Integration with OIDC

This page shows how to integrate with SMS OTP using OpenID Connect (OIDC) as an authentication protocol.

Before you begin

Before starting your OIDC integration with SMS OTP, make sure you have configured your Signicat account.

Add an OIDC client

To integrate with OIDC, you need to obtain an OIDC client and a secret in the Signicat Dashboard.

To create a new OIDC client in the Signicat Dashboard, navigate to Products > eID and Wallet Hub > OIDC clients and select Create Client.

Configure the following settings:

• Client name: Name of the client. End-users can view this name in an authentication flow.
• Primary Grant Type: Grant type (and respective OIDC authentication flow) you want to use with this client. We strongly recommend AuthorizationCode.
• Redirect URI: URI where end-users are redirected at the end of the flow. It must be HTTPS and an absolute URI.
• Scope: Controls the attributes returned at the end of an authentication flow. Scopes can differ per eID.

SMS OTP scope

For SMS OTP, select the openid and idp-id scopes. Additionally, you can use the phone scope, which returns the same phone number as idp-id.

For example:

OIDC client configuration

For more details on how to configure an OIDC client, view the Set up an OIDC client guide.

Add a client secret

Depending on the type of your application, you may want to add a client secret. To do this:

1. In the menu for the client, go to the Secrets tab and click Add secret.
2. Enter a name for your client secret and click Create.
3. Copy your new client secret and store it safely.

Important

Make sure you copy and store your client secret securely. You can view your client secret only once, when you create it. If you ever lose your secret, you must create a new one.

PKCE

Note that if you intend to use the OIDC client in a frontend flow, then you must always use Proof Key for Code Exchange (PKCE). We strongly recommend using PKCE, even when you are using a client secret. Learn more about PKCE in the eID and Wallet Hub documentation.

OIDC implementation

In OIDC, an application first needs to specify which permissions to request, then send the end-user to a browser to get their permission. After the end-user approves the authentication request and gets redirected to your website, your application receives back an authorisation code. You exchange the authorisations code for an access token and an ID token, where you can find the end-user personal information.

Example of authentication request

To begin the authorization flow, your application should build an authentication URI that the end-user can open in a browser to start an authentication flow with SMS OTP.

In OIDC, the authorize endpoint performs the authentication of the end-user. It directs the end-user to the authorisation server, where the end-user enters their mobile number to receive an SMS with a one-time token. The authorization URL corresponds to a webpage where the authentication flow begins.

Here is how to build an authentication URL:

https://<SIGNICAT_ACCOUNT_DOMAIN>/auth/open/connect/authorize?
    &client_id=OIDC_CLIENT_ID
    &response_type=GRANT_TYPE_CODE
    &redirect_uri=REDIRECT_URI
    &scope=OIDC_SCOPES
    &ui_locales=LANGUAGE_TAG
    &state=STATE

The authentication URL consist of two parts:

• The base URL https://<SIGNICAT_ACCOUNT_DOMAIN>/auth/open/connect/authorize where SIGNICAT_ACCOUNT_DOMAIN is the domain configured in your Signicat account.
• The query parameters:
  • client_id: The client ID of your OIDC application that you created in the Dashboard.
  • redirect_uri: The URI where the end-user is redirected to at the end of the authentication flow. This must be an absolute URI using the HTTPS protocol.
  • response_type: Specifies the desired grant type for the OIDC flow.
  • state: A randomly generated string used to maintain the state between the request and the callback. It helps mitigate CSRF attacks by ensuring the returned value matches the one sent in the initial request.
  • scope: A space-separated list of permissions that the application requests, determining which claims are returned after a successful OIDC flow. For SMS OTP, use openid, idp-id and optionally phone.
  • ui_locales: (ISO 639-1 code) sets the language in the UI. By default, the language is English. For an overview of the languages supported, see the UI language page.

Matching configuration

The query parameters in the URL must match the configuration of your OIDC client in the Dashboard.

Here is an example authentication URL for an authorization code flow:

https://example.sandbox.signicat.com/auth/open/connect/authorize?
    &client_id=dev-test-client-123
    &response_type=code
    &redirect_uri=https://example.com/callback
    &scope=openid%20idp-id%20phone
    &ui_locales=en
    &state=1713343316409-zie

Example of user journey

When end-users access the authentication URL, the user journey looks like this:

Previous

1/7

Next

Set the UI language

To change the language on the SMS OTP UI, use the query string parameter ui_locales in the OIDC authorization request. For example, use ui_locales=el to set the SMS OTP UI to Greek.

Default language

By default, the UI language is English.

For an overview of the languages supported, see the UI language page.

Prefill user information

You can use the login_hint query parameter to prefill the phone number of the end-user, so that the end-user does not have to enter this information manually when authenticating.

For example, you can specify a phone number in the authentication URL with login_hint=mobile:%2B447700900000 :

https://example.sandbox.signicat.com/auth/open/connect/authorize?
&client_id=dev-test-client-123
&response_type=code
&redirect_uri=https://example.com/callback
&scope=openid%20idp-id%20phone
&login_hint=mobile:%2B447700900000

This will display the phone number to the end-user when they start the authentication flow. To learn more about data prefilling, see the Prefilling user information conceptual guide.

login_hint field format

Note that the phone number format must be %2B<COUNTRY_CODE><PHONE_NUMBER>. For example, use the URL encoded (percent encoding) %2B447700900000 string to represent the +44 7700900000 phone number.

ACR values

In OIDC, acr_values are a space-separated list of key-value pairs to customise the authentication flow. Signicat defined a set of custom keys that help you control specific features of an authentication flow.

Customise SMS sender name

To override the SMS sender name displayed to the recipient on a request basis, use otp_sms_sender:YOUR_SENDER_NAME. The value cannot contain spaces; use a double underscore instead. For example otp_sms_sender:Signicat__AS, displays "Signicat AS" as the SMS sender name.

Example of an authorization request with acr_values:

https://example.sandbox.signicat.com/auth/open/connect/authorize?
    &client_id=dev-test-client-123
    &response_type=code
    &redirect_uri=https://example.com/callback
    &scope=openid%20idp-id%20phone
    &acr_values=idp:otp-sms%20otp_sms_sender:Signi__Kitten

IdP scoping

To automatically redirect the end-user to SMS OTP, thus skipping the eIDs selection screen, use idp:otp-sms. This prevents users from choosing other eIDs that may be active in your account.

Advanced security

To protect your implementation from fraudulent attacks, make sure you follow the security recommendations in the Security measures page.

Next steps

Continue your journey with more SMS OTP guides:

Attributes reference

Scopes and claims for SMS OTP with OIDC

Dive deeper into OIDC and improve your application with advanced security features:

Advanced OIDC implementation

Learn about available flows, endpoints, claims, key rotation, security, error codes and more.

Code examples

Follow along a code example with OIDC