Skip to main content

Integration with OIDC

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

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

Before you begin​

Before starting your mojeID OIDC integration:

  1. Make sure you have completed the initial preparations.
  2. Set up mojeID in the Signicat Dashboard.

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 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 and personal data

    Scopes encode what personal information you request from your end-users. Your billing bundle with Signicat determines what scopes are available. Learn more in the Attributes reference.

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

PKCE

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 authentication flow​

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 authorization code that it can exchange for an access token and an ID token. You can find the end-user data attributes in the ID token or in the UserInfo endpoint.

Build the authentication request​

To begin the authorization flow, your application should build an authentication URI that the end-user can open in a browser to start an authentication flow with mojeID.

The authorize endpoint is the place where to start the authentication flow with the end-user. It directs the end-user to the authorisation server, where the end-user logs in with their mojeID account.

Your application sends an HTTPS GET request with the appropriate URI parameters.

Here is an example of an OIDC authentication URI:

https://<YOUR_ACCOUNT_DOMAIN>/auth/open/connect/authorize?
    client_id=<OIDC_CLIENT_ID>
    &response_type=<GRANT_TYPE_CODE>
    &redirect_uri=<REDIRECT_URI>
    &state=1713343316409-zie
    &scope=openid%20profile%20nin%20address
    &acr_values=idp:mojeid-pl%20loa:substantial

The base URL of your authorization_endpoint is available in the discovery document of your OIDC client which you can find under "Well-Known URL for client" in your OIDC client configuration in the Signicat Dashboard.

Note the following query parameters:

  • client_id: The client ID of your OIDC application.
  • response_type: Specifies the desired grant type for the OIDC flow.
  • redirect_uri: The URI where to redirect the user after they approve the request at the end of the OIDC flow. This must be an absolute URI using the HTTPS protocol.
  • state: A randomly generated string used to maintain the state between the request and the callback. It helps mitigate CSRF attacks by ensuring the returned value matches the one sent in the initial request.
  • scope: A space-separated list of permissions that the application requests, determining which claims are returned after a successful OIDC flow.
  • acr_values: (Optional) A space-separated list of key-value pairs to customise the authentication flow. See the acr_values reference for more details. In the request:
    • idp:mojeid-pl: Directs the end-user to mojeID, skipping the eIDs selection screen. This prevents users from choosing other eIDs that may be active in your account.
    • loa:substantial: Sets the desired Level of Assurance (LoA) for the authentication flow.

You can find additional authorization request query parameters in the OIDC specification.

Important

The values you specify in the query parameters must match the values in the configuration of your OIDC client.

End-user authentication​

To authenticate with mojeID, end-users must consent to share their data with you through the mojeID confirmation screen.

The process flow that the end-user follows includes these steps:

  1. On your website/application, the end-user clicks on a button to authenticate with mojeID. Your application sends an authorization request to start an authentication with mojeID, as described in the previous section.
  2. The end-user is redirected to the mojeID identity providers (IdP) page where they can select their online bank/IdP.
  3. The end-user logs in to their bank environment using their mojeID credentials (this step may involve two-factor authentication).
  4. In the mojeID validation page, the end-user views:
    • Attributes requested for authentication.
    • Context description. This is the reason for authentication you specify in the mojeID configuration.
    • Your customer name as agreed with KIR.
  5. The end-user consents to transfer their data in the authentication flow and gets redirected back to the redirect URI.

After the end-user approves the request, the authorization server redirects the browser back to the redirect_uri specified by the application, adding a code and state to the query string in the server response.

Server response​

Here is an example of the server response URI after the end-user authentication:

https://<REDIRECT_URI>?
code=7E3324AB3AC63C7C1D4BED818D01DDE8F7DDC15EBA9505E1B4D44A95A2B72DDF-1
&scope=openid%20profile%20nin%20address
&state=1713343316409-zie
&session_state=PJl854GXgavBXj1-JRlfSvwkh9hpraImao2fvYDTDwE.A6AB53401320A51C5D61F205FE29468B
&iss=https%3A%2F%2F<YOUR_ACCOUNT_DOMAIN>%2Fauth%2Fopen

Your application should check that the state in the redirect matches the original state in the authorization request to mitigate CSRF and other related attacks.

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

Obtain the access token​

Your application should exchange the authorization code for an access token, an ID token and optionally a refresh token by making an HTTPS POST request to the authorization server token endpoint.

Example token request

curl -X POST https://<YOUR_ACCOUNT_DOMAIN>/auth/open/connect/token -H 'Authorization: Basic ZGV2LXRlbnNlL...pnTW9oajBpbW1SQQ==' -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=<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"
}​

ID token​

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 mojeID would then look like:

{
  "iss": "https://<YOUR_ACCOUNT_DOMAIN>/auth/open",
  "nbf": 1712237928,
  "iat": 1712237928,
  "exp": 1712238528,
  "aud": "<OIDC_CLIENT_ID>",
  "amr": [
    "external"
  ],
  "at_hash": "0zAbHkX...IeNDhkFoWlhKg",
  "sid": "8930E9EC6FAF...874DF7BA6FC907383",
  "sub": "1q3Yf0-oFOvZCALyfLI98p0lgWgoSneWICAwQOzY18E=",
  "auth_time": 1712237927,
  "idp": "mojeid",
  "name": "firstName middleName lastName",
  "family_name": "lastName",
  "given_name": "firstName",
  "middle_name": "middleName",
  "birthdate": "1899-12-31 ",
  "address": {
    "formatted": "ul. Lirowa 137, Gdańsk, PostName, 80-298, Poland",
    "street_address": "ul. Lirowa 137 Gdańsk",
    "locality": "PostName",
    "postal_code": "80-298",
    "country": "Poland"
  },
  "nin": "99923106807",
  "nin_type": "PERSON",
  "nin_issuing_country": "PL",
  "idp_issuer": "https://wb.kir.pl",
  "transaction_id": "355f42c4-a1ec-a...-87af-1eaad9a89435",
  "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.

UserInfo response​

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

Example of a response from the UserInfo endpoint:

{
  "name": "firstName middleName lastName",
  "family_name": "lastName",
  "given_name": "firstName",
  "middle_name": "middleName",
  "birthdate": "1899-12-31",
  "address": {
    "formatted": "ul. Lirowa 137, Gdańsk, PostName, 80-298, Poland",
    "street_address": "ul. Lirowa 137 Gdańsk",
    "locality": "PostName",
    "postal_code": "80-298",
    "country": "Poland"
  },
  "nin": "99923106807",
  "nin_type": "PERSON",
  "nin_issuing_country": "PL",
  "sub": "1q3Yf0-oFOvZCALyfLI98p0lgWgoSneWICAwQOzY18E=",
  "idp_issuer":"https://wb.kir.pl",
}
Success

You have now completed an identity verification flow with mojeID.

Next steps​

Continue your journey with more mojeID guides:

Attributes reference
Scopes and claims for mojeID 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 etc.
Advanced security considerations
Learn about advanced security measures like PKCE and encryption
Last updated:
On this page