For the complete documentation index, see llms.txt. You can also append .md to any page URL to get its markdown version.
Skip to main content
For the complete documentation index, see llms.txt.

For the complete documentation index, see llms.txt

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:

Kotlin compatibility

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:

  1. Go to Signicat Dashboard > Products > eID and Wallet Hub > OIDC clients.
  2. Click the + Add client button.
  3. Enter or select the following values:
    PropertyDescription
    Primary Grant TypeThis is automatically set to AuthorizationCode when you select a template to create the client from.
    Create client from templateSelect Native/Mobile Application.
    Client nameEnter a name for the client.
    Redirect URIAdd 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.
  4. When prompted to add a secret, click Skip. The SDK uses PKCE instead of a client secret.
Want to learn more?

To learn more about OIDC clients, see the following links:

2. Add the SDK to your app​

  1. Set your Nexus repository login credentials in $HOME/.gradle/gradle.properties:
    Example: Set your Nexus repository login credentials
    mavenUser=<YOUR_NEXUS_REPOSITORY_USER_ID>
    mavenPassword=<YOUR_NEXUS_REPOSITORY_PASSWORD>
  2. Add the Signicat OIDC SDK repository to your project's configuration:
    Example: Add the Signicat repository in settings.gradle.kts
    dependencyResolutionManagement {
    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()
    }
    }
    }
    }
  3. Add the SDK as a dependency in your app module's build file:
    Example: Add the OIDC SDK as a dependency in build.gradle.kts
    dependencies {
    implementation("com.signicat:oidc-sdk-android:1.0.1")
    }
Transitive runtime dependencies

The SDK includes its own transitive runtime dependencies, including AppAuth for Android and AndroidX Browser. You do not need to declare them yourself.

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).

Match the redirect URI

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:

Example: Declare the redirect host and path
android {
defaultConfig {
manifestPlaceholders["signicatOidcRedirectUriHost"] = "example.com"
manifestPlaceholders["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:

Debug signing certificate

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.

Google Play App Signing

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:

  1. Add AppAuth as a dependency of your app module so you can reference its Activity in your own manifest:
    Example: Add AppAuth as a dependency in build.gradle.kts
    dependencies {
    implementation("net.openid:appauth:0.11.1")
    }
  2. Override RedirectUriReceiverActivity in your app's AndroidManifest.xml, with one intent filter per redirect URI:
    Example: Declare multiple redirect App Links
    <activity
    android: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" />

    <data
    android: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" />

    <data
    android:host="another.example.com"
    android:path="/redirect/response"
    android:scheme="https" />
    </intent-filter>
    </activity>
Replace the complete receiver declaration
  • 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.

Configure the client before use

If you call an operation before setting a configuration, then it fails with error code notConfigured.

  1. Gather the following values:

    • Issuer (issuer)
    • Client ID (clientId)
    • Redirect URI (redirectUri)
  2. Replace the example values below with your own:

    Example: Configure the client
    val 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"),
    )
    Optional settings

    Both examples explicitly set scopes to openid and offline_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:

Request a refresh token

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.