Skip to main content

OpenID Connect

This guide details how to integrate with MitID using OpenID Connect (OIDC) as an authentication protocol.

Prerequisites​

We assume you have done the initial preparations and received the needed access to the service, as described on the Initial preparations page.

Set up the OIDC client in the Dashboard​

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

2. Configure the scope​

Available scopes for MitID are: openid profile idp-id nin mitid-extra

openid is mandatory for all eIDs.

To be able to add scopes in your request, you first need to define them in the Signicat Dashboard:

  1. In the Signicat Dashboard, navigate to Products > eID Hub > OIDC Clients.
  2. Select Edit to view your client configuration.
  3. Open the Access tab.
  4. Select Add scope in the "Allowed scopes" section and select the scopes from the list.

For more details about these scopes, see the Attributes reference.

3. 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 Signicat Dashboard, navigate to Products > eID Hub > OIDC Clients.
  2. Choose your client, go to the Secrets tab and select Add secret.
  3. Enter a name for your client secret and select Create.
  4. Copy your new client secret and store it safely.
Important

Save the client secret in a safe place, since you will only be able to view your client secret once, right after you create it. If you ever forget it or lose it, you have to 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.

Implement the 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.

1. Build the authentication request​

This section describes how to generate the URI that opens the MitID login page.

To begin the authentication flow, your application should build an authentication URI that the end-user can open in a browser to start an authentication flow with MitID. The authorize endpoint starts the authentication flow with the end-user. It directs the end-user to the authorisation server, where the end-user logs in with their MitID account.

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

You can pre-select an eID in your authorization request by including the name of the identity provider (idp) in the acr_values parameter. To pre-select MitID, include acr_values=idp:mitid in your authorization request.

Here is an example of an OIDC authentication URI:

https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize?
client_id=sandbox-example-client-123
&response_type=code
&scope=openid profile idp-id nin mitid-extra
&prompt=login
&acr_values=idp:mitid
&redirect_uri=https://myservice.example/redirect

The URL consists of two parts:

  • The first part is the base URL, https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize. This URL is available in the discovery document of your OIDC client which you can find under Well-Known URL for client in the configuration of your OIDC client in the Dashboard.
  • The remainder constitutes parameters to set things like Client ID, flow and redirects.

Note the following query parameters:

  • client_id: The client ID of your OIDC application. To view the client ID, navigate to Products > eID Hub > OIDC Clients and select your client.
  • response_type: Specifies the required grant type for the OIDC flow.
  • scope: A space-separated list of permissions that the application requests, determining which claims are returned after a successful OIDC flow.
  • prompt: Controls the behaviour of the authentication flow. For more details, see Forcing re-authentication.
  • acr_values: (Optional) A space-separated list of key-value pairs to customise the authentication 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.
Important

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

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

The acr_values parameters are described in more detail below.

Control the MitID flow (acr_values)​

You can control the MitID flow by using the acr_values parameters, for example: acr_values=idp:mitid.

Available parameters and values are:

Reference text must be signed

You must pass the mitid_reference_text parameter as a signed request to ensure it is generated by you and has not been tampered with by other parties. For more details about how to sign a request, see the eID Hub documentation.

End-user authentication​

The end-user follows these steps:

  1. On your website/application, the end-user clicks on a button to authenticate with MitID. Your application sends an authorization request to start an authentication with MitID, as described in the previous section.
  2. The end-user is redirected to the MitID login page.
  3. The end-user logs in using their MitID credentials (this step may involve two-factor authentication).

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 in the server response.

Server response​

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

https://<REDIRECT_URI>/?
code=DBB67B2E8E95933A1B8D283C04848DC6A878855B943671DED1310736A811D44E-1
&scope=openid%20profile%20idp-id%20nin%20mitid-extra
&session_state=MZvUqShFyumujsPPyby4cyUNhxrSKvmkBuDFvONHlcw.00C7928A96EBC64F87BEA33E37C3290B
&iss=https%3A%2F%2F<YOUR_SIGNICAT_DOMAIN>%2Fauth%2Fopen

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 (see the next sections).

2. 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_SIGNICAT_DOMAIN>/auth/open/connect/token -H 'Authorization: Basic ZGV2LXRlbnNlL...pnTW9oajBpbW1SQQ==' -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=authorization_code&redirect_uri=<REDIRECT_URI>&code=7E3324AB3AC63C7C1D4BED818D01DDE8F7DDC15EBA9505E1B4D44A95A2B72DDF-1&code_verifier=oQDZ3uPQn...W7U'

Example token response​

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

{
    "id_token": "eyJhbGciOiJSU0EtT0FFUC...",
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNhbmRib3gtc2lnbmluZy1rZXktZjJlNGE3YTg4NDgxYTc0ZWJlMzIxNDFiYj...",
    "expires_in": 600,
    "token_type": "Bearer",
    "scope": "openid profile idp-id nin mitid-extra"
}

ID token​

An ID token is a JWT that encoded looks like "eyJraWQiOiJoc20tc2lnbi0xNDEtMjA2NDc5ODk" (abbreviated).

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

{
  "iss": "https://postman-test.sandbox.signicat.dev/auth/open",
  "nbf": 1733316354,
  "iat": 1733316354,
  "exp": 1733316954,
  "aud": "dev-immense-drop-342",
  "amr": ["external"],
  "at_hash": "npaLd_WTdIbwrXO38GFDgQ",
  "sid": "0E2F59A888BFEAB2EAD3221684B196D4",
  "sub": "MbLYMQJMSQAwk-saNS0KEcLGJbtfTR52eQHCkSaqTww=",
  "auth_time": 1733316333,
  "idp": "mitid",
  "name": "Abelone Christensen",
  "family_name": "Christensen",
  "given_name": "Abelone",
  "birthdate": "1974-07-11",
  "mitid_has_cpr": "true",
  "mitid_transaction_id": "a6ca8f2f-a962-49a5-820b-581bff5645d3",
  "mitid_reference_text_body": "Transfer 200 DKK to Account XYZ",
  "mitid_ial": "SUBSTANTIAL",
  "mitid_loa": "SUBSTANTIAL",
  "mitid_aal": "SUBSTANTIAL",
  "mitid_fal": "HIGH",
  "mitid_uuid": "f5276262-9145-4616-8faf-23e8e683d665",
  "idp_issuer": "MitID",
  "transaction_id": "e50db162-f045-7f45-9a48-e0edd9a0532a",
  "sandbox": true
}

In this example we have used the following scopes for MitID: openid profile idp-id nin mitid-extra

Control the returned data in ID Token​

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:

  1. In the Signicat Dashboard, navigate to Products > eID Hub > OIDC Clients.
  2. Choose your OIDC client and select Edit to view the client configuration.
  3. Navigate to the Advanced > Security tab and edit the ID Token User data. You can choose between:
    • Standard Scopes (default): Returns the standard OIDC scopes.
    • All: Returns all claims.
    • Minimal: Returns only sub.

3. Obtain user information​

You use the UserInfo request to obtain the user information as defined in the scopes.

This response example shows user information retrieved from the UserInfo endpoint:

{
    "name": "Abelone Christensen",
    "family_name": "Christensen",
    "given_name": "Abelone",
    "birthdate": "1974-07-11",
    "mitid_has_cpr": "true",
    "mitid_transaction_id": "43081689-6291-4367-afc2-da515e0220d6",
    "mitid_reference_text_body": " ",
    "mitid_ial": "SUBSTANTIAL",
    "mitid_loa": "SUBSTANTIAL",
    "mitid_aal": "SUBSTANTIAL",
    "mitid_fal": "HIGH",
    "mitid_uuid": "f5276262-9145-4616-8faf-23e8e683d665",
    "idp_issuer": "MitID",
    "sub": "MbLYMQJMSQAwk-saNS0KEcLGJbtfTR52eQHCkSaqTww="
}

See also the Attributes reference page for a list of available scopes and claims.

Success

You have now completed an authentication flow with MitID.

Next steps​

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