Integration with OIDC
This page shows how to integrate with Email OTP using OpenID Connect (OIDC) as an authentication protocol.
Before you begin
Before starting your OIDC integration with Email 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 Hub > OIDC clients and select Create Client.
Configure the following settings:
- Client name: the name of the client. This is visible to your end-users.
- Primary Grant Type: the grant type (and respective OIDC authentication flow) you want to use with this client. We strongly recommend AuthorizationCode.
- Redirect URI: the URI where end-users are redirected at the end of the flow. It must be HTTPS and an absolute URI.
- Scope: control the attributes returned at the end of an authentication flow. Scopes can differ per eID.
For Email OTP, select the openid and idp-id scopes. Additionally, you can use the email scope, which returns the same email address 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:
- In the menu for the client, go to the Secrets tab and click Add secret.
- Enter a name for your client secret and click Create.
- Copy your new client secret and store it safely.
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.
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 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
In OIDC, the authorize endpoint is where end-user authentication occurs by connecting the end-user to the authorisation server, where the end-user logs in with an eID (and gives consent). Routing your end-users to the authorize endpoint displays 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
&ui_locales=LANGUAGE_TAG
&scope=OIDC_SCOPES
The authentication URL consist of two parts:
- The base URL
https://<SIGNICAT_ACCOUNT_DOMAIN>/auth/open/connect/authorizewhereSIGNICAT_ACCOUNT_DOMAINis the domain configured in your Signicat account. - The query parameters:
client_id: OIDC Client ID you created on Dashboard.redirect_uri: the URI where the end-user is redirected to at the end of the authentication flow.response_type: based on the response flow you set for the OIDC Client (this is an advanced feature).scope: OIDC scopes that determine the authentication flow.openidis a required parameter.ui_locales: (ISO 639-1 language tag) sets the language in the UI. By default, the UI language is English. For an overview of the languages supported, see the Attributes reference.
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
&ui_locales=en
&scope=openid%20idp-id%20email
Example of user journey
When end-users access the authentication URL, the user journey looks like this:
Set the UI language
To change the language on the Email OTP UI, use the query string parameter ui_locales in the OIDC authorization request. For example, use ui_locales=el to set the Email OTP UI to Greek.
By default, the UI language is English.
For an overview of the languages supported, see the Attributes reference.
Prefill user information
You can use the login_hint query parameter to prefill the email address of the end-user, so that the end-user does not have to enter their email manually when authenticating. For example, this applies to cases when you already know the email address.
To specify an email address in the authentication URL, pass login_hint=email:signikitten@example.com in your request:
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%20email
&ui_locales=en
&login_hint=email:signikitten@example.com
This will display the email address to the end-user when they start the authentication flow. To learn more about data prefilling, see the Prefilling user information conceptual guide.
For security reasons, we recommend you verify that the email address you receive in the response from Email OTP matches the email address you prefilled in the authentication URL.
Next steps
Continue your journey with more Email OTP guides:
Dive deeper into OIDC and improve your application with advanced security features: