Device profiling methods
ThreatMetrix requires a device profile to determine a review status. There are several methods for capturing the device profile and sending it to ThreatMetrix.
There are several device profiling methods to accommodate:
-
Where your users sign on, such as:
-
A PingFederate adapter template, such as the HTML Form Adapter or ThreatMetrix IdP Adapter
-
A web app that uses the PingFederate authentication API
-
A mobile or native app that uses the PingFederate authentication API
-
-
Whether you are able to modify the sign-on page or app to:
-
Run a device profiling script
-
Pass a session ID to the ThreatMetrix IdP Adapter through an HTTP cookie
-
Pass a session ID to the ThreatMetrix IdP Adapter through the PingFederate authentication API
-
Choosing a device profiling method
The "basic" methods below are simpler to set up, but the user has to wait during the device profiling process.
The "enhanced" methods are more complex to set up, but the device profiling process happens in the background before the ThreatMetrix IdP Adapter is triggered by the PingFederate authentication API. This eliminates the perceived wait time for the users.
With all device profiling methods, the ThreatMetrix IdP Adapter uses a session ID to pass additional (optional) attributes to ThreatMetrix.
Compare the device profiling methods in the table and descriptions below, and decide which is the best fit for your environment. Detailed instructions are provided in the setup steps.
Comparison of device profiling methods
| Method | Authentication mode | Session ID created by | Profile captured by | Profile submitted by | Device Profilingsetting | Notes |
|---|---|---|---|---|---|---|
Built-in (basic) |
PingFederate template |
ThreatMetrix IdP Adapter |
ThreatMetrix IdP Adapter |
ThreatMetrix IdP Adapter |
Create a new device profile |
User waits while device is profiled |
Web app (basic) |
Authentication API |
ThreatMetrix IdP Adapter |
Web app |
Web app |
Create a new device profile |
User waits while device is profiled Requires script setup |
Web app (enhanced) |
PingFederate template or Authentication API |
Web app |
Web app |
Web app |
Use existing session ID |
Requires script setup Passes session ID in cookie |
Mobile or native app (enhanced) |
Authentication API |
Mobile or native app |
Mobile or native app |
Mobile or native app |
Use existing session ID |
Requires ThreatMetrix SDK Passes session ID via API call |
Built-in (basic)
When the ThreatMetrix IdP Adapter is triggered in the sign-on flow, it inserts a page that runs the device profiling script.
|
This method does not require modifications to any other pages, but users must wait while the device profile is captured. The length of the wait depends on your environment. |
Sequence:
-
The user arrives at the first-factor sign-on page and enters their credentials.
-
The ThreatMetrix IdP Adapter is triggered by the PingFederate authentication policy. It presents a "spinner" animation page that runs the device profiling script. The script sends the device profile to ThreatMetrix with a unique session ID.
-
The ThreatMetrix IdP Adapter requests a review status by sending the session ID and any user attributes to ThreatMetrix.
Web app (basic)
If you have a web app that uses the PingFederate authentication API, you can add the device profiling script to your existing sign-on page.
|
This method requires you to add a device profiling script to your existing page, and users must wait while the device profile is captured. The length of the wait depends on your environment. |
Sequence:
-
The user arrives at the sign-on page and enters their credentials.
-
The ThreatMetrix IdP Adapter is triggered by the PingFederate authentication policy.
-
The web app gets the session ID from the authentication API and runs the device profiling script. The script sends the device profile to ThreatMetrix with the session ID.
-
The web app tells PingFederate to continue the authentication flow.
-
The ThreatMetrix IdP Adapter requests a review status by sending the session ID and any user attributes to ThreatMetrix.
This method is recommended if you have a web app and cannot accommodate HTTP cookies.
Web app (enhanced)
To reduce perceived wait times for the user, you can run the device profiling script while the user interacts with a web page that is already part of the sign-on flow.
You can integrate the device profiling script into any web page that meets the following criteria:
-
The user sees your sign-on page before the ThreatMetrix IdP Adapter is triggered in your PingFederate authentication policy.
-
The page is hosted in the same domain as your PingFederate server.
This is required to accommodate the HTTP cookies that passes the ThreatMetrix session ID to the ThreatMetrix IdP Adapter.
You might be able to work around this requirement by consolidating your domains with a reverse proxy server.
For example, you can use this method with the following:
-
The HTML Form Adapter, or another PingFederate adapter that presents a web page
-
A web app that uses the PingFederate authentication API
Sequence:
-
The user arrives at a first-factor sign-on page presented by the HTML Form Adapter or your web app.
-
While the user interacts with the page (for example, entering their username and password), the device profiling script sends the device profile to ThreatMetrix with a unique session ID. The script also stores the session ID in an HTTP cookie.
-
The ThreatMetrix IdP Adapter gets the session ID from the HTTP cookie.
-
The ThreatMetrix IdP Adapter sends the session ID and any user attributes to ThreatMetrix and requests the review status.
Mobile or native app (enhanced)
If your users authenticate through a mobile or native app, you can use the ThreatMetrix SDK to capture the device profile. Your app can then provide the ThreatMetrix session ID to PingFederate to continue the authentication flow.
ThreatMetrix provides SDKs for Android, iOS, OSX, Windows, and Java. For details, see Introduction to ThreatMetrix SDK and FAQ in the ThreatMetrix documentation.
Sequence:
-
The user starts the authentication process in your mobile or native app.
-
While the user interacts with the app (for example, entering their username and password), the ThreatMetrix SDK captures the device profile and sends it to ThreatMetrix. The app then sends the ThreatMetrix session ID to PingFederate.
-
The ThreatMetrix IdP Adapter sends the session ID and any user attributes to ThreatMetrix and requests the review status.