Skip to main content

Implement

This guide shows you how to implement the Authorization Code Flow for MobileID.

Need to set up the integration?

Before you implement the flow, you must first set up the integration. To do this, see the Authorization Code Flow Setup instructions.

1. Build the authentication request​

This step describes how to generate the URL that opens the MobileID login screen.

The authentication request is made of two parts:

  • The base URL.
  • The query parameters.
Example: Authentication request format
https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize?
client_id=<YOUR_OIDC_CLIENT_ID>
&response_type=code
&scope=<YOUR_SCOPES>
&acr_values=<YOUR_ACR_VALUES>
&redirect_uri=<YOUR_REDIRECT_URL>
&login_hint=<YOUR_LOGIN_HINT>

1.1 Set the base URL​

The base URL makes up the first part of the authentication request, given in format https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize.

This URL is available on the client details page for your OIDC client. To find this:

  1. In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > OIDC Clients.
  2. Click the Edit button next to the required client.
  3. See the Well-known URL for client section.

1.2 Set the query parameters​

The query parameters make up the second part of the authentication request:

Important

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

Want to learn more?

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

Client ID​

You need to set the client ID of your OIDC application. To find this:

  1. In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > OIDC Clients.
  2. See the Client ID column for the required client.

Response type​

When using the Authorization Code Flow, you must always set the response type to code.

Select the scope​

When using OIDC, you must always include the scope openid.

There are two MobileID-specific scopes that will return claims related to the MobileID user, the device and the operation in the ID token:

  • mobileid
  • mobileid-extra

You can see which claims are returned for each scope in the MobileID Attributes reference table.

Example: Set scopes
scope = openid mobileid mobileid-extra
What does this example mean?

In this example, the mandatory scope openid is set, in addition to both MobileID-specific scopes. This means that all MobileID claims will be returned.

ACR values​

You can use the ACR values (acr_values) parameter to control the authentication parameters of a MobileID authentication.

Required ACR values

The identity provider (idp) ACR value is required, whereas all other ACR values are optional.

Example: Set ACR values
&acr_values=idp%3Amobileid%20authLevel%3ATWO_FACTOR%20authMethod%3ADEVICE_PIN%20sendPush%3Atrue%20sessionTimeout3A300000%20preOperationContextContent%3ARG8geW91IHdhbnQgdG8gdHJhbnNmZXIgJDMwMCB0byBKYW5lPw==%20preOperationContextTitle%3AUGxlYXNlIGNvbmZpcm0=
What does this example mean?

In this example, the specified ACR values mean that:

  • A MobileID operation is started.
  • Two-factor authentication will be carried out.
  • The end-user will be asked for a PIN in order to fulfil the authentication on the mobile device.
  • A push will be sent to end-user's device.
  • The desired session duration is 300000 milliseconds.
  • The message 'Do you want to transfer $300 to Jane?' with title 'Please confirm' will be shown in the mobile app before the authentication is completed.

Login hint​

You can optionally use the login hint (login_hint) parameter to pass the external reference of the MobileID user and the ID of the device that you want to start the operation for. The format is a space-separated list of key-value pairs.

Note

If these parameters are not passed in this request, then they will be requested by the end-user later in the flow. This is because they are required in order for an end-user to be used with the Authorization Code Flow.

The available options are:

Example: Set the login hint
login_hint=userName%3A11098433221%20deviceId%3A20874199-f4d1-4e9d-86ee-dd4a46030acb
What does this example mean?

In this example, both the external reference and the device ID have been set in the login hint.

This means that the flow will automatically be started for end-user 3A11098433221, for device 3A20874199-f4d1-4e9d-86ee-dd4a46030acb.

Example​

The examples below show what an authentication request and response could look like.

Authentication request example​

Example: Authentication request
https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize?
client_id=sandbox-example-client-123
&response_type=code
&scope=openid%20mobileid
&redirect_uri=https://myservice.example/redirect
&acr_values=idp%3Amobileid%20authLevel%3ATWO_FACTOR%20authMethod%3ADEVICE_PIN%20sendPush%3Atrue%20sessionTimeout3A300000%20preOperationContextContent%3ARG8geW91IHdhbnQgdG8gdHJhbnNmZXIgJDMwMCB0byBKYW5lPw==%20preOperationContextTitle%3AUGxlYXNlIGNvbmZpcm0=
&login_hint=userName%3A11098433221%20deviceId%3A20874199-f4d1-4e9d-86ee-dd4a46030acb

Authentication response example​

Example: Authentication response
HTTP/1.1 200 OK
content-type: application/json; charset=UTF-8

{
    "code": "DBB67B2E8E95933A1B8D283C04848DC6A878855B943671DED1310736A811D44E-1",
    "scope": "openid mobileid",
    "session_state": "MZvUqShFyumujsPPyby4cyUNhxrSKvmkBuDFvONHlcw.00C7928A96EBC64F87BEA33E37C3290B",
    "iss": "https://<YOUR_SIGNICAT_DOMAIN>/auth/open
}
Note

The code returned in the authentication response is the authorisation code generated by the authorisation server.

You need to use this code in the request to the token endpoint to obtain an access token and the ID token.

2. Obtain the access token​

After a MobileID operation has been completed, your application should exchange the authorisation code for:

  • An access token
  • An ID token
  • Optional: A refresh token

To do this, it must make a HTTP POST request to the authorisation server token endpoint.

Want to learn more?

You can find general information about the token endpoint in our developer documentation.

Token request​

You need to include the following parameters in the request:

  • The authorisation code (code) received in the OIDC authentication response.
  • The grant type (grant_type). For this flow, this is always authorization_code.
  • The redirect URI (redirect_uri).
Example: Token request
POST /auth/open/connect/token HTTP/1.1
Authorization: Basic ZGV2LW...CamdraTd2
Host: <YOUR_SIGNICAT_DOMAIN>.signicat.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 101

grant_type=authorization_code
redirect_uri=https://oauth.tools/callback/code
code=04B08DB603596E810C061EFA963FA31EE90FA13696F019612413EEAAC3E1DA3B-1

Token response​

After the MobileID operation has been completed successfully, the token request will respond with a token response.

Example: Token response
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
    "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​

The token response contains an ID token. This token will contain all the claims, including those specific to MobileID.

Example: ID token
{
    "sub":"6NZrmEFWVaQij7tQgDSlsG6H6nBpVbZneQKZMrkJbls=",
    "iss":"https://yourcompany.signicat.com",
    "aud":"dev-flat-nail-899",
    "exp":"300",
    "iat":"2022-08-19T06:01:37.123Z",
    "auth_time":"2022-06-19T06:12:37.222Z",
    "mobileid_transaction_id":"daa489e-6b35-46ca-83a4-1bba2ea35f68",
    "mobileid_user_id":"5ddc7357-abe0-6940-b4a3-fd6eb3277830",
    "mobileid_device_id":"20874199-f4d1-4e9d-86ee-dd4a46030acb",
    "mobileid_state":"COMPLETED",
    "mobileid_created":"2022-06-19T06:12:37.222Z",
    "mobileid_session_timeout":"2022-08-19T06:01:37.123Z",
    "mobileid_push_sent":"true",
    "mobileid_auth_level":"TWO_FACTOR",
    "mobileid_auth_method":"DEVICE:PIN",
    "mobileid_pre_operation_context_content":"Do you want to transfer $300 to Jane?",
    "mobileid_pre_operation_context_title":"Please confirm",
    "mobileid_risk_attributes":"isDebuggerConnected=false, isEmulator=false, deviceHash=yVJ9HYE+WJL40/K04CIDZzuD9jD5I9sLVZ3d47o08U0=, operatingSystemVersion=12"
}
What does this example mean?

In this example, the claims shown in the ID token are a result of using the following scopes:

scope = openid mobileid

3. Obtain information​

All claims belong to a scope. The scopes that you set in the authentication request determine which claims are returned.

The claims are returned in both:

For an overview of all MobileID scopes and corresponding claims, see the Authorization Code Flow Attributes reference table.

On this page