Backup code (Authentication)

This is a technical guide on how you can implement the backup code by simply following the steps below.

What is Backup Code?

The backup code is a one-time password, an 8-digit backup code that can be used to sign in to your account. It is a unique code that comes in a set of 10 for an account, and each code is unique and can be used only once.

It is one of multiple different authentication methods

When is a user able to use Backup code?

Criteria	Example	Configuration
User Verification Setup	As soon as a user provides their email address, they can use the backup code to enter it from the list provided to them.
Allowed Verification Methods	This is an app setting that can be configured in the app management's Authentication Section.

Understanding the Flow and APIs

API	Description	Link
Get the configured authentication methods	Displays the configured authentication methods on the user login page, e.g., after configuring a pattern; The user gets the pattern mfa on the login page.	Link to API
Initiate the authentication	This API is used to initiate the configured authentications, e.g., when a user clicks on the Backup code authentication, it initiates the Backup code authentication.	Link to API
Perform the authentication	After successfully authenticating by entering the Backup code, the enrollment completion will finally enroll the user.	Link to API
Continue Login After Passwordless Authentication	After successfully authenticating, you can proceed with the login process	Link to API

Step 1: Allow Backup Code in Your App

In the Admin portal, you need to make the BACKUPCODE verification type an allowed authentication method under App advanced settings.

To do that,

You can change your existing application, by navigating to Apps -> App Settings -> Edit -> Advanced Settings -> Authentication -> MFA -> Authentication -> and Add BACKUPCODE

Step 2: Rendering the User Verification Methods

Before initiating the Backup Code, you will perform an Authorization (Authz) Call and use the requestId in the upcoming calls.

The first call will be to get the configured verification methods for a user. Based on the response, you provide a selection of verification methods for your user. Below is a demo of how this can look by presenting different verification icons.

Call the configured verification methods of a user. This will filter the user configured verification methods and the app level configuration.

Request

curl --location '{{base_url}}/verification-srv/public/graph/user/setup' \
--header 'content-type: application/json' \
--data-raw '{
    "request_id": "{{requestId}}",
    "identifier": "{{identifier}}"
}'

The response contains a list of all verification methods the user could use. It already filters if the client allows the verification method. The identifier field accepts email, mobile number, or username - whichever identifier type the user registered with.

Note: No medium_id is generated for the backup code. The backup code verification method does not require a medium_id since it uses pre-generated backup codes.

Response

{
    "configured_list": [
        {
            "type": "BACKUPCODE"
        },
        {
            "type": "EMAIL",
            "mediums": [
                {
                    "id": "72873fb5-0c21-4f15-b4f5-c4a0824e09f4",
                    "key_name": "aca******as@w***s.in"
                }
            ]
        },
        {
            "type": "PASSWORD"
        },
        {
            "type": "PUSH",
            "mediums": [
                {
                    "id": "cb4f579f-4780-4e68-8b13-3505722aedc9",
                    "key_name": "Academy cidaas"
                }
            ]
        },
        {
            "type": "SMS",
            "mediums": [
                {
                    "id": "72873fb5-0c21-4f15-b4f5-c4a0824e09f4",
                    "key_name": "+91******159"
                }
            ]
        }
    ]
}

API	Description	Link
Get the configured authentication methods	Displays the configured authentication methods on the user login page, e.g., after configuring a pattern; The user gets the pattern mfa on the login page.	Link to API

This API requires requestId, It returns the medium_id which will be used during authentication in step 3.

Step 3: Initiating a Backup Code

The user now selects Backup Code, you need to initiate the Authentication using Backup Code as a parameter.

Request

curl --location '{{base_url}}/verification-srv/authentication/backupcode/initiation' \
--header 'content-type: application/json' \
--data-raw '{
    "usage_type": "PASSWORDLESS_AUTHENTICATION",
    "request_id": "df08cabb-4b8c-4181-9f6f-f6948802ebf7",
    "identifier": "[email protected]"
}'

The response contains a status_id and an exchange_id, those are unique for this process, and the following steps will rely on this being provided. If Status is 200, the initiation was successfully triggered.

Response

{
    "success": true,
    "status": 200,
    "data": {
        "exchange_id": {
            "exchange_id": "6915d3b2-c183-40aa-aa2c-e9c82eedda09",
            "expires_at": "2024-01-12T13:11:17.203Z",
            "_id": "93f9d23c-09cc-4947-8df6-87190430409f",
            "createdTime": "2024-01-12T12:41:17.204Z",
            "updatedTime": "2024-01-12T12:41:17.204Z",
            "__ref": "4908129189115a60:736d055ffe8243d2:4908129189115a60:0",
            "id": "93f9d23c-09cc-4947-8df6-87190430409f"
        },
        "sub": "c873de5d-53ce-4570-ae67-0fce41722138",
        "status_id": "c0667444-1f71-45c5-8f8c-1f7bb0c61394"
    }
}

API	Description	Link
Initiate the authentication	This API is used to initiate the configured authentications, e.g., when a user clicks on the touch id authentication, it initiates the touch id authentication.	Link to API

It returns an exchange_id and masked sub which is required as input for the Step 4

Step 4: Performing the Authentication

Using the exchange_id and pass_code sent in the request the actual authentication will now take place. The verification method is specified in the URL path parameter (backupcode), so the type field is not required in the request body.

Note: The backup code is a one-time password. Once used, it becomes inactive and cannot be reused.

Request

curl --location '{{base_url}}/verification-srv/authentication/backupcode/verification' \
--header 'content-type: application/json' \
--data '{
    "exchange_id": "d594490e-a4da-4433-81a8-2009744ebb48",
    "pass_code": "56944921"
}'

The response returns another exchange_id and status 200 success if it is performed successfully.

Response

{
    "success": true,
    "status": 200,
    "data": {
        "exchange_id": {
            "exchange_id": "94669e02-d666-4be5-8f4d-130664c6d57c",
            "expires_at": "2024-01-12T13:24:40.706Z",
            "_id": "a69bb211-387b-47b1-b19d-5da3b91c15ba",
            "createdTime": "2024-01-12T12:54:40.709Z",
            "updatedTime": "2024-01-12T12:54:40.709Z",
            "__ref": "1ede4f31b521fc74:76e4c2fc2e83313a:1ede4f31b521fc74:0",
            "id": "a69bb211-387b-47b1-b19d-5da3b91c15ba"
        },
        "sub": "521bb9c7-eda9-4070-ab28-551825a3b502",
        "status_id": "e3f1ad0e-b32d-4304-8861-d8dff503396a"
    }
}

It returns for a exchange_id and status_id which is required as input for Step 5. The exchange_id did change between the above steps.

Continue the login process by performing the login Call. This API will redirect when the authentication was successful to your provided redirect_uri including a code or an access_token depending on the OAuth2 Flow used. Link to API

curl --location '{base_url}/login-srv/verification/login' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'requestId=df08cabb-4b8c-4181-9f6f-f6948802ebf7' \
--data-urlencode 'exchange_id=e8896cfe-8371-4d79-b8d5-ae8f14c5666c' \
--data-urlencode 'verificationType=backupcode' \
--data-urlencode 'sub=b0dd23-1a2d-40eb-9gb-2ba3cc1942b' \
--data-urlencode 'status_id=710792ba-32f9-4d2d-8584-fefa3a6d94b8' \
--data-urlencode 'rememberMe=true' 

API	Description	Link
Perform the authentication	After successfully authenticating the user can receive an access token	Link to API
Continue Login After Passwordless Authentication	After successfully authenticating, you can proceed the login process	Link to API

Implementation using SDK

This Implementation Guide is based on the default hosted pages, which use an Angular framework based on Typescript. It can be implemented in any other programming language as well.

As a first step, you are redirected to the login page. This section starts to show the APIs to be called when reaching this page

To install the cidaas-sdk please perform the following command

npm install cidaas-javascript-sdk

The import to your webapp will be done by using:

this.cidaas_sdk = new WebAuth(options)

Step 1: Rendering the User Verification Methods

Call the getMFAList API to get all the MFA that is configured for the user.

const queryParams = new URL(window.location.href).searchParams; // get query params from window.location
const payload = {
    sub: queryParams.get("sub"), // subId of user got from query params
    requestId: queryParams.get("requestId"), // requestId identifying active login flow
}
this.cidaas_sdk.getMFAList(payload)
    .then((response) => {
        if (!response.data || response.status !== 200) {
            // handle error
            return;
        }
        const mfaList = response.data;
        // Populate mfa list
        showMFAList(mfaList); // Add implementation to parse mfa list and show in UI
    })
    .catch((e) => {
        // handle error
    });
});

Using the response of this API call, the user can render the UI to display all verification methods that they are allowed and able to use. Furthermore, it is used as input for the next Endpoint.

Step 2: Initiating a Backup Code

In this example, the mfaItems are the items returned by the above API, after user selects the authentication method (Backup Code) it initiates the verification process by calling initiateMFAV2 API with usage_type. request_id & type, The API returns a response containing an exchangeId that is required to call authentication API.

let exchangeId: string = "";
const queryParams = new URL(window.location.href).searchParams; // get query params from window.location
const requestId = queryParams.get("requestId");
const identifier = queryParams.get("identifier") as string; // The identifier can be email, username, or mobile number
const payload = {
    usage_type: "PASSWORDLESS_AUTHENTICATION",
    request_id: requestId,
    identifier: identifier
}

// initiate api call which returns exchange_id
this.cidaas_sdk.initiateMFAV2(payload)
    .then((response) => {
        if(response || response.status !== 200){
            // handle error
            return;
        }
        const data = response.data;
        this.exchangeId = data?.exchange_id?.exchange_id;
    })
    .catch(error=>{
        // handle error
    })

Step 3: Performing the Authentication

The next step is to perform the authentication. Thereby the exchangeId as well as verificationType will be provided in the next authentication step. The requestId stays the same.

const exchangeId = this.exchangeId;  // This is generated after the initiate process  (Step 3)
const queryParams = new URL(window.location.href).searchParams; // get query params from window.location
const requestId = queryParams.get("requestId"); 
let payload = {
    exchange_id: exchangeId,
    pass_code: "23861567" // This is one of the backup codes that is generated for the user, replace with your backup code. Note: The verification method (backupcode) is specified in the API endpoint URL path, not in the request body.
};

this.cidaas_sdk.authenticateMFAV2(payload)
    .then((response) => {
        if(response || response.status !== 200) {
            // handle error
            return;
        }
        const data = response.data;
        this._initiatePasswordlessLogin(data); // initiate the login process
    })
    .catch((error) => {
        // handle error
    })

Step 4: Continue the Login Process

The passwordlessLogin will continue the login process and finally the user will be redirected to the provided redirect_uri including a token or code, depending on the OAuth2 grant (OAuth2 flow) that was used during initiating the authentication process.

_intitiatePasswordlessLogin = async (response) => {
    const queryParams = new URL(window.location.href).searchParams; // To get query params from window.location
    const requestId = queryParams.get("requestId");
    let options = {
        requestId: requestId,
        exchange_id: response.exchange_id.exchange_id,
        verificationType: "backupcode", // The verification method type (backupcode) 
        sub: response.sub,
        status_id: response.status_id, // The status ID is generated after authenticate process
    };
    await this.cidaas_sdk.passwordlessLogin(options) // to redirect to the home page after successful login
};

Need Support?

Please contact us directly on our support page.