Skip to main content

Device Recognition authentication API guide

Updated February 10, 2022

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 Identity Platform realm. Configure device or browser profiles to store a credential in the device, which increases security because a client-side and server-side component 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.

Prerequisites

  1. Complete the steps in the Authentication API guide.

  2. Complete the Device Recognition configuration steps in the Configure Identity Platform Web Admin section. The configuration steps are for all realms that use Device Recognition.

Device Recognition workflow

The Authentication API uses two endpoints and either two or three requests for Device Recognition.

  1. The first endpoint is a GET request to retrieve the JavaScript source file required to collect the digital profile from the end user's device or browser.

    For desktop or browser profile collection options, use one of the following:

    • No Cookie: SecureAuth Identity Platform collects information sent from the browser without delivering or registering any information at the client side, such as HTTP headers and cookies.

    • Cookie: SecureAuth Identity Platform collects information sent from the browser and registers a cookie at the client-side to increase security.

    For iOS and Android mobile devices, SecureAuth Identity Platform collects information in two ways:

    • Cookie mode: SecureAuth Identity Platform collects information sent from the browser and registers a cookie at the client-side to increase security.

    • App mode: SecureAuth's native mobile app pulls unique device hardware information, such as UDID, Advertiser ID, and Device ID.

  2. After a successful multi-factor authentication, the profile is collected and stored in the user account in the directory.

  3. When the end user uses the same device or browser to log into SecureAuth Identity Platform again, the second endpoint is called via a POST request to compare the presented profile with those stored in the user account.

    The current client-unique information (a new device or browser profile) is collected and compared with the previously registered profiles for authentication.

    If a match for the profile is found and has an acceptable Authentication Threshold score, then the end user is not required to undergo additional multi-factor authentication (OTP).

  4. If a match for the profile is not found or if an update is needed, then another POST request is used to create or update the profile.

Configure Identity Platform Web Admin

The following configuration steps are for realms using Device Recognition.

  1. Go to the Data tab.

    The following step is for LDAP data stores only (AD and others). If using a different directory (for example, SQL), then the Property needs to be configured as a stored procedure in the data store.

    Note

    For SQL, ASP.net, and Oracle data stores, only the Plain Binary Data Format is supported. For ODBC data stores, Device Recognition is not supported.

  2. In the Profile Fields section, map a directory field to the following Property:

    Fingerprints

    In typical AD deployments, set this field to audio and use the Plain Binary data format.

    Select the Writable check box.

    Caution

    For the LDAP directory attribute mapped to the Property based on the Data Format selection (Plain Binary or JSON), there are distinct requirements for the directory field that contains the device or browser profile information:

    Plain Binary requirements:

    • Length – 8 kB minimum per Device / Browser Profile; and if the Total FP Max Count is set to -1, then the size must be unlimited

    • Data Type – Octet string (bytes)

    • Multi-valued

    JSON requirements:

    • Length – No limit / undefined

    • Data Type – DirectoryString

    • Multi-valued

    60570368.png

  3. Click Save.

  4. Go to the Workflow tab.

  5. In the Device Recognition Method section, set the following:

    Integration Method

    Set to Certification Enrollment and Validation.

    Client Side Control

    Set to Device/Browser Fingerprinting.

    60570369.png

  6. In the Workflow section, set the following:

    Default Workflow

    Set the login workflow for the end user login.

    If you select the "(Valid Persistent Token) only" option, a persistent token (for example, device or browser profile is required to access the target resource.

    To redirect the end user to enroll for a persistent token to gain access, provide the realm URL to another Identity Platform realm. Go to the Workflow tab, in the Workflow > Redirects section and set the realm URL (for example, /Realm#) in the Invalid Persistent Token Redirect field.

    Public/Private Mode

    This generates a device or browser profile in this realm and checks for existing profiles.

    Set to Private and Public Mode or Private Mode Only.

    Default Public/Private

    On the client-side page shown to the end user, select which option is to be selected by default.

    To ensure that profiles are generated and checked in the realm, it is recommended to set to Default Private.

    Remember User Selection

    On the client-side page shown to the end user, to automatically select the Private or Public option, based on the previous selection by the user, set to True.

    60570370.png

  7. In the Browser / Mobile Profiles section, set the following:

    Browser Profile Settings

    FP mode

    By default, this is set to Cookie. This Indicates whether to deliver a cookie to the browser after authentication – Cookie or No Cookie.

    Cookie name prefix

    Keep or change the default cookie name.

    The cookie name appears as Cookie Name Prefix + company name + hashed value of user ID.

    Cookie length

    Set the length of time in hours, the cookie is valid. For example, 72 hours.

    Match FP ID in cookie

    By default, this is set to True. This requires the profile ID to presented and then matched to a profile ID in the directory with an acceptable Authentication Threshold score.

    Otherwise, if set to False, it does not require ID matching between the cookie and the stored profile.

    Authentication threshold (%)

    Set the Authentication threshold to a percentage number between 90 and 100.

    Update threshold (%)

    Set the Update threshold to a percentage number just below the Authentication threshold. This number must be less than the number set in the previous field.

    The following is Profile Comparison Score information that describes thresholds.

    Identity Platform provides two threshold values:

    • Authentication Threshold (the high one) determines whether additional 2-Factor Authentication is required (OTP)

    • Update Threshold (the low one) determines whether an existing profile is to be updated with new information from the presented profile, or if a new profile is to be created

    For example, if the Authentication Threshold is set to 90 and the Update Threshold is set to 89, then the following evaluation would be done on subsequent authentications:

    <Profile-Score> represents the score of the presented profile,

    If <Profile-Score> is ≥ 90, then no additional Multi-Factor Authentication is required.

    If <Profile-Score> is < 90, but ≥ 89, then additional Multi-Factor Authentication is required and the existing profile is updated with the presented profile information.

    If <Profile-Score> is < 89, then additional Multi-Factor Authentication is required, and a new profile is created.

    Note: If the device recognition cookie is in use and the user login is in the same browser, the existing device profile will be updated with the new profile data.

    Mobile Profile Settings

    FP mode

    Set to Cookie to deliver a cookie to the mobile device after authentication.

    The Mobile App setting has been deprecated.

    Cookie name prefix

    Keep or change the default cookie name.

    The cookie name appears as Cookie Name Prefix + company name + hashed value of user ID.

    Cookie length

    Set the length of time in hours, the cookie is valid. For example, 72 hours.

    Match FP ID in cookie

    By default, this is set to True. This requires the profile ID to presented and then matched to a profile ID in the directory with an acceptable Authentication Threshold score.

    Otherwise, if set to False, it does not require ID matching between the cookie and the stored profile.

    Skip IP Match

    If an exact IP address match is not required for profile comparison, set to True. Otherwise, to require an exact match, set to False.

    Authentication threshold (%)

    Set the Authentication threshold to a percentage number between 90 and 100.

    Update threshold (%)

    Set the Update threshold to a percentage number just below the Authentication threshold. This number must be less than the number set in the previous field.

    For an explanation of thresholds, see the "Update threshold" above.

    Other Settings

    FP expiration length

    Set the number of days the profile is valid.

    For example, when set to 10 days, the user's profile expires in days, no matter how often it is used.

    Set to 0 for no expiration.

    FP expiration since last access

    Set the number of days a profile is not used since the last access; to which the profile no longer valid.

    For example, when set to 10 days, the user's profile expires when it hasn't been used since it was last employed.

    Set to 0 for no expiration.

    Total FP max count

    Set the maximum number of profiles that can be stored in a user's account at a given time.

    A typical configuration would limit a profile storage maximum from five to eight profiles.

    Set to -1 for no limit on profile storage maximum.

    When exceeding max count

    If the Total FP max count is set to a number other than -1, set to one of the following:

    • Allow to replace – Enable replacement of an existing profile with a new one.

    • Not Allow to replace – Profiles cannot be automatically replaced. With this option, the user or administrator must manually remove stored profiles from the user profile on the Self-service Account Update page or Account Management (Help Desk) page.

    Replace in order by

    If a maximum is set in the Total FP max count and Allow to replace is selected when exceeding the maximum count, set to one of the following:

    • Created Time – Enable replacement of the oldest stored profile with the new one.

    • Last Access Time – Enable replacement of the most recently used profile with the new one.

    FP's access records max count

    Set to the number of access history entries stored in each profile. Recommended setting is 5.

    60570371.png

  8. To modify the Profile Component default weight values, select the Show Custom Component Weights check box.

  9. Set the components based on how profiles should be analyzed against the Thresholds:

    • Off – Not considered in profile analysis

    • Low – Profile analysis is low; small changes do not drastically change profile Component is considered in profile analysis with low effect (small changes do not drastically change profile)

    • High – Profile analysis is high; significant change could drastically change profile, requiring new profile for device or browser

      As an administrator, you can view mismatched components in the Audit log. For example:

      <Message>Fingerprint Mismatch: Field=PixelRatio, Weight=8.888889%</Message>

      Note: The logs show mismatched components only when the device or browser profile score is higher than the Update Threshold score and is less than 100 percent.

      For specific component information, expand the following link.

  10. Click Save.

  11. Go to the System Info tab.

  12. In the Plugin Info section, set the Java Detection field to False.

    60570373.png

  13. Click Save.

The following optional configurations are available if your organization requires them:

  • Enable administrator (help desk) revocation of user device or browser profiles. Another realm (for example, Realm B) must be set up for the Account Management Page post authentication action.

    For more information, see the Device Recognition document, "Realm B" section, and the Account Management (Help Desk) Page Configuration Guide.

  • Enable end user self-service revocation of device or browser profiles. Another realm (for example, Realm C) must be set up for the Self-service Account Update post authentication action.

    For more information, see the Device Recognition document, "Realm C" section, and the Self-service Account Update Page Configuration Guide.

Standard endpoints

Three types of /dfp endpoints are used for standard device recognition, explained in the following sections.

  1. The /dfp/js endpoint uses the GET method to retrieve the JavaScript reference that is required to generate device or browser profiles.

  2. The /dfp/validate endpoint uses the POST method to compare the presented profile with those stored in the user account.

  3. If a profile posted to the /dfp/validate endpoint returns a not_found or found_for_update status, the user is required to complete multi-factor authentication (MFA). Once the user has successfully completed MFA, 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.

To use these endpoints, configure the SecureAuth Identity Platform realm for Device Recognition.

GET /dfp/js

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.

HTTP Method

Endpoint

Example

GET

/api/v1/dfp/js

https://secureauth.company.com/secureauth2/api/v1/dfp/js
POST method endpoints (standard)

The POST method for standard device recognition has two endpoints: /dfp/validate and /dfp/confirm.

/dfp/validate

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

HTTP Method

Endpoint

Example

POST

/api/v1/dfp/validate

https://secureauth.company.com/secureauth2/api/v1/dfp/validate
/dfp/confirm

If a profile posted to the /dfp/validate endpoint returns a not_found or found_for_update status, the user is required to complete multi-factor authentication (MFA). Once the user has successfully completed MFA, 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 Identity Platform returns a fingerprint_id, which is then posted to the confirm endpoint to create the entry.

HTTP Method

Endpoint

Example

POST

/api/v1/dfp/confirm

https://secureauth.company.com/secureauth2/api/v1/dfp/confirm

Stateless endpoints

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.

  3. The /dfp/save endpoint uses the POST method to complete the user account profile in the directory.

To use these endpoints, configure the SecureAuth Identity Platform realm for Device Recognition.

POST method endpoints (stateless)

The POST method for stateless device recognition has two endpoint: /dfp/score and /dfp/save.

/dfp/score

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 Identity Platform 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

HTTP Method

Endpoint

Example

POST

/api/v1/dfp/score

https://secureauth.company.com/secureauth2/api/v1/dfp/score
/dfp/save

The /dfp/save endpoint uses the POST method to complete the user account profile in the directory.

HTTP Method

Endpoint

Example

POST

/api/v1/dfp/save

https://secureauth.company.com/secureauth2/api/v1/dfp/save
In this section: