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.)
SecureAuth® Identity Platform version 20.06 or later
Complete the steps in the Authentication API Guide.
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.
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 GET method has one endpoint: /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 |
| https://secureauth.company.com/secureauth2/api/v2/users/jsmith/factors | v20.06 or later |
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
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 |
| https://secureauth.company.com/secureauth2/api/v1/fido/enrollment/begin | v20.06 or later |
POST |
| https://secureauth.company.com/secureauth2/api/v1/fido/enrollment/complete | v20.06 or later |
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 |
| https://secureauth.company.com/secureauth2/api/v1/fido/login/begin |
POST |
| https://secureauth.company.com/secureauth2/api/v1/fido/login/complete |
The PUT method has one endpoint: /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 |
| https://secureauth.company.com/secureauth2/api/v1/fido/tokens/ 3ac71d8e15b2efe75027d5766ef37850d4b2a1380d53b53ba250d24d1f5f9492 |
The DELETE method has one endpoint: /fido/tokens/<token_id>.
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 |
| https://secureauth.company.com/secureauth2/api/v1/fido/tokens/3ac71d8e15b2efe75027d5766ef37850d4b2a1380d53b53ba250d24d1f5f9492 |