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 iOS 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:

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. In the Signicat Dashboard, go to Products > eID and Wallet Hub > OIDC clients.
  2. Click + Add client.
  3. Enter or select the following values:
    PropertyDescription
    Primary Grant TypeAutomatically set to AuthorizationCode when you select Native/Mobile Application.
    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. In our Nexus repository, log in with your Nexus repository credentials, then download oidc-sdk-ios-<VERSION>.zip.
  2. Extract the .zip file, then drag SignicatOIDC.xcframework into your Xcode project and add it to your app target.
  3. In your app target's General tab, under Frameworks, Libraries, and Embedded Content, set SignicatOIDC.xcframework to Embed & Sign. This adds the SDK's privacy manifest to your app.
  4. Import the SDK in the files that use it:
    Example: Import SDK into relevant files
    import SignicatOIDC

The SDK contains AppAuth for iOS, so you do not need to add AppAuth or the -ObjC linker flag to your app.

3. Associate your app with the redirect domain​

Standard login runs in the system authentication browser, which returns to your app only if the host of your redirect URI lists your app under webcredentials in its apple-app-site-association file. To set this up:

  1. In Xcode, select your app target, go to Signing & Capabilities, then add the Associated Domains capability.
  2. Add a webcredentials: entry for the host of your redirect URI, for example webcredentials:example.com.

Verify your domain​

To verify your domain, the host must publish an apple-app-site-association file containing your app ID (<TEAM_ID>.<BUNDLE_ID>). The required entries in this file depend on your chosen login flow:

  • Standard login: Requires a webcredentials entry.
  • App-to-app flow: Requires both webcredentials and applinks entries. The applinks entry allows the identity provider's app to return the end-user to your app using a universal link. To learn more, see App-to-app flow.

How you publish this file depends on who manages your redirect domain:

Without the correct association, the login() operation fails before the browser opens, returning the authorizationFailed error code. Check the underlyingErrorDescription for the specific reason.

Important

iOS caches the apple-app-site-association file, so any changes can take time to reach devices where your app is already installed.

Test the association during development​

For a build signed with a development profile, you can make iOS read the association file directly from your redirect domain instead of from Apple's content delivery network:

  1. Add ?mode=developer to the entry, for example webcredentials:example.com?mode=developer.
  2. On your test device, go to Settings > Developer and turn on Associated Domains Development.
  3. Before you submit your app to the App Store, remove ?mode=developer from the entry.

4. Set the configuration​

You must set the configuration for SignicatOIDCClient.shared 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
    SignicatOIDCClient.shared.configuration = try OIDCConfiguration(
    issuer: URL(string: "https://<YOUR_SIGNICAT_DOMAIN>/auth/open")!,
    clientId: "<CLIENT_ID>",
    redirectUri: URL(string: "<REDIRECT_URI>")!
    )
    Optional settings

    The example omits scopes, so the SDK uses its default values, openid and offline_access.

    To learn about optional settings, see the Configuration reference section below.

The redirectUri must exactly match the redirect URI registered on your OIDC client, and its host must be the one that you associated with your app in step 3.

Change the configuration​

You should set the configuration once when your app launches, before you call getSession().

To switch configurations, for example to select an identity provider with acrValues, you need to set the new configuration immediately before you call login().

Changing the configuration removes the session

The SDK keeps one session for your configuration. Changing the configuration or setting it to nil removes the session.

Configuration reference​

The OIDCConfiguration object validates its values when you create it. Invalid values cause the initialiser to throw a SignicatOIDCError with the invalidConfiguration code.

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.