Set up the SDK
Add the Signicat OIDC SDK to your Android app, configure the redirect URI and set the OIDC client configuration.
Prerequisites
Before you start, ensure that you meet the following prerequisites:
Development environment
Your development environment must meet the following requirements:
The Kotlin binary format is often compatible with the next Kotlin language release, but not later releases.
Although this means that the minimum supported Kotlin language version is generally one version earlier (for example, 2.2), we cannot guarantee compatibility.
Setup and credentials
You must meet the following requirements for your Signicat account setup and credentials:
1. Set up your OIDC client
The SDK expects a public OIDC client that uses Proof Key for Code Exchange (PKCE) and an HTTPS redirect URI. Signicat offers an OIDC client template with the correct configuration for native apps.
To create an OIDC client for native apps using this template:
- Go to Signicat Dashboard > Products > eID and Wallet Hub > OIDC clients.
- Click the + Add client button.
- Enter or select the following values:
Property Description Primary Grant Type This is automatically set to AuthorizationCode when you select a template to create the client from. Create client from template Select Native/Mobile Application. Client name Enter a name for the client. Redirect URI Add your redirect URI to the client. It must be an absolute HTTPS URI without a fragment, on a domain you control or one managed by Signicat. - When prompted to add a secret, click Skip. The SDK uses PKCE instead of a client secret.
To learn more about OIDC clients, see the following links:
2. Add the SDK to your app
- Set your Nexus repository login credentials in
$HOME/.gradle/gradle.properties:Example: Set your Nexus repository login credentialsmavenUser=<YOUR_NEXUS_REPOSITORY_USER_ID>mavenPassword=<YOUR_NEXUS_REPOSITORY_PASSWORD> - Add the Signicat OIDC SDK repository to your project's configuration:
- Gradle (Kotlin)
- Gradle (Groovy)
Example: Add the Signicat repository in settings.gradle.ktsdependencyResolutionManagement {repositories {google()mavenCentral()maven {url = uri("https://nexus.pub.encap.no/content/repositories/oidc-sdk")credentials {username = providers.gradleProperty("mavenUser").get()password = providers.gradleProperty("mavenPassword").get()}}}}Example: Add the Signicat repository in settings.gradledependencyResolutionManagement {repositories {google()mavenCentral()maven {url "https://nexus.pub.encap.no/content/repositories/oidc-sdk"credentials {username mavenUserpassword mavenPassword}}}} - Add the SDK as a dependency in your app module's build file:
- Gradle (Kotlin)
- Gradle (Groovy)
Example: Add the OIDC SDK as a dependency in build.gradle.ktsdependencies {implementation("com.signicat:oidc-sdk-android:1.0.1")}Example: Add the OIDC SDK as a dependency in build.gradledependencies {implementation "com.signicat:oidc-sdk-android:1.0.1"}
The SDK includes its own transitive runtime dependencies, including AppAuth for Android and AndroidX Browser. You do not need to declare them yourself.
3. Configure the redirect App Link
The SDK registers the redirect receiver in its own manifest, but requires the host and path of your redirect URI.
You must supply these values as manifest placeholders in your app module's build file (build.gradle or build.gradle.kts).
The values must match the redirectUri in your OIDCConfiguration and the redirect URI registered on your OIDC client. The path is matched exactly.
For example:
- Gradle (Kotlin)
- Gradle (Groovy)
android {
defaultConfig {
manifestPlaceholders["signicatOidcRedirectUriHost"] = "example.com"
manifestPlaceholders["signicatOidcRedirectUriPath"] = "/redirect/response"
}
}
android {
defaultConfig {
manifestPlaceholders = [
signicatOidcRedirectUriHost: "example.com",
signicatOidcRedirectUriPath: "/redirect/response"
]
}
}
Verify your domain
To verify your domain, the host must publish a Digital Asset Links file containing your app ID and the SHA-256 fingerprint of your app's signing certificate.
This file must be available at https://<your-domain>/.well-known/assetlinks.json. The verification allows the authentication redirect to seamlessly open your app instead of staying in the browser.
How you publish this file depends on who manages your redirect domain:
For testing, check that the Digital Asset Links file includes the SHA-256 fingerprint of the certificate used to sign your debug build.
Otherwise, App Link verification fails during development, and the redirect opens in the browser instead of returning to your app.
If you use Google Play App Signing, use the SHA-256 fingerprint of the app signing certificate from the Play Console in the Digital Asset Links file.
Optional: Support multiple redirect URIs
The manifest placeholders described in Configure the redirect App Link declare a single redirect URI.
If your app needs multiple redirect URIs (for example, a different redirect URI per OIDC client configuration), you can declare the receiver Activity yourself. To do this:
- Add AppAuth as a dependency of your app module so you can reference its Activity in your own manifest:
- Gradle (Kotlin)
- Gradle (Groovy)
Example: Add AppAuth as a dependency in build.gradle.ktsdependencies {implementation("net.openid:appauth:0.11.1")}Example: Add AppAuth as a dependency in build.gradledependencies {implementation "net.openid:appauth:0.11.1"} - Override
RedirectUriReceiverActivityin your app'sAndroidManifest.xml, with one intent filter per redirect URI:Example: Declare multiple redirect App Links<activityandroid:name="net.openid.appauth.RedirectUriReceiverActivity"android:exported="true"tools:node="replace"><intent-filter android:autoVerify="true"><action android:name="android.intent.action.VIEW" /><category android:name="android.intent.category.DEFAULT" /><category android:name="android.intent.category.BROWSABLE" /><dataandroid:host="example.com"android:path="/redirect/response"android:scheme="https" /></intent-filter><intent-filter android:autoVerify="true"><action android:name="android.intent.action.VIEW" /><category android:name="android.intent.category.DEFAULT" /><category android:name="android.intent.category.BROWSABLE" /><dataandroid:host="another.example.com"android:path="/redirect/response"android:scheme="https" /></intent-filter></activity>
- List every redirect URI your app uses. Because
tools:node="replace"replaces the SDK's declaration entirely, the manifest placeholders no longer affect which links your app receives. - Use a separate intent filter for each redirect URI. Multiple
<data>elements in one filter match every combination of the hosts and paths they declare, which can make your app accept links you did not intend. - Each host needs its own Digital Asset Links file, as described in Verify your domain.
4. Set the configuration
You must set the configuration for SignicatOIDCClient before calling any operations.
If you call an operation before setting a configuration, then it fails with error code notConfigured.
-
Gather the following values:
- Issuer (
issuer) - Client ID (
clientId) - Redirect URI (
redirectUri)
- Issuer (
-
Replace the example values below with your own:
- Kotlin
- Java
Example: Configure the clientval client = SignicatOIDCClient.getInstance(applicationContext)client.configuration = OIDCConfiguration(issuer = "https://example.com/issuer".toUri(),clientId = "your-client-id",redirectUri = "https://example.com/redirect/response".toUri(),scopes = setOf("openid", "offline_access"),)Example: Configure the clientSignicatOIDCClient client = SignicatOIDCClient.getInstance(context);OIDCConfiguration configuration = new OIDCConfiguration(Uri.parse("https://example.com/issuer"),"your-client-id",Uri.parse("https://example.com/redirect/response"),new HashSet<>(Arrays.asList("openid", "offline_access")));client.setConfiguration(configuration);Optional settingsBoth examples explicitly set
scopestoopenidandoffline_access, which are also the default values.To learn about optional settings, see the Configuration reference section below.
Configuration reference
The OIDCConfiguration object validates its values when you create it. Invalid values result in an error with the code invalidConfiguration.
Required properties
The following properties are required and must be set:
Optional properties
The following properties are optional and can be used to customise the behaviour of the authentication flow:
Keep offline_access in scopes if you want the SDK to automatically refresh an expired access token when you call getSession() or getUserInfo(). Without a refresh token, an expired session fails with the sessionExpired error code and the end-user has to log in again.