Use this guide to configure the SecureAuth Authentication API to enable end users to securely access resources using their unique device or browser profiles without requiring additional one-time passcodes (OTPs) for multi-factor authentication.
End users enroll profiles for mobile or desktop devices by successfully authenticating through a SecureAuth IdP realm. Device or browser profiles can be configured to store a credential in the device, thereby increasing security by having a client-side and server-side component that must match for a successful authentication.
Device or browser profiles can be revoked instantly at any time by the administrator or the end user.
Refer to Device Recognition for more information.
The Authentication API includes two options for Device Recognition endpoints, Standard and Stateless.
- Standard enables validation and confirmation of device or browser profiles with cached information, relying on the fingerprint_ID for account storage.
- Stateless enables validation and confirmation without requiring cached storage or the fingerprint_ID, enabling workflow on multiple appliances.
1. Complete the steps in the Authentication API Guide.
2. Complete the Device Recognition configuration steps on the SecureAuth IdP Web Admin for SecureAuth IdP v9.1 or greater. The configuration steps are for all realms that use Device Recognition.
Three types of /dfp endpoints are used for Standard Device Recognition.
1. The /dfp/js endpoint uses the GET method to retrieve the JavaScript reference that is required to generate device or browser profiles.
Using the JavaScript reference, the end user's devices or browsers are analyzed and most of the required information is collected; but the remaining characteristics must be provided by the application.
2. The /dfp/validate endpoint uses the POST method to compare the presented profile with those stored in the user account.
Based on the information provided from the directory, SecureAuth IdP returns a response stating whether the profile is found or not found.
If a match is made during a login attempt, then the profile is used as the second factor of authentication.
3. If a profile posted to the /dfp/validate endpoint returns a not_found or found_for_update status, then the information must be posted to the /dfp/confirm endpoint to create a new, or update an existing, profile in the user account in the directory.
After the profile is validated, SecureAuth IdP returns a fingerprint_id, which is then posted to the confirm endpoint to create the entry.
To use these endpoints, configure the SecureAuth IdP realm for Device Recognition.
HTTP Method | Endpoint | Example |
---|---|---|
GET | /api/v1/dfp/js | https://secureauth.company.com/secureauth2/api/v1/dfp/js |
HTTP Method | Endpoint | Example |
---|---|---|
POST | /api/v1/dfp/validate | https://secureauth.company.com/secureauth2/api/v1/dfp/validate |
HTTP Method | Endpoint | Example |
---|---|---|
POST | /api/v1/dfp/confirm | https://secureauth.company.com/secureauth2/api/v1/dfp/confirm |
Three types of /dfp endpoints are used for Stateless Device Recognition.
1. The /dfp/js endpoint uses the GET method to retrieve the JavaScript reference that is required to generate device or browser profiles. See endpoint information in the Standard DFP Endpoint section above.
Using the JavaScript reference, the end user's devices or browsers are analyzed and most of the required information is collected, but the remaining characteristics must be provided by the application.
2. The /dfp/score endpoint uses the POST method to compare the presented profile with those stored in the user account.
Based on the information provided from the directory, SecureAuth IdP returns a response stating whether the profile is found or not found.
If a match is made during a login attempt, then the profile is used as the second factor of authentication.
3. The /dfp/score endpoint uses the POST method to complete the user account profile in the directory.
To use these endpoints, configure the SecureAuth IdP realm for Device Recognition.
HTTP Method | Endpoint | Example |
---|---|---|
POST | /api/v1/dfp/score | https://secureauth.company.com/secureauth2/api/v1/dfp/score |
HTTP Method | Endpoint | Example |
---|---|---|
POST | /api/v1/dfp/save | https://secureauth.company.com/secureauth2/api/v1/dfp/save |