Login Quick Start: Web

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 integrate BindID into your web application—including the changes required for your login page and backend application. Since BindID implements the OpenID Connect (OIDC) standard, the integration steps are similar to other OIDC-based services like Sign in with Google. Learn more about BindID

Step 1: Configure Your Application

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:

Set the allowed redirect URIs—Specify the list of pages to which users are allowed to be redirected after authentication.
Get your BindID credentials—Obtain the client ID and client secret used to identify your web application to the BindID Service.

Step 2: Configure SDK in Login Page

Your page can access all the BindID functionality by loading the BindID SDK. Add the code used to load the BindID SDK to your front-end web application, by including the following HTML tags:

<script src="https://polyfill.io/v3/polyfill.min.js?features=Promise%2CPromise.prototype.finally%2CTextDecoder%2CTextEncoder%2CObject.entries"></script>
<script src="https://signin.bindid-sandbox.io/bindid-sdk/transmit-bind-id-sdk.js" defer></script>

You also need to configure the BindID SDK with the client ID and the redirect URI from step 1. To do this, add the following meta tags before the script tag used to load the SDK:

<meta name="xm-bind-id-client_id" content="[CLIENT_ID]">
<meta name="xm-bind-id-redirect_uri" content="[REDIRECT_URI]">

where [CLIENT_ID] should be replaced with your client ID, and [REDIRECT_URI] should be replaced with the redirect URI you provided in order to obtain your BindID credentials.

Step 3: Add Login Button

Add the button that will initiate the BindID login process by including a snippet like the one below in your login page. The recommended label for the button is “Biometric Login”.

<button class='xm-bind-id-button'>Biometric Login</button>

Including the xm-bind-id-button class tells the BindID SDK to initiate an authentication process once this button is clicked. Once clicked, the browser navigates to the BindID service.

Step 4: Create Redirect Page

Upon completing authentication, BindID redirects to the Redirect URI provided in step 1. The URL encodes the BindID authentication result. Your application should respond to this URL by serving a web page that uses the BindID SDK to extract and process the authentication result.

This redirect page should load and initialize the BindID SDK by including the HTML tags below, where [CLIENT_ID] should be replaced with your client ID:

<meta name="xm-bind-id-client_id" content="[CLIENT_ID]">
...
<script src="https://polyfill.io/v3/polyfill.min.js?features=Promise%2CPromise.prototype.finally%2CTextDecoder%2CTextEncoder%2CObject.entries"></script>
<script src="https://signin.bindid-sandbox.io/bindid-sdk/transmit-bind-id-sdk.js" defer></script>

Next, the page should use the BindID SDK to process the authentication result. For example:

<body>
 …
 <script>
   function sendAuthCodeToServer(authCode) {
    // Add code to send the authCode to your application server here
   }
   function handleError(err) {
    // Add code to process the authentication error here
   }
   window.XmBindId.processRedirectResponse()
    .then(res => { sendAuthCodeToServer(res.code); },
        err => { handleError(err); })
 </script>
 …
</body>

The functions in the snippet above should be implemented as follows:

sendAuthCodeToServer should send the authorization code received upon successful authentication to your server, where it will be processed to retrieve user info (see step 5).
handleError should respond to an authentication error, possibly by presenting a suitable message to the user.

Step 5: Get User Token

To retrieve user information, the authorization code that was sent to your application server in step 4 should now be sent to the BindID service using a backend API, along with the client secret obtained in step 1. The authorization code will be exchanged for a user token.

Send the following HTTP POST request, after substituting the tokens as described below:

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

grant_type=authorization_code&code=[AUTH_CODE]&redirect_uri=[REDIRECT_URI]&client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]

Token	Substitute with...
`[AUTH_CODE]`	Authorization code received from the client in step 4.
`[CLIENT_ID]`	Client ID obtained in step 1.
`[CLIENT_SECRET]`	Client Secret obtained in step 1.
`[REDIRECT_URI]`	Redirect URI set in step 1.

The response to this request will include a JWT token encoding the user information:

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

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

Token	Description
`[ACCESS_TOKEN]`	Access token used to set the user’s alias in step 4.
`[EXPIRATION_TIME]`	Time in seconds until the access token expires.
`[ID_TOKEN]`	JWT encoding identifying info and other info about the authenticating user.

Step 6: Handle User Token

The ID token ([ID_TOKEN]) received in step 5 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 7). 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 7: Register New User

If the ID token received in step 5 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]
    }
  ]
}

Token	Substitute with...
`[ACCESS_TOKEN]`	Access token received in step 5.
`[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 8: Test Your Integration

Once you complete your integration with BindID, test your integration as follows:

Run the login webpage and click the BindID login button.
The page should redirect to the BindID Sandbox environment.
You should see your logo as part of the page.
A QR code and instructions on how to scan the QR with the mobile device should appear.
Use the mobile device to scan the QR code.
The BindID service will appear in the browser of your mobile device with your logo.
Approve the information in the mobile device.
Run the biometric authentication process on the mobile device.
If your computer includes a biometric scanner, BindID should offer you an option to register the biometric authenticator on your device.
The BindID process ends and returns to your application.
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: Web#

Step 1: Configure Your Application#

Step 2: Configure SDK in Login Page#

Step 3: Add Login Button#

Step 4: Create Redirect Page#

Step 5: Get User Token#

Step 6: Handle User Token#

Step 7: Register New User#

Step 8: Test Your Integration#