# 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.

Page contents

Add an OIDC client
itsme® services with OIDC
- OIDC flow for Authentication
- OIDC flow for Identification
Next steps

# Add an OIDC client

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

In the Signicat Dashboard, go to eID Hub > OIDC clients (opens new window) and select Create/Add client.
Enter a name for the client.
In Primary grant type, select which grant type you want to use with this client. We strongly recommend AuthorizationCode. For further information about the different grant types, refer to the OIDC specification (opens new window) and the OAuth 2.0 specification (opens new window).
In the Redirect URI field, enter the URL that you want to redirect your end-user to when the authentication process is finished. Note that if you want to use more than one redirect URI, you can still add them after the client has been created.
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.
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:

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.

Important

Make sure you save your client secret. You will only be able to view your client secret once, right after you create it. Therefore, it is important that you copy it and store it safely so that you can retrieve it later on. If you ever forget it or lose it, you have to create a new one.

Note that if you intend to use the OIDC client in a frontend flow, then you always need to 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.

# itsme® services with OIDC

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

Authentication: to authenticate recurring end-users. Use this to log in end-users securely to your application.
Identification: to identify, onboard end-users and access their verified data.
Signing: for more information, contact us (opens new window).

OIDC scopes allow you to control which service to initiate and present to your end-users. You can learn more about the scopes for each service in the Attributes reference documentation.

Below, you find instructions to trigger each service.

# OIDC flow for Authentication

The itsme® Authentication service enables your end-users to log in securely to your application (on web, tablet or mobile).

# Build the request

Scopes

The following scopes start an Authentication service flow:

name
email
openid (required scope)

For example, you can trigger Authentication service for your end-users by building the authorization request URL with the following scopes openid email:

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

ACR values

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

# End-user authentication

To authenticate with itsme®, end-users must consent to share their data with you through the itsme® app:

itsme itsme authentication click-to-zoom

After the end-user clicks Confirm:

The end-user is redirected to the URL you configured in the redirect_uri query parameter of the request. The value should match the Redirect URI you configured in your OIDC client.
You receive a server response with an access token and an 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",
  "email": "test@itsme.be",
  "email_verified": false,
  "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 data returned in the ID Token, edit the Id Token User data in the Advanced > Security tab of your OIDC client configuration in the Signicat Dashboard.

Subject value (sub)

You can use the subject (sub) of the ID Token as the unique identifier of the corresponding end-user.

# Mapping users with subject ID

To successfully sign in a given end-user to your web desktop, mobile web or mobile application, you must map the user attributes you obtain in the response with a user account 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.

The sub claim is a string that uniquely identifies a given user account. The benefit of using a sub claim is that it does not change over time, even if other user attributes (for example email or phone number) associated with that user account are updated.

# UserInfo response

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

{
  "email": "test@itsme.be",
  "email_verified": false,
  "sub": "tXOq9...ytA=",
  "idp_issuer": "https://idp.e2e.itsme.services/v2"
}

Success

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

# OIDC flow for Identification

The itsme® Identification service enables you to identify your end-users and access their verified data.

# Build the request

To trigger an end-user Identification request to itsme® with OIDC, build the URL using:

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

ACR values

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

Scopes

All scope values must be space-separated. The basic (and required) scope is openid. Beyond that, your application can ask for additional scopes.

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

# End-user identification

To identify with itsme®, end-users must consent to share their data with you through the itsme® app:

itsme identification click-to-zoom

After the end-user clicks Confirm:

The end-user is redirected to the URL you configured in the redirect_uri query parameter of the request. The value should match the Redirect URI you configured in your OIDC client.
You receive a server response with an access token and an 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

Subject value (sub)

You can use the subject (sub) of the ID Token as the unique identifier of the corresponding end-user.

# 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

← Initial preparations Attributes reference →