For the complete documentation index, see llms.txt

OpenID Connect

This guide shows you how to implement a connection with OpenID Connect (OIDC) for the EUDI Wallet.

Before you begin

Before starting your OIDC integration, ensure to complete the steps to Configure identity wallets.

Add an OIDC client

An OIDC client allows your application to authenticate users with the EUDI Wallet using standardised, secure OAuth 2.0 protocols.

For the complete documentation index, see llms.txt

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.

6. In the Scope field, enter the scopes you want for this client. openid is mandatory. Find out what scopes are supported in the Attributes reference.

   OIDC scope configuration

   Scopes encode what personal information you request from your end-users' wallets.

   You can retrieve specific identity data like Person Identification Data (PID) by specifying the appropriate scopes in your request.

7. Select 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 your client, go to the Secrets tab and select Add secret.
2. Enter a name for your client secret and select 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

We strongly recommend using PKCE, even when you are using a client secret. 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).

Learn more about PKCE in the eID and Wallet Hub documentation.

OIDC authentication flow

The steps on this guide explain how to build your application for authentication flows with the EUDI Wallet using a cross-device redirect flow. This flow starts on a desktop application and completes on the user's mobile device where their wallet app is active.

Supported flows

Same-device redirect flow (where the entire authentication occurs on a mobile phone) is not supported yet. Users must initiate the authentication flow on a PC browser and complete it on their mobile phone.

Overview of cross-device redirect flow:

1. You build the OIDC authorisation request with the appropriate parameters.
2. Redirect the user to the Signicat authorisation endpoint.
3. Signicat displays a QR code on the desktop/PC browser.
4. The user scans the QR code with their mobile phone using their EUDI Wallet app.
5. The user authenticates on their mobile phone and consents to share the requested data in their wallet by verifying their identity, for example by entering a PIN or biometric authentication.
6. After successful mobile authentication, the desktop browser automatically resumes. Signicat sends the user to your specified Redirect URI with the authorisation code.
7. At the same time, your application receives the authorisation code and the state on the desktop/PC browser.
8. Your backend exchanges the code for tokens: ID token, access token and refresh token (optional).
9. You validate the ID token before establishing a session.
10. Optionally, you retrieve additional information through the userInfo endpoint.

1. Build the authentication request

To begin an authentication flow, design your application to build an authorisation URI which points to the authorisation (authorize) endpoint. Then, you direct the end-user to the authorisation URI in a browser, where they can log in with their EUDI Wallet.

Your application should send an HTTPS GET request with the appropriate URI parameters. Here is an example of an authorisation URI with OIDC:

https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize?
    &client_id=<OIDC_CLIENT_ID>
    &response_type=code
    &redirect_uri=<REDIRECT_URI>
    &state=xyz123
    &scope=openid%20profile%20address%20phone%20nin%20wallet-verifier-extra
    &acr_values=idp:wallet-verifier
    &prompt=login
    &code_challenge=Qr_Nb4Ge6pPGzGW5pMThE8QSHzhP432v4NfIgeNFylI
    &code_challenge_method=S256

Authorisation endpoint

You can find the base URL of your authorization_endpoint in the discovery document of your OIDC client available in the Signicat Dashboard under "Well-Known URL for client".

The above example uses the following parameters:

For more query parameters to pass in your authentication request, see the official OIDC specification.

Important: Scopes matching

The scopes you specify in the query parameters must match the scopes you configured in your OIDC client in the Signicat Dashboard.

2. End-user authentication

Now, your application can redirect the end-user to the authorisation URI you built above. This redirects the users to a web link where they can perform authentication in the context of the session you just created.

User journey

To authenticate with their EUDI Wallet, end-users will complete a cross-device flow:

1. QR code scan: The user chooses to authenticate with their EUDI Wallet on your website. Signicat displays a QR code on the desktop/PC browser. The user opens their EUDI Wallet app on their smartphone and scans the QR code.
2. Consent and verification: After scanning, the user's mobile app displays the specific personal data requested (such as PID or QEAA). The user reviews this request and confirms by entering their PIN or verifying with biometrics.
3. Redirect: After successful verification, the desktop/PC browser automatically resumes and Signicat redirects the user back to the redirect_uri specified in your request, containing the authorisation code and state.

Test an authentication

To test an authentication flow during the implementation phase, use the test user you generated in your wallet app, as in the Try it out page.

3. Get the server response

Now, you can retrieve the end-user data by exchanging the authorisation code in the server response for an access token and an ID token.

Example of the server response URI after the end-user authentication:

https://<REDIRECT_URI>?
code=7E3324AB3AC63C7C1D4BED818D01DDE8F7DDC15EBA9505E1B4D44A95A2B72DDF-1
&scope=openid%20profile%20address%20phone%20nin%20pseudonym
&state=xyz123

You should check that the state in the redirect matches the original state sent in the authorisation request to mitigate CSRF and other related attacks.

The code holds the authorisation code generated by the authorisation server. You use this code in the request to the token endpoint to obtain an access token and the ID token.

4. Obtain the access token

You can now exchange the authorisation code for an access token, an ID token and optionally a refresh token by making an HTTPS POST request to the token endpoint of the authorisation server.

Example token request

POST /auth/open/connect/token HTTP/1.1
Host: <YOUR_SIGNICAT_DOMAIN>
Authorization: Basic ZGV2LXRlbnNlL...pnTW9oajBpbW1SQQ==
Content-Type: application/x-www-form-urlencoded

grant_type=code
redirect_uri=<REDIRECT_URI>
code=7E3324AB3AC63C7C1D4BED818D01DDE8F7DDC15EBA9505E1B4D44A95A2B72DDF-1
code_verifier=oQDZ3uPQn...W7U

Example token response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJ ... Klmmm.emo ... NzBKFf.gaW8g ... Mzn5",
    "token_type": "Bearer",
    "refresh_token": "eyJ ... zcuUk.mow ... 7HmKmn.ggW8h ... Gz4g",
    "expires_in": 3600,
    "id_token": "eyJ ... zcifQ.ewo ... NzAKfQ.ggW8h ... Mzqg"
}

5. Decode the ID token

An ID token is a JWT that contains information about the authenticated user.

Decoded payload (data) of the ID token for the EUDI Wallet:

{
    "iss":"https://<ACCOUNT_DOMAIN>/auth/open",
    "nbf":1726046529,
    "iat":1726046529,
    "exp":1726047129,
    "aud":"<OIDC_CLIENT_ID>",
    "amr":[
        "external"
    ],
    "at_hash":"_T539pqKJTOovx1xVyMnKA",
    "sid":"783EFB56CEE40C1FA95F0543535B6E4E",
    "sub":"X-FUmG7SkaAb8fA-7IU0ZrpTIJ37fnaV-c5SbXAoOqw=",
    "auth_time":1726046523,
    "idp":"wallet-verifier",
    "sandbox":true
}

ID Token

By default, the ID Token returns only the claims defined in the OIDC standard (standard scopes).

To control the data returned in the ID Token, go to your OIDC client configuration in the Signicat Dashboard and edit the ID Token User data in the Advanced > Security tab to return All claims.

UserInfo response

You can retrieve full user information by making a request to the UserInfo endpoint using the access_token as a Bearer token.

Example response from the UserInfo endpoint:

{
    "sub": "X-FUmG7SkaAb8fA-7IU0ZrpTIJ37fnaV-c5SbXAoOqw=",
    "name": "John Robert Doe",
    "family_name": "Doe",
    "given_name": "John",
    "middle_name": "Robert",
    "gender": "male",
    "birthdate": "1985-06-15",
    "phone_number": "+4799999999",
    "address":
    {
        "formatted": "Munkegata 26B, 7011 Trondheim, Norway",
        "street_address": "Munkegata 26B",
        "locality": "Trondheim",
        "region": "Trøndelag",
        "postal_code": "7011",
        "country": "Norway"
    },
    "nin": "15068512345",
    "nin_type": "social_security_number",
    "nin_issuing_country": "NO"
}

Next steps and security considerations

After you retrieve the identity data of a user, you must integrate this information into your application's user lifecycle and secure the active session. This typically involves matching the returned attributes to a user record in your database or initiating your internal registration flow. To complete the transaction securely, ensure your backend validates the integrity of the session state before granting the user access to your services.

Learn more

See the OIDC parameters that apply to the EUDI Wallet:

Attributes reference

Attributes and claims for the EUDI Wallet 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

Advanced security considerations

Learn about advanced security measures like PKCE and encryption