FIDO2 WebAuthn API endpoints

Updated July 16, 2020

Use this guide to configure the SecureAuth Authentication API to enable end users to register their FIDO2-compliant devices and use them to authenticate into your resources. The /fido endpoints allow you to enroll end users, validate end users logging in, update tokens, and delete tokens.

End users can then securely access resources, such as Office 365, using FIDO2 WebAuthn-enabled devices that include bound /platform authenticators, such as mobile, laptop, and desktop devices using passwords, PINs and biometrics, and roaming authenticators, such as USB, Bluetooth, and NFC tokens attached to multiple devices. (A bound / platform authenticator is an operating system that supports the WebAuthn protocol.)

Prerequisites

SecureAuth® Identity Platform version 20.06 or later
Complete the steps in the Authentication API Guide.

FIDO2 API workflow

The Authentication API uses four endpoints for FIDO2 using WebAuthn.

Embed the functions in the Javascript snippet example into your JavaScript or HTML file.
Use the two /fido/enrollment endpoints via POST to enroll end users.
After a successful FIDO2 enrollment, end users can use their FIDO2-compliant device to log into the login pages to authenticate.
When the end user logs into their login pages to access a resource with the same device, the second endpoint, /fido/login, is called via POST to validate the device associated to the end user.
The current device information is compared with the registered device for authentication.
If a device match is found and is validated, the end user can continue with authentication.
If a device match for the end user is not found, then go back to step 2 and enroll the end user's device again.
To update a device, the fido/tokens endpoint is called via PUT.
To delete a device, the fido/tokens endpoint is called via DELETE.

Javascript snippet

The following is an example of a JavaScript snippet that you might run. Several other WebAuthn features are also available for your use. Learn more on the Web Authentication: An API for accessing Public Key Credentials Level 1 external page.

The following example shows the functions to embed into a JavaScript file to begin and complete FIDO2 enrollment and login.

$(function () {
    $('#btnEnroll').click(function () {
        console.log("enroll");
        fetch("/api/fido/enrollment/begin/", {
            method: "POST"
        }).then(function (response) {
            response.json().then(beginEnrollment);
        });
    });
    $('#btnLogin').click(function () {
        fetch("/api/fido/login/begin/?username=" + $('#username').val(), {
            method: "POST"
        }).then(function (response) {
            response.json().then(beginLogin);
        });
    });
    function toArray(value) {
        return Uint8Array.from(atob(value), c => c.charCodeAt(0));
    }
    function fromArray(value) {
        return btoa(String.fromCharCode.apply(null, new Uint8Array(value))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
    }
    function beginEnrollment(pkOptions)
    {
        console.log(pkOptions);
        pkOptions.publicKey.challenge = toArray(pkOptions.publicKey.challenge);
        pkOptions.publicKey.user.id = toArray(pkOptions.publicKey.user.id);;
        console.log(pkOptions);
        navigator.credentials.create({
            publicKey: pkOptions.publicKey
        }).then(function (credential) {
            console.log("Credential generated");
            finishEnrollment(credential)
        });
    }
    function completeEnrollment(credential)
    {
        var clientDataJSON = fromArray(credential.response.clientDataJSON);
        var attestationObject = fromArray(credential.response.attestationObject);
        var rawId = fromArray(credential.rawId);
        var payload = {
            id: credential.id,
            rawId: rawId,
            type: credential.type,
            response: { attestationObject, clientDataJSON }
        }
        console.log(payload);
        fetch("/api/fido/enrollment/complete/", {
            method: "POST",
            body: JSON.stringify(payload),
            headers: { 'Content-Type': 'application/json' }
        }).then(function (response) {
            console.log(response);
            response.json().then(function (v) {
                alert(JSON.stringify(v));
            });
        });
    }
    function beginLogin(pkOptions) {
        console.log(pkOptions);
        pkOptions.publicKey.challenge = toArray(pkOptions.publicKey.challenge);
        console.log(pkOptions);
        navigator.credentials.get({
            publicKey: pkOptions.publicKey
        }).then(function (credential) {
            console.log("Credential read");
            finishLogin(credential)
        });
    }
    function completeLogin(credential) {
        var clientDataJSON = fromArray(credential.response.clientDataJSON);
        var authenticatorData = fromArray(credential.response.authenticatorData);
        var rawId = fromArray(credential.rawId);
        var signature = fromArray(credential.response.signature);
        var userHandle = fromArray(credential.response.userHandle);
        var payload = {
            id: credential.id,
            rawId: rawId,
            type: credential.type,
            response: {
                authenticatorData,
                clientDataJSON,
                signature,
                userHandle
            }
        }
        console.log(payload);
        var formValues = new FormData();
        formValues.append("formValues", JSON.stringify(payload));
        fetch("/api/fido/login/complete/", {
            method: "POST",
            body: formValues,
        }).then(function (response) {
            console.log(response);
            response.json().then(function (v) {
                alert(JSON.stringify(v));
            });
        });
    }
});

GET endpoint

The GET method has one endpoint: /users/<username>/factors.

/users/<username>/factors

Use the GET /factors method to access the end user's profile and generate a response containing a list of factors.

The factors are returned if you use /api/v2 and the user status in Active Directory matches one of the following:

InvalidGroup
Disabled
Lockout
PasswordExpired
AccountExpired

HTTP Method	URI	Example	Identity Platform version
GET	`/api/v2/users/<username>/factors`	https://secureauth.company.com/secureauth2/api/v2/users/jsmith/factors	v20.06 or later

GET retrieval is successful in the following situations:

The response includes a status, message, and user ID.
A valid status signifies that an account can be accessed and changed:
- valid = User Id found.
- not_found = User Id not found.
- invalid_group = User Id is not associated with a valid group.
- disabled = Account is disabled.
- lock_out = Account is locked out.
- password_expired = Password is expired for account.
- change_password = Password must be changed on login. (AD-specific)
- account_expired = Account is expired. (AD-specific)

Success response	Failed response / error
... { "status": "found", "message": "User Id found.", "user_id": "jsmith", "factors": [ { "type": "email", "id": "Email1", "value": "jsmith@example.com" }, { "description": "macbook", "value": "fingerprint", "modifiedAt": "2020-06-23T18:00:56Z", "type": "fido2", "id": "01541d434cc9aafe5fc3f58be75434fcf2b8e49a9b914dcb90a2d14d6502...", "createdAt": "2020-06-23T18:00:56Z" } ] }, ...	{ "status": "not_found", "message": "User Id not found." } HTTP Status 404 { "status": "invalid_group", "message": "User Id is not associated with a valid group." } HTTP Status 200 { "status": "disabled", "message": "Account is disabled." } HTTP Status 200 { "status": "lock_out", "message": "Account is locked out." } HTTP Status 200 { "status": "password_expired", "message": "Password is expired for account." } HTTP Status 200 { "status": "change_password", "message": "Password must be changed on login." } HTTP Status 200

Success response

Failed response / error

...
{
"status": "found",
"message": "User Id found.",
"user_id": "jsmith",
"factors": [
  {
    "type": "email",
    "id": "Email1",
    "value": "jsmith@example.com"
  },
  {
    "description": "macbook",
    "value": "fingerprint",
    "modifiedAt": "2020-06-23T18:00:56Z",
    "type": "fido2",
    "id": "01541d434cc9aafe5fc3f58be75434fcf2b8e49a9b914dcb90a2d14d6502...",
    "createdAt": "2020-06-23T18:00:56Z"
  }
  ]
},
...

{
  "status": "not_found",
  "message": "User Id not found."
}
HTTP Status 404

{
  "status": "invalid_group",
  "message": "User Id is not associated with a valid group."
}
HTTP Status 200

{
  "status": "disabled",
  "message": "Account is disabled."
}
HTTP Status 200

{
  "status": "lock_out",
  "message": "Account is locked out."
}
HTTP Status 200

{
  "status": "password_expired",
  "message": "Password is expired for account."
}
HTTP Status 200

{
  "status": "change_password",
  "message": "Password must be changed on login."
}
HTTP Status 200

POST endpoints

The POST method has two endpoints: /fido/enrollment and /fido/login.

/fido/enrollment: Enables the Authentication API to set end user FIDO2 enrollment
/fido/login: Authenticates the end user through the registered FIDO2 device when logging into resources

/fido/enrollment

The /fido/enrollment endpoint uses thePOST method to begin and complete the enrollment.

/begin initiates the WebAuthn registration process.
/complete registers the device based on the WebAuthn registration process.

The Identity Platform returns a response stating whether the enrollment succeeded or failed.

HTTP Method	Endpoint	Example	Identity Platform version
POST	`/api/v1/fido/enrollment/begin`	https://secureauth.company.com/secureauth2/api/v1/fido/enrollment/begin	v20.06 or later
POST	`/api/v1/fido/enrollment/complete`	https://secureauth.company.com/secureauth2/api/v1/fido/enrollment/complete	v20.06 or later

The following example describes the /fido/enrollment/begin endpoint response for the POST method.

JSON parameters	Success/failure response
Tip Initiate end user enrollment by including rp_id and user_id in the parameters. where rp_id is the name of the SecureAuth local host and user_id is the username. Example request for the POST: { "rp_id": "secureauth.company.com", "user_id": "jsmith" }	The following example shows the payload required in the `beginEnrollment` function in the JavaScript. { "status": "valid", "session_id": "b1db3f5a-1d67-49b9-93d1-869d74e96240", "publicKey": { "challenge": "qKyUadeT2zWNxS8ed20QF8NOve8TB2AuJqwca1HMT3E=", "rp": { "name": "SecureAuth", "id": "localhost" }, "user": { "name": "jsmith", "displayName": "jsmith", "id": "fEf+ekdURd+atlFPcCmoqQ==" }, "pubKeyCredParams": [ { "type": "public-key", "alg": -7 }, { "type": "public-key", "alg": -35 }, { "type": "public-key", "alg": -36 }, { "type": "public-key", "alg": -257 }, { "type": "public-key", "alg": -258 }, { "type": "public-key", "alg": -259 }, { "type": "public-key", "alg": -37 }, { "type": "public-key", "alg": -38 }, { "type": "public-key", "alg": -39 }, { "type": "public-key", "alg": -8 } ], "authenticatorSelection": {}, "timeout": 60000, "excludeCredentials": [ { "type": "public-key", "id": "AZRD/KjFe17xABTtNhnUEv+..." } ] } } HTTP Status 200 { "status": "invalid", "message": "rp_id not found." } HTTP Status 400 { "status": "invalid", "message": "User Id not found." } HTTP Status 400

JSON parameters

Success/failure response

Tip

Initiate end user enrollment by including rp_id and user_id in the parameters.

where rp_id is the name of the SecureAuth local host and user_id is the username.

Example request for the POST:

{
    "rp_id": "secureauth.company.com",
    "user_id": "jsmith"
}

The following example shows the payload required in the beginEnrollment function in the JavaScript.

{
    "status": "valid",
    "session_id": "b1db3f5a-1d67-49b9-93d1-869d74e96240",
    "publicKey": {
        "challenge": "qKyUadeT2zWNxS8ed20QF8NOve8TB2AuJqwca1HMT3E=",
        "rp": {
            "name": "SecureAuth",
            "id": "localhost"
        },
        "user": {
            "name": "jsmith",
            "displayName": "jsmith",
            "id": "fEf+ekdURd+atlFPcCmoqQ=="
        },
        "pubKeyCredParams": [
            {
                "type": "public-key",
                "alg": -7
            },
            {
                "type": "public-key",
                "alg": -35
            },
            {
                "type": "public-key",
                "alg": -36
            },
            {
                "type": "public-key",
                "alg": -257
            },
            {
                "type": "public-key",
                "alg": -258
            },
            {
                "type": "public-key",
                "alg": -259
            },
            {
                "type": "public-key",
                "alg": -37
            },
            {
                "type": "public-key",
                "alg": -38
            },
            {
                "type": "public-key",
                "alg": -39
            },
            {
                "type": "public-key",
                "alg": -8
            }
        ],
        "authenticatorSelection": {},
        "timeout": 60000,
        "excludeCredentials": [
            {
                "type": "public-key",
                "id": "AZRD/KjFe17xABTtNhnUEv+..."
            }
        ]
    }
}
HTTP Status 200

{
  "status": "invalid",
  "message": "rp_id not found."
}
HTTP Status 400

{
  "status": "invalid",
  "message": "User Id not found."
}
HTTP Status 400

The following example describes the /fido/enrollment/complete endpoint response for the POST method.

JSON parameters	Success/failure response
Tip Complete end user enrollment by including rp_id and user_id in the parameters. where rp_id is the name of the SecureAuth local host and user_id is the username. Example: { "rp_id": "secureauth.company.com", "user_id": "jsmith" ... } Request: The following payload is generated from the `completeEnrollment` function in the JavaScript, and is needed to build the request for this endpoint. { "user_id": "jsmith", "description": "macbook", "rawId": "L7rn85CxICtfUSDohY5qZ22BiPVMlZC1gsEulJ4nbpw", "rp_id": "secureauth.company.com", "session_id": "b1db3f5a-1d67-49b9-93d1-869d74e96240", "response": { "clientDataJSON": "eyJvcmlnaW4iOiAiaHR0cHM6Ly93ZWJ...", "attestationObject": "o0NmbXREbm9uZUdhdHRTdG10oEhh..." }, "type": "public-key", "id": "L7rn85CxICtfUSDohY5qZ22BiPVMlZC1gsEulJ4nbpw", "name": "jsmith" }	{ "status":"valid", "ok":true } HTTP Status 200 { "status": "invalid", "message": "rp_id not found." } HTTP Status 400 { "status": "invalid", "message": "User Id not found." } HTTP Status 400

JSON parameters

Success/failure response

Tip

Complete end user enrollment by including rp_id and user_id in the parameters.

where rp_id is the name of the SecureAuth local host and user_id is the username.

Example:

{
    "rp_id": "secureauth.company.com",
    "user_id": "jsmith"
    ...
}

Request:

The following payload is generated from the completeEnrollment function in the JavaScript,

and is needed to build the request for this endpoint.

{
    "user_id": "jsmith",
    "description": "macbook",
    "rawId": "L7rn85CxICtfUSDohY5qZ22BiPVMlZC1gsEulJ4nbpw",
    "rp_id": "secureauth.company.com",
    "session_id": "b1db3f5a-1d67-49b9-93d1-869d74e96240",
    "response": {
"clientDataJSON": "eyJvcmlnaW4iOiAiaHR0cHM6Ly93ZWJ...",
        "attestationObject": "o0NmbXREbm9uZUdhdHRTdG10oEhh..."
    },
    "type": "public-key",
    "id": "L7rn85CxICtfUSDohY5qZ22BiPVMlZC1gsEulJ4nbpw",
    "name": "jsmith"
}

{
   "status":"valid",
   "ok":true
}
HTTP Status 200

{
  "status": "invalid",
  "message": "rp_id not found."
}
HTTP Status 400

{
  "status": "invalid",
  "message": "User Id not found."
}
HTTP Status 400

/fido/login

The /fido/login endpoint uses the POST method to begin and complete authentication for the specified user.

/begin starts the WebAuthn authentication process.
/complete confirms that the end user was successfully authenticated through the WebAuthn authentication process.

The Identity Platform returns a response stating whether the authentication was validated or invalid.

HTTP Method	Endpoint	Example
POST	`/api/v1/fido/login/begin`	https://secureauth.company.com/secureauth2/api/v1/fido/login/begin
POST	`/api/v1/fido/login/complete`	https://secureauth.company.com/secureauth2/api/v1/fido/login/complete

The following example describes the /fido/login/begin endpoint response for the POST method.

JSON parameters	Success/failure response
Tip Begin confirmation of end user login authentication by including rp_id and user_id in the parameters. where rp_id is the name of the SecureAuth local host and user_id is the username. Example: { "rp_id": "secureauth.company.com", "user_id": "jsmith" }	The following example shows the payload required in the`beginLogin`function in the JavaScript. { "status": "found", "session_id": "f24f8bfa-db06-4b8c-ab12-8fabfde193d2", "publicKey": { "challenge": "/XdVURsy/KuWSpti5l0tAzfzwGrNUZnOcCYTR8NiC3w=", "timeout": 60000, "rpId": "localhost", "allowCredentials": [ { "type": "public-key", "id": "AZRD/KjFe17xABTtNhnUEv+ygoO8BGWT535Uo66K82A..." } ], "extensions": { "txAuthSimple": "" } } } HTTP Status 200 { "status": "valid", "message": "User Id found." } HTTP Status 200 { "status": "invalid", "message": "User Id not found." } HTTP Status 400 { "status": "invalid", "message": "rp_id not found." } HTTP Status 400

JSON parameters

Success/failure response

Tip

Begin confirmation of end user login authentication by including rp_id and user_id in the parameters.

where rp_id is the name of the SecureAuth local host and user_id is the username.

Example:

{
    "rp_id": "secureauth.company.com",
    "user_id": "jsmith"
}

The following example shows the payload required in thebeginLoginfunction in the JavaScript.

{
    "status": "found",
    "session_id": "f24f8bfa-db06-4b8c-ab12-8fabfde193d2",
    "publicKey": {
        "challenge": "/XdVURsy/KuWSpti5l0tAzfzwGrNUZnOcCYTR8NiC3w=",
        "timeout": 60000,
        "rpId": "localhost",
        "allowCredentials": [
            {
                "type": "public-key",
                "id": "AZRD/KjFe17xABTtNhnUEv+ygoO8BGWT535Uo66K82A..."
            }
        ],
        "extensions": {
            "txAuthSimple": ""
        }
    }
}
HTTP Status 200

{
  "status": "valid",
  "message": "User Id found."
}
HTTP Status 200

{
  "status": "invalid",
  "message": "User Id not found."
}
HTTP Status 400

{
  "status": "invalid",
  "message": "rp_id not found."
}
HTTP Status 400

The following example describes the /fido/login/complete endpoint response for the POST method.

JSON parameters	Success/failure response
Tip Confirm end user authentication by including rp_id and user_id in the parameters. where rp_id is the name of the SecureAuth local host and user_id is the username. Example: { "rp_id": "secureauth.company.com", "user_id": "jsmith" ... } Request: The following payload is generated from the `completeLogin` function in the JavaScript, and is needed to build the request for this endpoint. { "user_id": "jsmith", "rawId": "L7rn85CxICtfUSDohY5qZ22BiPVMlZC1gsEulJ4nbpw", "rp_id": "secureauth.company.com", "response": { "clientDataJSON": "eyJvcmlnaW4iOiAiaHR0cHM6Ly93ZWJhZG1pbi5nb3NlY3...", "authenticatorData": "A2Kl4rVc_oY1RvUM7IITS59lwBvBIfcDyXYaBPC4grABAAAAAQ", "userHandle": "Es_0A-aCTBill2UB2H7dxw", "signature": "MEUCIQCbn0voS0WZow5EqYR9o5rTHMoscPUruaZSBQl5VUs1Dw..." }, "type": "public-key", "id": "L7rn85CxICtfUSDohY5qZ22BiPVMlZC1gsEulJ4nbpw" }	{ "status":"found" } Status code: 200 { "status": "invalid", "message": "Request validation failed with: rp_id was not present." } HTTP Status 400 { "status": "invalid", "message": "Request validation failed with: User Id was not present." } HTTP Status 400

JSON parameters

Success/failure response

Tip

Confirm end user authentication by including rp_id and user_id in the parameters.

where rp_id is the name of the SecureAuth local host and user_id is the username.

Example:

{
    "rp_id": "secureauth.company.com",
    "user_id": "jsmith"
    ...
}

Request:

The following payload is generated from the completeLogin function in the JavaScript,

and is needed to build the request for this endpoint.

{
    "user_id": "jsmith",
    "rawId": "L7rn85CxICtfUSDohY5qZ22BiPVMlZC1gsEulJ4nbpw",
    "rp_id": "secureauth.company.com",
    "response": {
        "clientDataJSON": "eyJvcmlnaW4iOiAiaHR0cHM6Ly93ZWJhZG1pbi5nb3NlY3...",
        "authenticatorData": "A2Kl4rVc_oY1RvUM7IITS59lwBvBIfcDyXYaBPC4grABAAAAAQ",
        "userHandle": "Es_0A-aCTBill2UB2H7dxw",
        "signature": "MEUCIQCbn0voS0WZow5EqYR9o5rTHMoscPUruaZSBQl5VUs1Dw..."
    },
    "type": "public-key",
    "id": "L7rn85CxICtfUSDohY5qZ22BiPVMlZC1gsEulJ4nbpw"
}

{
    "status":"found"
}
Status code: 200

{
  "status": "invalid",
  "message": "Request validation failed with: rp_id was not present."
}
HTTP Status 400

{
  "status": "invalid",
  "message": "Request validation failed with: User Id was not present."
}
HTTP Status 400

PUT endpoint

The PUT method has one endpoint: /fido/tokens/<token_id>.

/fido/tokens/<token_id>

The /fido/tokens/<token_id> endpoint uses the PUT method to update the enrolled device for the specified user with a new device name and device description. You must first run GET /factors to obtain the factors Id, then include it in place of <token_id> in the URL.

The Identity Platform returns a response stating whether the device was updated or not updated.

HTTP Method	Endpoint	Example
PUT	`/api/v1/fido/tokens/<token_id>`	https://secureauth.company.com/secureauth2/api/v1/`fido/tokens/` 3ac71d8e15b2efe75027d5766ef37850d4b2a1380d53b53ba250d24d1f5f9492

HTTP Method

Endpoint

Example

PUT

/api/v1/fido/tokens/<token_id>

https://secureauth.company.com/secureauth2/api/v1/fido/tokens/

3ac71d8e15b2efe75027d5766ef37850d4b2a1380d53b53ba250d24d1f5f9492

The following example describes the /fido/tokens/<token_id> endpoint response for the PUT method.

JSON parameters	Success/failure response
Tip Update registered device for an end user by including user_id, name, and description in the parameters. where user_id is the username, name is the device name, and description is the device description. Request example: { "user_id":"jsmith", "name":"macbook2020", "description":"my new macbook" }	{ "status":"valid", "message":"User Id found." } Status code: 200 { "status": "not_found", "message": "Token not found." } HTTP Status 400 { "status": "invalid", "message": "User Id not found." } HTTP Status 400

JSON parameters

Success/failure response

Tip

Update registered device for an end user by including user_id, name, and description in the parameters.

where user_id is the username, name is the device name, and description is the device description.

Request example:

{
    "user_id":"jsmith", 
    "name":"macbook2020", 
    "description":"my new macbook"
}

{
  "status":"valid",
  "message":"User Id found."
}
Status code: 200

{
  "status": "not_found",
  "message": "Token not found."
}
HTTP Status 400

{
  "status": "invalid",
  "message": "User Id not found."
}
HTTP Status 400

DELETE endpoint

The DELETE method has one endpoint: /fido/tokens/<token_id>.

/fido/tokens/delete

The /fido/tokens/<token_id> endpoint uses the DELETE method to delete a registered device for the specified user. You must first run GET /factors to obtain the factors Id, then include it in place of <token_id> in the URL.

The Identity Platform returns a response stating whether the device was deleted or not deleted.

HTTP Method	Endpoint	Example
DELETE	`/api/v1/fido/tokens/<token_id>`	https://secureauth.company.com/secureauth2/api/v1/fido/tokens/3ac71d8e15b2efe75027d5766ef37850d4b2a1380d53b53ba250d24d1f5f9492

The following example describes the /fido/tokens/<token_id> endpoint response for the DELETE method.

JSON parameters	Success/failure response
Tip Delete a registered device by including user_id in the parameters. where user_id is the username. Request example: { "user_id": "jsmith" }	{ "status": "valid", "message": "User Id found." } Status code: 204 { "status": "not_found", "message": "Token not found." } HTTP Status 400 { "status": "invalid", "message": "User Id not found." } HTTP Status 404

JSON parameters

Success/failure response

Tip

Delete a registered device by including user_id in the parameters.

where user_id is the username.

Request example:

{
    "user_id": "jsmith"
}

{
  "status": "valid",
  "message": "User Id found."
}
Status code: 204

{
  "status": "not_found",
  "message": "Token not found."
}
HTTP Status 400

{
  "status": "invalid",
  "message": "User Id not found."
}
HTTP Status 404

In this section:

FIDO2 WebAuthn API endpoints

Prerequisites

FIDO2 API workflow

Javascript snippet

GET endpoint

/users/<username>/factors

POST endpoints

/fido/enrollment

Tip

Tip

/fido/login

Tip

Tip

PUT endpoint

/fido/tokens/<token_id>

Tip

DELETE endpoint

/fido/tokens/delete

Tip

Search results