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

Configure the client before use

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 OIDCSession and stores it encrypted in the Keychain if persistSession is true.
Want to learn more?

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.

Example: Log in
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 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
// 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:

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

Example: Fetch user info
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.
Retry a failed logout

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

Example: Log out
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.

Example: Remove the local session without contacting the Signicat service
try await SignicatOIDCClient.shared.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 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.
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 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 call logout(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: