Skip to main content

Setup of Email OTP

With the Signicat Email OTP service, you can perform email-based user authentication.

Integration with Email OTP is done similarly to other Signicat's eID methods. This page describes how to set up Email OTP on the Signicat Dashboard

For more general information on how to integrate with Signicat, see the Quick start guide.

Initial preparations

This setup guide assumes you have completed the following initial preparations:

Sandbox account

We recommend you to create a sandbox account to test our services before implementing them in production.

Add Email OTP

To use an ID method, you first need to activate it. In the Signicat Dashboard:

  • Go to eID Hub > ID Methods.
  • Select Add new.
  • Choose Email OTP from the list of ID methods.
  • Optional. Customise the email subject and body to unify the user experience with your brand.
    Email OTP page

    Email OTP page

  • Click Add to save and activate Email OTP in your account.

Email OTP should now appear in the list of available ID methods with the status set to "Active".

Customise email service settings

When using the Signicat Email OTP service to send OTP codes to end-users, the service inherits the email settings configured in the Signicat Communication service.

On the Communication > Email, you can manage the email settings for your account. In particular, you can customise:

  • The email sender name
  • The email domain name ({from_address_prefix}@{domain_name})
  • The email address prefix

By default, the email sender name is set to "Signicat" and the email domain, and address prefix, is set to noreply@email.signicat.com. Alternatively, you can set up your custom SMTP server or use your own custom email domain.

Find out more about setting custom email settings in the Communication service documentation.

Select protocol and configure ID method

To establish a connection between Signicat Email OTP service and your application, you need to use an authentication protocol, like OpenID Connect (OIDC) or SAML 2.0. We recommend using OIDC, since SAML 2.0 is much more complex to implement on your side and usually requires a federation agent already in place.

Alternatively, you can integrate with Signicat Authentication REST API. You can find more information on the different types in the Authentication protocols section.


OIDC configuration

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

Create an OIDC client

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

Configure the following settings:

  • Client name: the name of the client. End-users can view this name in the authentication flow.
  • 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 ID method.
Email OTP scope

For Email OTP, select the openid and idp-id scopes.

For example:

OIDC client configuration

OIDC client configuration

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

Create a client secret

After you create an OIDC client, you can add a secret associated to the client.

Select Add secret and enter a name to generate a secret. You can view and add more secrets in the "Secrets" tab of your OIDC client.

Save your client secret

Make sure you save your client secret. You will only be able to view your client secret once - when you create it. If you ever lose it, you have to create a new one.

OIDC implementation

Example of authentication request

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 logs in with a service provider (and gives consent). This is 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

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: 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. openid is a required parameter.
Matching configuration

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

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

Example of user journey

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

login_hint (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 this information manually when authenticating.

For example, you can specify an email address in the authentication URL with login_hint=email:signikitten@example.com :

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
&login_hint=email:signikitten@example.com

This will display the email address to the end-user when they start the authentication flow.

Attributes and claims

For an overview of the attributes returned by Email OTP, see the Scopes and claims mapping for OIDC.

Full integration with OIDC

Learn more about OIDC flows, claims and endpoints in the OIDC documentation

If you are ready to integrate OIDC with your application, follow the Code example.