ID DataWeb Integration Kit

Device profiling methods

To include Threatmetrix when producing a policy decision for a sign-on event, ID DataWeb requires information about the device as well as the user. There are different methods for collecting the device profile depending on your preferences and whether users are authenticating directly through PingFederate or through the PingFederate authentication API.

Direct authentication mode - Captured by the ID DataWeb IdP Adapter

When the ID DataWeb 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 adds a wait time to the sign-on process. 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 ID DataWeb 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 the ID DataWeb API with a unique session ID.

  3. The ID DataWeb IdP Adapter requests a policy decision by sending the session ID and any user attributes to the ID DataWeb API.

Direct authentication mode - Captured by a previous adapter

To reduce perceived wait times for the user, you can run the device profiling script on a page that already requires user interaction.

Sequence:

  1. The user arrives at a page presented by a PingFederate adapter, such as the HTML Form Adapter.

  2. While the user interacts with the page (for example, entering their username and password), the device profiling script sends the device profile to the ID DataWeb API with a unique session ID. The script also stores the session ID in an HTTP cookie.

  3. The ID DataWeb IdP Adapter is triggered by the PingFederate authentication policy. It gets the session ID from the HTTP cookie.

  4. The ID DataWeb IdP Adapter requests a policy decision by sending the session ID and any user attributes to the ID DataWeb API.

You can integrate the device profiling script into any page that meets the following criteria:

  • The page appears before the ID DataWeb IdP Adapter 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. You might be able to work around this requirement by consolidating your domains with a reverse proxy server.

Authentication API mode - Captured by the ID DataWeb IdP Adapter

If you have a web application that uses the PingFederate authentication API, you can add the device profiling script to your existing sign-on page.

Sequence:

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

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

  3. The web application gets a device profiling URL from the authentication API. The script creates the device profile and associated it with the session ID in the URL.

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

  5. The ID DataWeb IdP Adapter requests a policy decision by sending the session ID and any user attributes to the ID DataWeb API.

This method is recommended if you have a web application and cannot accommodate HTTP cookies.

Authentication API mode - Captured by your web application first-factor sign-on page

If your web application can accommodate HTTP cookies, you can reduce perceived wait times by running the device profiling script while the user interacts with your sign-on page.

Sequence:

  1. The user arrives at a first-factor sign-on page presented by your web application.

  2. While the user interacts with the page (for example, entering their username and password), the device profiling script sends the device profile to the ID DataWeb API with a unique session ID. The script also stores the session ID in an HTTP cookie.

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

  4. The ID DataWeb IdP Adapter sends the session ID and any user attributes to the ID DataWeb API and requests the policy decision.

You can integrate the device profiling script into your web application if it meets the following criteria:

  • The user sees your sign-on page before the ID DataWeb 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. You might be able to work around this requirement by consolidating your domains with a reverse proxy server.