FIDO2 (Authentication)

This is a technical guide on how to implement the FIDO2 authentication by simply following the steps below.

What is FIDO2?

FIDO2 enables users to leverage common devices to easily authenticate to online services in both mobile and desktop environments.

It is one of multiple different authentication methods.

When is a user able to use FIDO2 authentication?

Criteria	Example	Configuration
User Verification Setup	The user has to log in to the portal and can enroll the FIDO2 using either the cidaas App or any other custom Authenticator App
Allowed Verification Methods	An app setting to configure FIDO2 authentication as a login method.

Understanding the Flow and APIs

API	Description	Link
Get the configured authentication methods	Displays the configured authentication methods of a user	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
Finish up the authentication and continue login	Continue the login process once the authentication is successful.	Link to API

Step 1: Allow FIDO2 in the App settings

In the Admin portal, you need to make the FIDO2 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 -> FIDO2.

Step 2: Rendering the user verification methods

Before initiating the FIDO2 authentication, perform an Authorization (Authz) Call and generate the requestId, then use it in the upcoming API 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.

API	Description	Link
Get the configured authentication methods	Displays the configured authentication methods of a user	Link to API

Implementation using Javascript SDK

To authenticate the user via FIDO2 using the JavaScript SDK, follow the below steps

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:

const cidaas = new CidaasSDK.WebAuth(options);

Step 1: Rendering the user verification methods

const mfaList = await this.cidaas.getMFAList({
    identifier: e.identifier,
    request_id: this.route.snapshot.queryParams['requestId'],
});

The UI will be rendered based on this response by displaying all configured verification methods.

Step 2: Initiating a FIDO2 authentication

When the user selects FIDO2 in the list of authentication methods, the initiateMFA method needs to be called.

const payload: IInitiateMFAPayload = {};
    
// pushIndex is the index of the type FIDO2 in the list and deviceIndex is the index of the device in the mediums list
const medium_id = mfaList[pushIndex]['mediums'][deviceIndex]['id']; 
    
// usage_type should be PASSWORDLESS_AUTHENTICATION or MULTIFACTOR_AUTHENTICATION or INITIAL_AUTHENTICATION
payload['usage_type'] = 'PASSWORDLESS_AUTHENTICATION';
    
// requestId should come in the login hosted page query param
payload['request_id'] = this.route.snapshot.queryParams['requestId'];

payload['medium_id'] = medium_id;
payload['type'] = this.verificationType;

// Optional: For cross-domain FIDO2 authentication
payload['domainURL'] = 'https://yourdomain.com';
    
const initResp = await this.cidaas.initiateMFA(payload);

Step 3: Perform the authentication

When the user completes the FIDO2 browser authentication, the authenticateMFA method needs to be called.

function authenticate() {
    let publicKey = generatePublicKeyCred(initResp.server_challenge);
    this.navigator.credentials.get({ publicKey }).then((response) => {
        // create the FIDO2 public key credential, you can use any other methods to generate this public key credential
        let publicKeyCredential = publicKeyCredentialToJSON(response);
    
        // setting up the payload for the FIDO2 authentication
        const authenticatePayload: any = {
            sub: initResp.sub,
            exchange_id: initResp.exchange_id.exchange_id,
            type: this.verificationType,
            fido2_client_response: {
                client_response: publicKeyCredential,
                fidoRequestId: initResp.fido2_entity.fidoRequestId,
            }
        };
        const authenticateResp = await this.cidaas.authenticateMFA(authenticatePayload);
    }
}

function generatePublicKeyCred(serverChallenge) {
    // decode base64 string of challenge
    serverChallenge.challenge = this.decode(serverChallenge.challenge);
    for (let allowCred of serverChallenge.allowCredentials) {
        // decode base64 string of credId
        allowCred.id = this.decode(allowCred.id);
    }
    return serverChallenge;
}

function publicKeyCredentialToJSON(pubKeyCred) {
    if (pubKeyCred instanceof Array) {
        let arr: any = [];
        for (let i of pubKeyCred) { 
            arr.push(this.  publicKeyCredentialToJSON(i)) 
        }
        return arr;
    }
    if (pubKeyCred instanceof ArrayBuffer) {
        return this.encode(pubKeyCred);
    }
    if (pubKeyCred instanceof Object) {
        let obj = {};
        for (let key in pubKeyCred) {
            obj[key] = this.publicKeyCredentialToJSON(pubKeyCred[key]);
        }
        return obj;
    }
    return pubKeyCred;
}

Step 4: Continue the Login Process

Once the user successfully completed the authentication, finish the login process by calling the passwordlessLogin method. This will redirect to the provided redirect_uri including a code or an access_token depending on the OAuth2 flow used.

let options = {
  requestId: this.route.snapshot.queryParams['requestId'],
  verificationType: this.verificationType,
  sub: this.sub,
  status_id: this.status_id
};
    
this.cidaas.passwordlessLogin(options);

warning

Need Support?

Please contact us directly on our support page or reach out to cidaas support at [email protected].