FIDO2 Authentication API — A Custom Approach

Introduction to FIDO Authentication

FIDO Authentication is a set of open technical specifications that define user authentication mechanisms to reduce the reliance on passwords. It offers expanded authentication options including strong single factor (passwordless), strong two factor, and multi-factor authentication.

You can refer to my previous blog post linked here to learn about FIDO2 Authentication in detail.

In this article, we will dive deep into FIDO2 Authentication.

WSO2 Identity Server 5.10.0 FIDO2 Authentication API

Why FIDO2 Authentication API?

The WSO2 Identity Server currently provides only the FIDO Registration API Endpoints for use. FIDO Authentication is strongly coupled in the existing web application therefore FIDO Authentication mechanism is not exposed.

In this article, The FIDO2 Authentication custom API is explained which is decoupled from the existing authentication mechanism as a second-factor authentication option to expose authentication using FIDO devices functionality.

NOTE: The following approach is a custom REST API implemented to expose the FIDO2 Authentication Flow available in the WSO2 Open Source Packages.

There are two endpoints required to authenticate with the server via FIDO devices in this custom approach,

• Start Authentication: start-authentication(startAuthRequest)
• Finish Authentication: finish-authentication(finishAuthRequest)

Note that the user should be registered with the service prior to using the FIDO2 Authentication API. Refer to the prerequisites section below.

Following is the flow of FIDO2 Authentication process from the client to the server side of the application,

FIDO2 Authentication Flow

Start Authentication API

The start-authentication API requires the username, tenantDomain, storeDomain, and the appId properties in the request body.

• username: The username of the relevant user. For example: Jenny.
• tenantDomain: The domain name of the tenant. For example: carbon.super.
• storeDomain: The domain name of the user store. For example: PRIMARY.
• appId: The origin of the client application. For example: https://localhost:9443.

Note: Since the API is restricted, make sure you pass the Authorization and the appropriate Content-typeHeaders in the request.

Following is a sample usage of the start-authentication API,

//start authentication API call
async function callStartAuth() {

    const body = {
        "username": "Jenny",
        "tenantDomain": "carbon.super",
        "storeDomain": "PRIMARY",
        "appId": "http://localhost:3000"
    };

    let headers = {
        'accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Basic y123456swAWEJhcd'
    };

    try {
        let response = await axios.post('https://localhost:9443/wso2/rest/v1/fido2/start-authentication', body, {headers});

        if (response.status == 200) {
            return response.data;
        }
    } catch (err) {
        alert(err.response.data.message)
    }
};

Finish Authentication API

The finish-authentication API requires the username, tenantDomain, storeDomain and the signed responseJson properties in the request body.

• username: The username of the relevant user. For example: Jenny.
• tenantDomain: The domain name of the tenant. For example: carbon.super.
• storeDomain: The domain name of the user store. For example: PRIMARY.
• responseJson: The signed challenge from the client device. This is a string converted object. For example:

Challenge signed by the client device

Note: Since the API is restricted, make sure you pass the Authorization and the appropriate Content-typeHeaders in the request.

Following is a sample usage of the finish-authentication API,

//finish authentication API call
async function finishAuth(content) {
    let headers = {
        'accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Basic y123456swAWEJhcd'
    };
    let body = {
        "username": "Jenny",
        "tenantDomain": "carbon.super",
        "storeDomain": "PRIMARY",
        "responseJson": JSON.stringify(body)
    }
    try {
        let response = await axios.post('https://localhost:9443/wso2/rest/v1/fido2/finish-authentication', body, {headers});
        if (response.status == 204) {
            return response;
        }
    } catch (err) {
        alert(err.response.data.message)
    }
}

Hope you guys liked my article on introducing the FIDO2 Custom Authentication API using WSO2 Identity Server version 5.10.0. Let me know in the comments if you tried it.