Login 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 perform a backend BindID integration to log users into your web application. For example, you can obtain an authentication link to embed in a QR code, which will initiate a BindID authentication flow on their mobile device when the user scans the QR. As opposed to a direct BindID web integration, this provides a more native experience since your web application does not redirect to or from BindID as part of the authentication flow. Learn more about BindID

Note: If you need to receive notifications when users open an authentication link and finish authentications flows, see the guide.

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: Get Your Link to BindID

Your application can initiate an out-of-band authentication flow for a user by sending the BindID service a backchannel authentication request. The request can either be used to obtain a direct link (for example, to embed in a QR code) or to send the user a link by SMS. When opened, this link will initiate an authentication process.

To initiate an authentication flow by displaying a QR code, send the following HTTP POST request, after substituting the field values as described below, and embed the returned link in a QR code that is displayed to your users.

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%20email%20phone&channel=%7B%22type%22%3A%22direct_link%22%7D

Field	Substitute with...
`[CLIENT_ID]`	Client ID obtained in step 1.
`[CLIENT_SECRET]`	Client Secret obtained in step 1.

The response to this request will include a link, which should be encoded and displayed as QR code in your application, and 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]",
    "link": "[LINK]",
    "interval": "[POLLING_INT]"
    "expires_in": "[EXPIRATION_TIME]"
}

Field	Description
`[AUTH_REQ_ID]`	Authentication request identifier to use to obtain the user token in step 3.
`[LINK]`	Link for initiating a BindID authentication flow.
`[POLLING_INT]`	The minimum time interval required between each BindID Service poll (see 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.

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 authentication flow is completed, the response to this request will be an HTTP 200 response with an authorization_pending error. During this time, the web application can display a waiting page or animation.

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 flow 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.
`[EXPIRATION_TIME]`	Time in seconds until the access token expires.
`[ID_TOKEN]`	JWT encoding identifying info and other info about the authenticating user.

Step 4: Handle User Token

The ID token ([ID_TOKEN]) received in step 3 contains various user information as claims. This user may either be already known to BindID, or a new user.

If the user is unknown to BindID, the ID token will not include the bindid_alias claim. The application should respond by taking the user through a registration process where the application establishes user identity (see step 5). Afterwards, the application should set a BindID alias for the user so that subsequent logins will be associated with it.
If the user is known to BindID, the ID token will include the bindid_alias claim. Your application should look up this value within its user-store to identify the application user to which this alias is registered, and use that user for the rest of the session.

Step 5: Register New User

If the ID token received in step 4 indicates the user is unknown to BindID, the application should:

Validate the user’s identity. Your web application should run its existing authentication process to authenticate the user (e.g., using username and password). Whichever process you choose to run should establish the identity of the user in your web application. We recommend explaining to the user that you only need their username and password this time to enable Biometric Login.
Define the BindID Alias for the user. The Alias is an identifier that BindID will return to your application every time the user completes a successful authentication process. Whether the alias is a new identifier you generate only for BindID purposes, or an existing internal user identifier that the application already uses, it must be unique for the user. You should not use the same Alias for different users of your application.

Record that BindID Alias on the BindID service. To set the BindID Alias for the BindID user, your application server should send the following HTTP POST request:

POST /session-feedback HTTP/1.1
Host: api.bindid-sandbox.io
Content-Type: application/json
Authorization: BindIdBackend AccessToken [ACCESS_TOKEN]; [FEEDBACK_AUTH_VALUE]

{
  "subject_session_at": [ACCESS_TOKEN],
  "reports": [
    {
      "type": "authentication_performed",
      "alias": [BINDID_ALIAS],
      "time": [AUTHENTICATION_TIME]
    }
  ]
}

Field	Substitute with...
`[ACCESS_TOKEN]`	Access token received in step 3.
`[BINDID_ALIAS]`	BindID Alias to assign to the BindID user. NOTE: Consider that the ID token may be exposed to the client before passing sensitive information in the alias.
`[AUTHENTICATION_TIME]`	Time when the user was authenticated, expressed as the number of seconds since 1970-01-01 00:00. You can use the current time at the time of this request.
`[FEEDBACK_AUTH_VALUE]`	Token validating this request. This should be computed by the application server by computing HMAC-SHA256 over the `[ACCESS-TOKEN]` value, using the Client Secret obtained in step 1 as the secret. The HMAC-SHA256 computation result is then included encoded with Base64 encoding. See sample below.

This sample Java code generates the [FEEDBACK_AUTH_VALUE] and constructs the Authorization header value:

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.UnsupportedEncodingException;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
     
    public static String calculateAuthorizationHeaderValue(String clientSecret, String bindIdAccessToken) throws UnsupportedEncodingException, InvalidKeyException, NoSuchAlgorithmException {

        // Create and initialize the Mac instance
        Mac mac = Mac.getInstance("HmacSHA256");
        byte[] keyBytes = clientSecret.getBytes(StandardCharsets.UTF_8);
        SecretKeySpec keySpec = new SecretKeySpec(keyBytes, "HmacSHA256");
        mac.init(keySpec);
 
        // Calculate the MAC on the BindID AccessToken
        byte[] signedBytes = mac.doFinal(bindIdAccessToken.getBytes(StandardCharsets.UTF_8));
 
         // Encode the signed bytes to base64
        String encodedResult = Base64.getEncoder().encodeToString(signedBytes);
 
        // Create the Authorization Header value
        return "BindIdBackend AccessToken " + bindIdAccessToken + "; " + encodedResult;
    }

Step 6: Test Your Integration

Once you complete your integration with BindID, test your integration (for a direct link flow) as follows:

Trigger an authentication request for a test user in your application, which calls the backend API described in step 2.
A link embedded in a QR code should be displayed in the application.
Use a mobile device to scan the QR code and initiate an authentication flow.
The BindID service appears in the browser of your mobile device.
Approve the authentication on the mobile device.
Run 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.
Your application should run the authentication process for the user if this is the first time the user runs BindID from your application.

Login Quick Start: Server#

Step 1: Get Your BindID Credentials#

Step 2: Get Your Link to BindID#

Step 3: Get User Token#

Step 4: Handle User Token#

Step 5: Register New User#

Step 6: Test Your Integration#