Core operations
The SDK provides four asynchronous operations on SignicatOIDCClient.shared.
You must set the configuration for your OIDC client before calling any 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.
Error handling
Every operation is an async method that throws a SignicatOIDCError when it fails. The client runs on the main actor, so call it from the main actor, for example from a SwiftUI view or a @MainActor view model.
To learn how to respond to failures, see Error handling.
Log in
The login() operation does the following:
- Removes the local session.
- Reads the Signicat service metadata from the discovery document.
- Opens the authorisation request in the system authentication browser.
- Handles the redirect and exchanges the authorisation code for tokens.
- Returns the new
OIDCSessionand stores it encrypted in the Keychain ifpersistSessionistrue.
To learn more about the OIDC configuration, see the Configuration reference section on the iOS Set up the SDK page.
Before the browser opens, iOS asks the end-user to allow your app to sign in with the Signicat domain.
do {
let session = try await SignicatOIDCClient.shared.login()
showLoggedInScreen(session)
} catch {
handleError(error)
}
If the end-user declines the iOS prompt or closes the browser, login() fails with the authorizationCancelled error code.
By default, the SDK shows the login from the top view controller of your app's active window.
To use a specific view controller, for example in an app with multiple windows, pass the view controller to login(presenting:). The view controller must be visible and must not already present another view controller.
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 restores the session from the Keychain if
persistSessionistrue. - Refreshes the access token if it has expired, so that the session it returns is always ready to use.
// Use the configuration that you logged in with.
SignicatOIDCClient.shared.configuration = configuration
do {
let session = try await SignicatOIDCClient.shared.getSession()
showLoggedInScreen(session)
} catch let error as SignicatOIDCError where error.code == .sessionNotFound {
showLoginScreen()
} catch {
handleError(error)
}
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 user information, 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.
do {
let userInfo = try await SignicatOIDCClient.shared.getUserInfo()
let subject = userInfo["sub"] as? String
} catch {
handleError(error)
}
Claims
The claims you receive depend on:
- The scopes you requested.
- The eID that the end-user chose.
The returned claim values are JSON values decoded by JSONSerialization, so you should cast them to the type you expect.
Log out
By default, the logout() operation does the following:
- Performs logout by sending 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.
do {
try await SignicatOIDCClient.shared.logout()
showLoginScreen()
} catch {
handleError(error)
}
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.
try await SignicatOIDCClient.shared.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 and stored in the Keychain.
- Isolated per issuer and client ID.
- Available after the device's first unlock following a restart, including while the device is locked.
- Kept on the device and not transferred to a new device through a backup.
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 any session that an earlier launch stored for the same issuer and client ID.
The SDK removes the session, including any stored copy, in the following cases:
logout()succeeds, or you calllogout(localOnly: true).login()starts.- You change the configuration, or set it to
nil. - The SDK cannot decrypt the stored session. The operation fails with
secureStorageError. - The end-user deletes and reinstalls your app.
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: