Skip to main content

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

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

login_hint

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:

NameDescription
userIdThe MobileID user ID for the user that will carry out the operation.
deviceIdThe 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:

NameValuesDescription
authMethodDEVICE, DEVICE_PIN, DEVICE_IOS_FACE_ID, DEVICE_ANDROID_FINGERPRINT, DEVICE_STRONG_TOUCH_ID or DEVICE_ANDROID_BIOMETRIC_PROMPTThe 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.
authLevelONE_FACTOR or TWO_FACTORThe authentication level to use for the operation.
If not provided, the default level TWO_FACTOR will be used.
sendPushtrue or falseChoose 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.
idpmobileidA 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 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.

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 the ID token part of the token response and the UserInfo endpoint.

MobileID scope

The following claims belong to the mobileid scope.

ClaimDescriptionExample
mobileid_transaction_idThe transaction ID.daa489e-6b35-46ca-83a4-1bba2ea35f68
mobileid_user_idThe ID of the MobileID user.5ddc7357-abe0-6940-b4a3-fd6eb3277830
mobileid_device_idThe ID of the user's device.20874199-f4d1-4e9d-86ee-dd4a46030acb
mobileid_stateThe operation state. See Operation states in our MobileID API reference for possible values.COMPLETED
mobileid_createdThe 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_expiryThe timestamp when the operation expires. Returned in pattern yyyy-MM-dd'T'HH:mm:ss.SSSZ.2022-08-19T06:01:37.123Z
mobileid_push_sentInforms you whether a push is sent or not.TRUE
mobileid_auth_levelThe authentication level used for the operation. See Authentication levels in our MobileID API reference for possible values.TWO_FACTOR
mobileid_auth_methodThe authentication method to use for the operation. See Authentication methods in our MobileID API reference for possible values.DEVICE :PIN
mobileid_binding_messageContext 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_accuracyThe 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_altitudeThe 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_latitudeThe 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_longitudeThe 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_attributesA 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_statusThe 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_dateThe 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_statusThe 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_dateThe 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.

ClaimDescriptionExample
mobileid_user_external_referenceA customer-generated identifier, that points to the userId.EMP11-21
mobileid_user_createdThe 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_usedThe 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_stateThe user state. Allowed values are ACTIVE or LOCKED.ACTIVE
mobileid_device_nameA customer-generated device name.My-iPhone
mobileid_device_stateThe device state. Allowed values are ACTIVE or LOCKED.ACTIVE
mobileid_device_createdThe 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_usedThe 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_typeThe last operation type that the device was used for. See Operation type in our MobileID API reference for possible values.AUTHENTICATION
mobileid_user_attributesA set of user attributes, given as a comma-separated list.first_name=Jane, last_name=Doe