Transaction Quick Start: Server

The BindID service is an app-less, strong portable authenticator offered by Transmit Security. BindID uses FIDO-based biometrics for secure, convenient, and consistent passwordless authentication. This guide explains how to use the CIBA poll mode to perform a backend integration of BindID to authenticate financial transactions (using transaction signing per PSD2.0 SCA). For example, when a user calls their banker to transfer a large sum of money (which cannot be done directly online), the bank can send them a link by SMS to initiate an out-of-band authentication process. Note that this guide assumes that your web application uses BindID to authenticate user login, so users would already be registered before their first transaction. Learn more about BindID

For more information on CIBA ping and poll modes, see Get User Identity and Trust.

Step 1: Get Your BindID Credentials

To integrate with BindID, you'll need to configure an application in the BindID Admin Portal (see Admin Portal: Get Started). You can either create a new application or use one that you already created.

From Applications, here is the basic client setup that is required for your application:

Get your BindID credentials—Obtain the client ID and client secret used to identify your web application to the BindID Service.
Enable CIBA support for the client (select the CIBA supported option).

Step 2: Initiate Transaction

Your application can initiate an out-of-band transaction flow for a user by sending the BindID service a backchannel transaction request. The request can be used to send the user a link by SMS. When opened, this link will initiate an authentication process.

To initiate an transaction flow by sending an SMS link, send the following HTTP POST request, after substituting the field values as described below (see the /authorize_ciba API):

POST /authorize_ciba HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: signin.bindid-sandbox.io

client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]&scope=openid&channel=
%7B%22type%22%3A%22sms%22%2C%20%22target%22%3A%22%[PHONE_NUMBER]%22%7D&claims=
claims%3D%7B%22id_token%22%3A%7B%22bindid_psd2_transaction%22%3A%7B%22essential%22%3A%20true%2C
%22value%22%3A%20%7B%22display_data%22%3A%20%7B%22payee%22%3A%22[PAYEE]%22%2C
%22[AMOUNT]%22%3A%20%22%24700%22%2C%22[METHOD]%22%3A%20%22Acme%20Card%22%7D%7D%7D%7D%7D

Note: The line breaks in the above example are for readability purposes only.

Field	Substitute with...
`[CLIENT_ID]`	Client ID obtained in step 1.
`[CLIENT_SECRET]`	Client Secret obtained in step 1.
`[PHONE_NUMBER]`	The user's mobile phone number that will receive the link to initiate the transaction. Remember to escape the leading + when you add it.
`[PAYEE]`	The account to which payment will be transferred.
`[AMOUNT]`	The amount that will be paid.
`[METHOD]`	The method used to make the transfer.

The response to this request will include an authentication request identifier, which should be used to obtain user information in step 3:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "auth_req_id": "[AUTH_REQ_ID]",
  "expires_in": "[EXPIRATION_TIME]"
}

Field	Description
`[AUTH_REQ_ID]`	Authentication request identifier to use to obtain the user token in step 3.
`[EXPIRATION_TIME]`	Time in seconds until the authentication request identifier expires.

Note: By default, links expire after 30 minutes. To change this, contact your Transmit representative to enable a preview feature where the expiration time can be set on the Application's settings page in the Admin Portal.

When the user opens the link, a screen is displayed prompting the user to approve the transaction request.

Step 3: Get User Token

You can obtain the user token by polling the BindID Service using the authentication request identifier received in step 2, along with the client credentials obtained in step 1. Note that only standard polling is supported (see the OIDC CIBA standard for more).

To obtain the user token, send the following backend HTTP POST request, after substituting the field values as described below:

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: signin.bindid-sandbox.io

grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba&auth_req_id=[AUTH_REQ_ID]&client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]

Field	Substitute with...
`[AUTH_REQ_ID]`	Authentication request identifier received in step 2.
`[CLIENT_ID]`	Client ID obtained in step 1.
`[CLIENT_SECRET]`	Client Secret obtained in step 1.

Until the transaction flow is completed, the response to this request will be an HTTP 200 response with an authorization_pending error. Once the link has been sent to the user, the response is:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "error": "authorization_pending",
    "status": "link_sent"
}

After the user opens the link, the response is:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "error": "authorization_pending",
    "status": "link_opened"
}

Once the transaction is successfully completed, the response will include a JWT token encoding the user information:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "[ACCESS_TOKEN]",
  "id_token": "[ID_TOKEN]",
  "token_type": "Bearer",
  "expires_in": "[EXPIRATION_TIME]"
}

Field	Description
`[ACCESS_TOKEN]`	Access token.
`[ID_TOKEN]`	JWT encoding identifying info, and other info about the transaction.
`[EXPIRATION_TIME]`	Time in seconds until the authentication request identifier expires.

Step 4: Validate User Token

The ID token ([ID_TOKEN]) received in step 3 contains various user information as claims, including claims that allow you to validate that the transaction signing was successfully completed.

The bindid_psd2_transaction claim contains transaction details that were displayed to the user (see example below). The user is required to approve these details before they authenticate. You should validate that payee, payment_method, and payment_amount match the corresponding parameters that you passed in the transaction signing request (in step 3).
{
...
"bindid_psd2_transaction": {
"display_data": {
"payee": "Acme",
"payment_amount": "$100.99",
"payment_method": "Acme Card"
}
}
...
}
The amr claim provides information about the authenticator used to authenticate. Since PSD2.0 SCA requires multi-factor authentication, validate that the array of AMR values includes ts.bind_id.mfca which indicates that a multi-factor biometric authenticator was used. For example:
{
...
"amr": ["ts.bind_id.ama", "ts.bind_id.mfca"],
...
}

Step 5: Test Your Integration

Once you complete your integration with BindID, test your integration (for an SMS flow) as follows:

Trigger an transaction request for a test user, which calls the backend API described in step 2.
The user should receive an SMS message that includes a link.
The user clicks the link to initiate an transaction flow from their mobile device.
The BindID service appears in the browser of their mobile device.
The user approves the transaction on the mobile device.
The user runs the biometric authentication process on the mobile device.
Your application should obtain the user token as described in step 3, and compare it with the user record you have in your system.

Transaction Quick Start: Server#

Step 1: Get Your BindID Credentials#

Step 2: Initiate Transaction#

Step 3: Get User Token#

Step 4: Validate User Token#