Core operations
The SDK provides four asynchronous operations on SignicatOIDCClient.
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
persistSessionistrue.
To learn more about the OIDC configuration, see the Configuration reference section on the Android Set up the SDK page.
- Kotlin
- Java
viewModelScope.launch {
try {
val session = client.login()
val accessToken = session.accessToken
val idTokenClaims = session.idTokenClaims
} catch (error: SignicatOIDCException) {
handleError(error.errorCode)
}
}
client.login(new SignicatOIDCCallback<OIDCSession>() {
@Override
public void onSuccess(OIDCSession session) {
String accessToken = session.getAccessToken();
Map<String, ?> idTokenClaims = session.getIdTokenClaims();
}
@Override
public void onError(SignicatOIDCException error) {
handleError(error.getErrorCode());
}
});
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
persistSessionistrue. - Refreshes the access token if it has expired, so that the session it returns is always ready to use.
- Kotlin
- Java
viewModelScope.launch {
try {
val session = client.getSession()
showLoggedInScreen(session)
} catch (error: SignicatOIDCException) {
if (error.errorCode == SignicatOIDCException.ErrorCode.sessionNotFound) {
showLoginScreen()
} else {
handleError(error.errorCode)
}
}
}
client.getSession(new SignicatOIDCCallback<OIDCSession>() {
@Override
public void onSuccess(OIDCSession session) {
showLoggedInScreen(session);
}
@Override
public void onError(SignicatOIDCException error) {
if (error.getErrorCode() == SignicatOIDCException.ErrorCode.sessionNotFound) {
showLoginScreen();
} else {
handleError(error.getErrorCode());
}
}
});
Session properties
The table below lists the properties of OIDCSession:
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
UserInfoendpoint, which the SDK reads from the discovery document.
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.
- Kotlin
- Java
viewModelScope.launch {
try {
val userInfo = client.getUserInfo()
val subject = userInfo["sub"]
val userInfoClaims = userInfo.claims
} catch (error: SignicatOIDCException) {
handleError(error.errorCode)
}
}
client.getUserInfo(new SignicatOIDCCallback<UserInfo>() {
@Override
public void onSuccess(UserInfo userInfo) {
Object subject = userInfo.get("sub");
Map<String, ?> userInfoClaims = userInfo.getClaims();
}
@Override
public void onError(SignicatOIDCException error) {
handleError(error.getErrorCode());
}
});
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.
If the Signicat service logout fails, the local session is kept so you can retry.
- Kotlin
- Java
viewModelScope.launch {
try {
client.logout()
showLoginScreen()
} catch (error: SignicatOIDCException) {
handleError(error.errorCode)
}
}
client.logout(false, new SignicatOIDCCallback<Unit>() {
@Override
public void onSuccess(Unit ignored) {
showLoginScreen();
}
@Override
public void onError(SignicatOIDCException error) {
handleError(error.getErrorCode());
}
});
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.
client.logout(localOnly = true)
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.
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: