Skip to main content

Implement

This guide shows you how to implement the Client-Initiated Backchannel Authentication (CIBA) 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 CIBA 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/ciba?
scope=<YOUR_SCOPES>
&request_expiry=<YOUR_SESSION_EXPIRY>
&binding_message=<YOUR_BINDING_MESSAGE>
&acr_values=<YOUR_ACR_VALUES>
&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/ciba.

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 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:

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.

Request expiry​

You can use the requested expiry (requested_expiry) parameter to set the desired duration of the authentication session in seconds.

If no requested_expiry is set, then the SESSION_EXPIRY in your application configuration is used. The default value for SESSION_EXPIRY is 187200000 milliseconds (187200 seconds).

Example: Set requested expiry
requested_expiry=300
What does this example mean?

In this example, the desired duration of the authentication session has been set to 300 seconds.

Binding message​

You can use the binding message (binding_message) parameter to pass text that is sent to the mobile app through a secure, end-to-end encrypted channel, before the MobileID authentication is completed.

Terminology

In MobileID, we refer to this binding_message as a pre-operation context, with a MIME type of plain text.

You can read more about pre-operation context as a concept in our MobileID feature documentation.

Example: Set binding message
binding_message=Do%20you%20want%20to%20transfer%20%24300%20to%20Jane%3F
What does this example mean?

In this example, the configured text Do you want to transfer $300 to Jane? will be passed to the mobile application before the end-user carries out the authentication.

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

Login hint​

You must use the login hint (login_hint) parameter to pass the ID 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.

The available options are:

Example: Set the login hint
login_hint=userId%3A0e99b25c-abde-4553-973b-8d94d49cd87e%20deviceId%3A20874199-f4d1-4e9d-86ee-dd4a46030acb
What does this example mean?

In this example, end-user 3A0e99b25c-abde-4553-973b-8d94d49cd87e and device 3A20874199-f4d1-4e9d-86ee-dd4a46030acb have been set in the login hint.

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/ciba?
scope=openid%20mobileid
&request_expiry=300
&binding_message=Do%20you%20want%20to%20transfer%20%24300%20to%20Jane%3F
&acr_values=idp%3Amobileid%20authLevel%3ATWO_FACTOR%20authMethod%3ADEVICE_PIN%20sendPush%3Atrue
&login_hint=userId%3A0e99b25c-abde-4553-973b-8d94d49cd87e%20deviceId%3A20874199-f4d1-4e9d-86ee-dd4a46030acb

Authentication response example​

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

{
    "auth_req_id": "5ddc7357-abe0-6940-b4a3-fd6eb3277830",
    "expires_in": 120,
    "interval": 1
}
Note

The auth_req_id returned in the authentication response is needed for when you make a request to the token endpoint to obtain an access token and the ID token.

Want to learn more?

The response to a successful CIBA authentication request is documented in the OpenID Connect Client-Initiated Backchannel Authentication Flow specification documentation.

2. Obtain the access token​

After a MobileID operation has been completed, your application should exchange the auth_req_id 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 CIBA token endpoint in our developer documentation.

Token request​

You need to include the following parameters in the request:

  • The auth_req_id received in the CIBA authentication response:
  • The grant type (grant_type). For this flow, this is always ciba.
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

auth_req_id=5ddc7357-abe0-6940-b4a3-fd6eb3277830&
grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba

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_requested_expiry":"2022-08-19T06:01:37.123Z",
    "mobileid_push_sent":"true",
    "mobileid_auth_level":"TWO_FACTOR",
    "mobileid_auth_method":"DEVICE:PIN",
    "mobileid_binding_message":"Do you want to transfer $300 to Jane?",
    "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 CIBA Flow Attributes reference table.

On this page