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

  1. SecureAuth® Identity Platform version 20.06 or later

  2. Complete the steps in the Authentication API Guide.

FIDO2 API workflow

The Authentication API uses four endpoints for FIDO2 using WebAuthn.

  1. Embed the functions in the Javascript snippet example into your JavaScript or HTML file.

  2. Use the two /fido/enrollment endpoints via POST to enroll end users.

  3. After a successful FIDO2 enrollment, end users can use their FIDO2-compliant device to log into the login pages to authenticate.

  4. 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.

  5. 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.

  6. To update a device, the fido/tokens endpoint is called via PUT.

  7. 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.

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

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

/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

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

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