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:
- In the Signicat Dashboard, go to Products > eID and Wallet Hub > OIDC clients.
- Click + Add client.
- Enter or select the following values:
Property Description Primary Grant Type Automatically set to AuthorizationCode when you select Native/Mobile Application. Create client from template Select Native/Mobile Application. Client name Enter a name for the client. Redirect URI Add 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. - When prompted to add a secret, click Skip. The SDK uses PKCE instead of a client secret.
To learn more about OIDC clients, see the following links:
2. Add the SDK to your app
- In our Nexus repository, log in with your Nexus repository credentials, then download
oidc-sdk-ios-<VERSION>.zip. - Extract the
.zipfile, then dragSignicatOIDC.xcframeworkinto your Xcode project and add it to your app target. - In your app target's General tab, under Frameworks, Libraries, and Embedded Content, set
SignicatOIDC.xcframeworkto Embed & Sign. This adds the SDK's privacy manifest to your app. - Import the SDK in the files that use it:
Example: Import SDK into relevant filesimport 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:
- In Xcode, select your app target, go to Signing & Capabilities, then add the Associated Domains capability.
- Add a
webcredentials:entry for the host of your redirect URI, for examplewebcredentials: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
webcredentialsentry. - App-to-app flow: Requires both
webcredentialsandapplinksentries. Theapplinksentry 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.
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:
- Add
?mode=developerto the entry, for examplewebcredentials:example.com?mode=developer. - On your test device, go to Settings > Developer and turn on Associated Domains Development.
- Before you submit your app to the App Store, remove
?mode=developerfrom the entry.
4. Set the configuration
You must set the configuration for SignicatOIDCClient.shared before calling any operations.
If you call an operation before setting a configuration, then it fails with error code notConfigured.
-
Gather the following values:
- Issuer (
issuer) - Client ID (
clientId) - Redirect URI (
redirectUri)
- Issuer (
-
Replace the example values below with your own:
Example: Configure the clientSignicatOIDCClient.shared.configuration = try OIDCConfiguration(issuer: URL(string: "https://<YOUR_SIGNICAT_DOMAIN>/auth/open")!,clientId: "<CLIENT_ID>",redirectUri: URL(string: "<REDIRECT_URI>")!)Optional settingsThe example omits
scopes, so the SDK uses its default values,openidandoffline_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().
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:
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.