# CIBA flow with MobileID

Contents

Overview
CIBA authentication request
CIBA token request
- Token request
- Token response
MobileID claims

# Overview

You can use MobileID to authenticate and authorise operations.

The following sequence diagram shows which steps are needed:

MobileID CIBA sequence diagram click-to-zoom

# 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. You do this by setting the identity provider (idp) to MobileID in the 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 parameter to pass the IDs of the MobileID user and device that you want to start the operation for. Both of these parameters are required.

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

The format is a space-separated list of key-value pairs. An example is shown below:

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

# acr_values

You can use the 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

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

requested_expiry=300

# binding_message

You can use the 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

An example of a binding_message is shown below:

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

An example of an authentication request is shown below:

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 (opens new window) specification documentation.

# Example

An example of an authentication response is shown below:

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. See the next section on CIBA token request for further information.

# 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
Optionally, a refresh token

You can find general information about the CIBA token endpoint in our developer documentation (opens new window).

# 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

An example of a token request is shown below:

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.

An example of a token response is shown below:

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

An example of what an ID token can look like when using scope = openid mobileid is shown below:

{
  "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 ID token part of the token response (opens new window) and the UserInfo (opens new window) endpoint.

Scope	Claim	Description	Example
`mobileid`	`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 state 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`	`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_user_segment`	The user segment. An optional field configured on user accounts, used to segment end-users and corresponding transactions.	`SE`
	`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 last 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`

← Set up MobileID for CIBA

# CIBA flow with MobileID

# Overview

# CIBA authentication request

# Select the ID method

# Select the scope

# Set MobileID operation parameters

# login_hint

# Example

# acr_values

# Example

# requested_expiry

# Example

# binding_message

# Example

# CIBA authentication request example

# CIBA authentication response example

# Example

# CIBA token request

# Token request

# Example

# Token response

# Example

# MobileID claims