ThreatMetrix Integration Kit

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.

Device profiling methods determine:

  • Where users sign on, such as:

    • A PingFederate adapter template, such as the HTML Form Adapter or ThreatMetrix IdP Adapter

    • A web, mobile, or native app that uses the PingFederate authentication API

  • Whether you’re 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 or the PingFederate authentication API

Choosing a device profiling method

Compare the device profiling methods in the following table and descriptions to decide which is the best fit for your environment.

  • Basic methods are simpler to set up, but the user must wait during the device profiling process.

  • Enhanced methods have more complex setup requirements, but device profiling happens in the background before the PingFederate Authentication API triggers the ThreatMetrix IdP Adapter. This eliminates the perceived wait time for users.

  • With all device profiling methods, the ThreatMetrix IdP Adapter uses a session ID to pass additional (optional) attributes to ThreatMetrix.

You can find detailed configuration instructions for each method in Integrating device profiling.

Comparison of device profiling methods
Method Authentication mode Session ID created by Profile captured by Profile submitted by Device Profiling Setting Notes

Built-in (basic)

PingFederate template

ThreatMetrix IdP Adapter

ThreatMetrix IdP Adapter

ThreatMetrix IdP Adapter

Create a new device profile

User waits during device profiling

Web app (basic)

Authentication API

ThreatMetrix IdP Adapter

Web app

Web app

Create a new device profile

User waits during device profiling

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 a 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 in an API call

Built-in (basic method)

When the ThreatMetrix IdP Adapter is triggered in the sign-on flow, it inserts a page that runs the device profiling script.

This method doesn’t 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

  1. The user arrives at the first-factor sign-on page and enters their credentials.

  2. The ThreatMetrix IdP Adapter is triggered by the PingFederate authentication policy and presents a spinner animation page that runs the device profiling script. The script sends the device profile to ThreatMetrix with a unique session ID.

  3. The ThreatMetrix IdP Adapter requests a review status by sending the session ID and any user attributes to ThreatMetrix.

Web app (basic method)

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.

  • This method is recommended if you have a web app and can’t accommodate HTTP cookies.
Sequence

  1. The user arrives at the sign-on page and enters their credentials.

  2. The ThreatMetrix IdP Adapter is triggered by the PingFederate authentication policy.

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

  4. The web app tells PingFederate to continue the authentication flow.

  5. The ThreatMetrix IdP Adapter requests a review status by sending the session ID and any user attributes to ThreatMetrix.

Web app (enhanced method)

To reduce perceived wait times for the user, you can run the device profiling script while the user interacts with a web page that’s already part of the sign-on flow.

Requirements

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 pass 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 HTML Form Adapter, or another PingFederate adapter that presents a web page.

  • A web app that uses the PingFederate authentication API.

Sequence

  1. The user arrives at a first-factor sign-on page presented by the HTML Form Adapter or your web app.

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

  3. The ThreatMetrix IdP Adapter gets the session ID from the HTTP cookie.

  4. The ThreatMetrix IdP Adapter sends the session ID and any user attributes to ThreatMetrix and requests the review status.

Mobile or native app (enhanced method)

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. Learn more in Introduction to ThreatMetrix SDK and FAQ (requires sign-on) in the ThreatMetrix documentation.

Sequence

  1. The user starts the authentication process in your mobile or native app.

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

  3. The ThreatMetrix IdP Adapter sends the session ID and any user attributes to ThreatMetrix and requests the review status.