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