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

Core operations

The SDK provides four asynchronous operations on SignicatOIDCClient.

Configure the client before use

You must set the configuration for your OIDC client before calling any of the operations. If you do not do this, then the operation will fail with the notConfigured error code.

Overview​

For an overview of the SDK operations, see the table below. You can learn how to use each operation in the sections that follow.

Choose an API style​

Every operation has a callback-based method that takes a SignicatOIDCCallback<T>. Kotlin callers can use the suspending equivalents instead, which are extension functions on SignicatOIDCClient.

Callbacks are invoked exactly once, on Android's main thread. You should use the style that matches your app:

The examples on this page show the Coroutines API for Kotlin and the Callbacks API for Java.

Log in​

The login() operation does the following:

  • Removes any existing session for the configured issuer and client ID.
  • Reads the Signicat service metadata from the discovery document.
  • Opens the authorisation request in a supported browser.
  • Handles the redirect and exchanges the authorisation code for tokens.
  • Saves the new session and stores it encrypted on the device if persistSession is true.
Want to learn more?

To learn more about the OIDC configuration, see the Configuration reference section on the Android Set up the SDK page.

Example: Log in with coroutines
viewModelScope.launch {
try {
val session = client.login()
val accessToken = session.accessToken
val idTokenClaims = session.idTokenClaims
} catch (error: SignicatOIDCException) {
handleError(error.errorCode)
}
}

Read the session​

A successful login() returns an OIDCSession. To get the session later, you can call getSession() instead of logging in again. To also restore the session after the app restarts, set persistSession to true.

The getSession() operation does the following:

  • Retrieves the active session. After an app restart, it reads the session from encrypted storage if persistSession is true.
  • Refreshes the access token if it has expired, so that the session it returns is always ready to use.
Example: Read the active session
viewModelScope.launch {
try {
val session = client.getSession()
showLoggedInScreen(session)
} catch (error: SignicatOIDCException) {
if (error.errorCode == SignicatOIDCException.ErrorCode.sessionNotFound) {
showLoginScreen()
} else {
handleError(error.errorCode)
}
}
}

Session properties​

The table below lists the properties of OIDCSession:

Tokens are credentials

Do not log token values or copy them into shared storage, analytics or crash reports.

To keep the session after the app restarts, set persistSession to true instead of storing the tokens yourself.

Fetch user info​

The getUserInfo() operation does the following:

  • Refreshes the access token, if it has expired.
  • Calls the Signicat service's UserInfo endpoint, which the SDK reads from the discovery document.
Do not send claims to your backend

Call getUserInfo() from the app if you only want to display information.

If your backend needs the user information, then it should call the UserInfo endpoint itself using the access token. Data sent from the app can be modified before it reaches your backend, so the backend should not trust it.

Example: Fetch user info with coroutines
viewModelScope.launch {
try {
val userInfo = client.getUserInfo()
val subject = userInfo["sub"]
val userInfoClaims = userInfo.claims
} catch (error: SignicatOIDCException) {
handleError(error.errorCode)
}
}

Claims​

The claims you receive depend on:

  • The scopes you requested.
  • The eID that the end-user chose.

The returned claim values are plain JSON types: String, Boolean, Long, Double, List, nested Map, or null.

Log out​

By default, the logout() operation does the following:

  • Performs logout by posting the ID token to the Signicat service's end-session endpoint, without opening a browser.
  • Removes the local session only after the Signicat service accepts the request.
Retry a failed logout

If the Signicat service logout fails, the local session is kept so you can retry.

Example: Log out with coroutines
viewModelScope.launch {
try {
client.logout()
showLoginScreen()
} catch (error: SignicatOIDCException) {
handleError(error.errorCode)
}
}

Clear the local session only​

To skip the Signicat service request and remove the local session immediately, pass localOnly = true.

For example, you can use this to remove the local session after a failed login and you want to remove the session from the device anyway, or when you have already ended the Signicat service session using another method.

Example: Remove the local session without contacting the Signicat service
client.logout(localOnly = true)
Single sign-on

A local-only logout leaves the session at the Signicat service active.

If the Signicat service still has a valid SSO session, the next login() can complete without the end-user re-authenticating, unless you set promptLogin to true.

Session persistence​

By default, the SDK keeps the session in memory only. The session is available until the app process ends, after which the end-user has to log in again.

To restore the session after the app restarts, set persistSession to true in your configuration. The SDK then handles session storage for you. This means that stored sessions are:

  • Encrypted with a key stored in the Android Keystore.
  • Stored in app-private storage.
  • Isolated per issuer and client ID.
  • Excluded from device backups.
  • Removed when the end-user logs out, or when the session is accessed after it has expired.
Assess the risk before you persist sessions

A stored session includes the access, refresh and ID tokens.

You should only set persistSession to true if your app needs to restore the Signicat OIDC session, and after you have assessed the risk of keeping these tokens on the device.

If you change persistSession from true to false, the SDK deletes the stored session the next time it accesses the session.

Token refresh​

The getSession() and getUserInfo() operations refresh the access token when it expires.

To learn how the SDK responds to different refresh scenarios, see the table below: