Skip to main content

Integration with OIDC

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

Note that you can also connect to itsme® using the Signicat Authentication REST API or SAML 2.0.

Add an OIDC client​

When you register an OIDC client application, you receive a client ID. To do this:

  1. In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > OIDC clients.
  2. Select Create/Add client.
  3. Enter a name for the client.
  4. In Primary grant type, select the grant type (authentication flow) to use for this client.
    Choosing a grant type

    The Authorization Code flow is recommended for most cases. Learn more about supported flows in the generic OIDC implementation guide and the OAuth 2.0 specification.

  5. In the Redirect URI field, enter the URL where to redirect the end-user after authentication. You can always edit and add more URIs later.
  1. In the Scope field, enter the scopes you want for this client. openid is mandatory.
    Scopes control the service

    To control which itsme® service to present to your end-users, you must select specific scopes in your OIDC client configuration. This guide shows you which scopes to use for each service.

  2. Click Create to create the OIDC client.

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.

Proof Key for Code Exchange (PKCE)

We strongly recommend using Proof Key for Code Exchange (PKCE), even when you are using a client secret. It is important that you always enforce PKCE when using the OIDC client in a frontend flow. Learn more in the PKCE documentation.

itsme® services with OIDC​

itsme® offers different scenarios to verify a person's digital identity. Signicat supports the following services/flows:

  • Authentication: to authenticate recurring end-users. Choose this to log in end-users securely to your application.
  • Identification: to identify and onboard new end-users. You can retrieve verified personal data.
  • Signing: available on request. To set it up, contact us.

OIDC scopes determine what service you start for the end-users. Below, you find instructions to implement each service. You can find more details about the scopes for each service in the Attributes reference documentation.

Authentication flow​

You can use the itsme® Authentication service to log in your end-users securely to your application (on web, tablet or mobile).

Build the request​

Scopes

The following scopes start an Authentication service flow:

  • name
  • openid (required scope)

For example, you can start an Authentication flow for your end-users by building the authorization request URL with the following scopes openid name:

https://<YOUR_DOMAIN>/auth/open/connect/authorize?
    client_id=<OIDC_CLIENT_ID>
    &response_type=code
    &redirect_uri=<REDIRECT_URI>
    &scope=openid%20name
    &acr_values=idp:itsme
    &prompt=login
ACR values

The acr_values=idp:itsme is optional but allows you to send the end-user directly to itsme®, therefore skipping the eID selection screen.

End-user authentication​

To authenticate with itsme®, the end-users need to consent to sharing their data (in the itsme® app) with your organisation. The consent screens looks similar to the image below:

Authentication with itsme: User data consent screen

Authentication with itsme: User data consent screen

Once the end-user confirms to sharing their personal data, the following happens:

  1. The end-user is redirected to the URL you configured in the redirect_uri (query parameter) of the request. Note that this should match the Redirect URI you configured in your OIDC client in the Signicat Dashboard.
  2. Then, you receive a server response with the access token and the ID token, in the body of the response.

Get the response​

An ID token is a JWT that looks like eyJhbGciOiJSUzI...AiOiJKV1QifQ.eyJpc3Mi...J1ZX0.nmupzTs...H9whojA.

The decoded payload (data) part of the ID token for itsme® would then look like:

{
  "iss": "https://<YOUR_DOMAIN>/auth/open",
  "nbf": 1710760018,
  "iat": 1710760018,
  "exp": 1710760618,
  "aud": "<OIDC_CLIENT_ID>",
  "amr": [
    "external"
  ],
  "at_hash": "PQw...4nw",
  "sid": "8437...690",
  "sub": "tXOq9...ytA=",
  "auth_time": 1710760017,
  "idp": "itsme",
  "name": "Maxence Legrand",
  "family_name": "Legrand",
  "given_name": "Maxence",
  "idp_issuer": "https://idp.e2e.itsme.services/v2",
  "transaction_id": "52f3497c-...-594c-...-13f229449925",
  "sandbox": true
}
ID Token

Note that ID Token is configured by default to return only the claims defined in the OIDC standard (standard scopes).

To control the claims returned in the ID Token, navigate to the Products > eID and Wallet Hub > OIDC clients page in the Dashboard, choose your client, then edit the ID Token User data under Advanced > Security.

Subject value (sub)

You can use the subject (sub) of the ID Token as the unique identifier for recurring end-users. This way you can log in your end-user the next time they want to access your service.

Mapping users with subject ID​

To successfully log in a given end-user to your web or mobile application, you need to map the user attributes you obtain in the response with a user account that you previously saved in your database.

By default, your application server should use the subject identifier (sub claim in the ID Token) to identify and verify a user account.

Subject

The sub claim is a string that uniquely identifies a user. The sub claim never changes over time, even if other user attributes (for example, email or phone number) change.

UserInfo response​

Response example with user information retrieved from the UserInfo endpoint.

{
  "name": "Maxence Legrand",
  "family_name": "Legrand",
  "given_name": "Maxence",
  "sub": "tXOq9...ytA=",
  "idp_issuer": "https://idp.e2e.itsme.services/v2"
}
Success

You have now completed an Authentication flow with itsme®.

Identification flow​

You can use the itsme® Identification service to identify the identity of the end-users and retrieve their personal data.

Build the request​

To start an Identification flow, you need to build the URL, as follows:

Scope: openid profile

https://<YOUR_DOMAIN>/auth/open/connect/authorize?
    client_id=<OIDC_CLIENT_ID>
    &response_type=code
    &redirect_uri=<REDIRECT_URI>
    &scope=openid%20profile
    &acr_values=idp:itsme
    &prompt=login
Scopes

openid is a required scope. Beyond that, your application can ask for additional scopes. All scopes must be space-separated.

Find out which scopes to use for Identification in the Attributes reference documentation.

ACR values

The acr_values=idp:itsme is optional but it allows you to redirect the end-user directly to itsme® therefore skipping the identity provider selection screen.

End-user identification​

To authenticate with itsme®, the end-users need to consent to sharing their data (in the itsme® app) with your organisation. The consent screens looks similar to the image below:

Identification with itsme: User data consent screen

Identification with itsme: User data consent screen

Once the end-user confirms to sharing their personal data, the following happens:

  1. The end-user is redirected to the URL you configured in the redirect_uri (query parameter) of the request. Note that this should match the Redirect URI you configured in your OIDC client in the Signicat Dashboard.
  2. Then, you receive a server response with the access token and the ID token, in the body of the response.

Get the response​

An ID token is a JWT that looks like eyJhbGciOiJSUzI...AiOiJKV1QifQ.eyJpc3Mi...J1ZX0.nmupzTs...H9whojA.

The decoded payload (data) part of the ID token for itsme® would then look like:

{
  "iss": "https://<YOUR_DOMAIN>/auth/open",
  "nbf": 1710759211,
  "iat": 1710759211,
  "exp": 1710759811,
  "aud": "<OIDC_CLIENT_ID>",
  "amr": [
    "external"
  ],
  "at_hash": "CWo...1Q",
  "sid": "843...690",
  "sub": "tXOq...ytA=",
  "auth_time": 1710759210,
  "idp": "itsme",
  "name": "Maxence Legrand",
  "family_name": "Legrand",
  "given_name": "Maxence",
  "gender": "female",
  "birthdate": "1981-04-24",
  "idp_issuer": "https://idp.e2e.itsme.services/v2",
  "transaction_id": "5a11d5ee-...-5e44-...-2628237a2241",
  "sandbox": true
}
ID Token

Note that ID Token is configured by default to return only the claims defined in the OIDC standard (standard scopes).

To control the claims returned in the ID Token, navigate to the Products > eID and Wallet Hub > OIDC clients page in the Dashboard, choose your client, then edit the ID Token User data under Advanced > Security.

Subject value (sub)

You can use the subject (sub) of the ID Token as the unique identifier for recurring end-users. This way you can log in your end-user the next time they want to access your service.

UserInfo response​

The response examples below show user information retrieved from the UserInfo endpoint.

{
  "name": "Maxence Legrand",
  "family_name": "Legrand",
  "given_name": "Maxence",
  "gender": "female",
  "birthdate": "1981-04-24",
  "sub": "tXOq...ytA=",
  "idp_issuer": "https://idp.e2e.itsme.services/v2"
}
Success

You have now completed an Identification service flow with itsme®.

Next steps​

Continue your journey with more itsme® guides:

Attributes reference
Scopes and claims for itsme® with OIDC
Go to production
Connect to itsme® in a production account

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 etc.
Advanced security considerations
Learn about advanced security measures like PKCE and encryption
On this page