CIBA flow with MobileID

Overview

You can use MobileID to authenticate and authorise operations.

The following sequence diagram shows which steps are needed:

MobileID CIBA sequence diagram

CIBA authentication request

This section contains details for how to setup the CIBA authentication request with MobileID.

Select the ID method

You need to select MobileID as the ID method in your authorisation request. To do this, set the identity provider (idp) to MobileID in the ACR values (acr_values):

acr_values=idp:mobileid`

Select the scope

When using OIDC CIBA, you always have to use 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 claims table.

Get all claims

To get all claims for MobileID, you can use:

scope = openid mobileid mobileid-extra

Set MobileID operation parameters

You can configure the MobileID operation by using the login_hint, acr_values, requested_expiry and binding_message parameters.

You must use the login hint (login_hint) parameter to pass the IDs of the MobileID user and device that you want to start the operation for.

Both the user ID and device ID are required.
The format is a space-separated list of key-value pairs.

Note

The MobileID user and device IDs are created when the user is registered and the device is enrolled through the MobileID REST API.

The available options are:

Name	Description
`userId`	The MobileID user ID for the user that will carry out the operation.
`deviceId`	The ID of the user's device to be used for operation.

Example: Using the login hint parameter

login_hint=userId%3A0e99b25c-abde-4553-973b-8d94d49cd87e%20deviceId%3A20874199-f4d1-4e9d-86ee-dd4a46030acb

ACR values

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

The available parameters and values are:

Name	Values	Description
`authMethod`	`DEVICE`, `DEVICE_PIN`, `DEVICE_IOS_FACE_ID`, `DEVICE_ANDROID_FINGERPRINT`, `DEVICE_STRONG_TOUCH_ID` or `DEVICE_ANDROID_BIOMETRIC_PROMPT`	The authentication method to use for the operation. Note: The MobileID device must have activated the selected `authMethod` to be able to use it. If the `authMethod` is not activated, then the operation will fail.
`authLevel`	`ONE_FACTOR` or `TWO_FACTOR`	The authentication level to use for the operation. If not provided, the default level `TWO_FACTOR` will be used.
`sendPush`	`true` or `false`	Choose to send push or not. In order to be sent, it requires that push notifications are configured for your application configuration. If not specified, push notifications will be sent depending on the settings in your application configuration.
`idp`	`mobileid`	A required ACR value that has to contain the value `mobileid`, in order to start a MobileID operation.

Example: Using the ACR values parameter

acr_values=idp%3Amobileid%20authLevel%3ATWO_FACTOR%20authMethod%3ADEVICE_PIN%20sendPush%3Atrue

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 code in order to fulfil the authentication on the mobile device.
A push will be sent to end-user's device.

Requested 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: Using the requested expiry parameter

requested_expiry=300

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: Using the binding message parameter

binding_message=Do%20you%20want%20to%20transfer%20%24300%20to%20Jane%3F

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.

CIBA authentication request example

Example: Authentication request

POST /auth/open/connect/ciba HTTP/1.1
Authorization: Basic ZGV2LW...CamdraTd2
Host: yourdomain.signicat.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 100

scope=openid%mobileid&
binding_message=Do%20you%20want%20to%20transfer%20%24300%20to%20Jane%3F&
request_expiry=300&
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

In this example, you can see that:

The URL for the authentication request is:

https://yourdomain.signicat.com/auth/open/connect/ciba

The operational parameters are given as:

scope=openid%mobileid&
binding_message=Do%20you%20want%20to%20transfer%20%24300%20to%20Jane%3F&
request_expiry=300&
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

CIBA authentication response example

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

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
}

The auth_req_id is needed when you poll the token endpoint. For further information, see the CIBA token request section.

CIBA token request

After a MobileID operation has been completed, you can obtain the following from our token endpoint:

An access token
An ID token
Optional: A refresh token

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:
```
auth_req_id=5ddc7357-abe0-6940-b4a3-fd6eb3277830
```

The grant type for CIBA:

grant_type=urn:openid:params:grant-type:ciba

Example: Token request

POST /auth/open/connect/token HTTP/1.1
Authorization: Basic ZGV2LW...CamdraTd2
Host: yourdomain.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"
}

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

Example: ID token when using scope = openid mobileid

{
    "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"
}

MobileID claims

All claims belong to a scope. If you set the scope in the authentication request, then the claim will be returned in both the ID token part of the token response and the UserInfo endpoint.

MobileID scope

The following claims belong to the mobileid scope.

Claim	Description	Example
`mobileid_transaction_id`	The transaction ID.	`daa489e-6b35-46ca-83a4-1bba2ea35f68`
`mobileid_user_id`	The ID of the MobileID user.	`5ddc7357-abe0-6940-b4a3-fd6eb3277830`
`mobileid_device_id`	The ID of the user's device.	`20874199-f4d1-4e9d-86ee-dd4a46030acb`
`mobileid_state`	The operation state. See Operation states in our MobileID API reference for possible values.	`COMPLETED`
`mobileid_created`	The timestamp when the operation is created. Returned in pattern `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.	`2022-08-19T06:01:37.123Z`
`mobileid_requested_expiry`	The timestamp when the operation expires. Returned in pattern `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.	`2022-08-19T06:01:37.123Z`
`mobileid_push_sent`	Informs you whether a push is sent or not.	`TRUE`
`mobileid_auth_level`	The authentication level used for the operation. See Authentication levels in our MobileID API reference for possible values.	`TWO_FACTOR`
`mobileid_auth_method`	The authentication method to use for the operation. See Authentication methods in our MobileID API reference for possible values.	`DEVICE :PIN`
`mobileid_binding_message`	Context sent to the app, through a secure end-to-end encrypted channel, before the operation is completed.	`Do you want to transfer $300 to Jane?`
`mobileid_location_accuracy`	The location accuracy of the device used for the operation. In order to be returned in the response, it has to be enabled in the application configuration.	`0.564`
`mobileid_location_altitude`	The location altitude of the device used for the operation. In order to be returned in the response, it has to be enabled in the application configuration.	`76.2352.3563`
`mobileid_location_latitude`	The location latitude of the device used for the operation. In order to be returned in the response, it has to be enabled in the application configuration.	`12.34234.143`
`mobileid_location_longitude`	The location longitude of the device used for the operation. In order to be returned in the response, it has to be enabled in the application configuration.	`32.24314.1431`
`mobileid_risk_attributes`	A set of risk attributes can be collected for each operation. You can configure which attributes are collected in the application configuration. See Risk attributes in our MobileID API reference for possible values.	`isDebugEnabled=true, isPowerConnected=false, isRootAvailable=false, isUnknownSourcesEnabled=false, isSecureScreenLockEnabled=false`
`mobileid_attestation_play_integrity_status`	The Play Integrity attestation status for the device. See Play Integrity statuses in our MobileID API reference for possible values. Note: In order for this to be returned in the response, app attestation has to be enabled in the application configuration.	`VERIFIED`
`mobileid_attestation_play_integrity_date`	The date of when the Play Integrity attestation was performed. Note: In order for this to be returned in the response, app attestation has to be enabled in the application configuration.	`2023-05-15T11:01:37.123Z`
`mobileid_attestation_app_attest_status`	The App Attest attestation status for the device. See App Attest statuses in our MobileID API reference for possible values. Note: In order for this to be returned in the response, app attestation has to be enabled in the application configuration.	`FAILED_CLIENT_TIMEOUT`
`mobileid_attestation_app_attest_date`	The date of when the App Attest attestation was performed. Note: In order for this to be returned in the response, app attestation has to be enabled in the application configuration.	`2023-05-15T11:01:37.123Z`

MobileID extra scope

The following claims belong to the mobileid-extra scope.

Claim	Description	Example
`mobileid_user_external_reference`	A customer-generated identifier, that points to the `userId`.	`EMP11-21`
`mobileid_user_created`	The timestamp when the user is created. Returned in pattern `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.	`2022-08-19T06:01:37.123Z`
`mobileid_user_last_used`	The timestamp when the user is last used. Returned in pattern `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.	`2022-08-19T06:01:37.123Z`
`mobileid_user_state`	The user state. Allowed values are `ACTIVE` or `LOCKED`.	`ACTIVE`
`mobileid_device_name`	A customer-generated device name.	`My-iPhone`
`mobileid_device_state`	The device state. Allowed values are `ACTIVE` or `LOCKED`.	`ACTIVE`
`mobileid_device_created`	The timestamp when the device is created. Returned in pattern `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.	`2022-08-19T06:01:37.123Z`
`mobileid_device_last_used`	The timestamp when the device was last used. Returned in pattern `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.	`2022-08-19T06:01:37.123Z`
`mobileid_device_last_operation_type`	The last operation type that the device was used for. See Operation type in our MobileID API reference for possible values.	`AUTHENTICATION`
`mobileid_user_attributes`	A set of user attributes, given as a comma-separated list.	`first_name=Jane, last_name=Doe`

Overview​

CIBA authentication request​

Select the ID method​

Select the scope​

Set MobileID operation parameters​

Login hint​

ACR values​

Requested expiry​

Binding message​

CIBA authentication request example​

CIBA authentication response example​

CIBA token request​

Token request​

Token response​

MobileID claims​

MobileID scope​

MobileID extra scope​