PingOne

Configuring a provider instance

The PingOne Protect provider works similarly to CAPTCHA providers and can detect bot activity before the password credential validator (PCV) is triggered.

About this task

A provider instance isn’t required, but having one is necessary for bot detection.

Steps

  1. In the PingFederate administrative console, go to System > External Systems > CAPTCHA and Risk Providers. Click Create New Instance.

  2. On the Type tab, set the basic provider instance attributes:

    1. In the Instance Name field, enter a name for the provider instance.

    2. In the Instance ID field, enter a unique identifier for the provider instance.

    3. In the Type list, select PingOne Protect Provider. Click Next.

  3. On the Instance Configuration tab:

    1. In the PingOne Environment field, select your PingOne Connection and Environment Name.

    2. In the Field Value list for PingOne Risk Policy section, select the risk policy to use.

    3. Click Show Advanced Fields.

    4. To allow the adapter to evaluate the risk rather than the provider, clear the Enable Risk Evaluation check box.

    5. Continue configuring the provider instance using the settings listed in Provider settings reference.

    6. Click Next.

  4. On the Summary tab, review the settings for the provider and click Save.

  5. Enable the HTML Form adapter to use the provider:

    1. Go to Authentication > Integration > IdP Adapters. Select your HTML Form IdP Adapter from the list.

    2. On the IdP Adapter tab, click Show Advanced Fields.

    3. In the Risk Provider list, select your PingOne Protect provider instance.

    4. Select one or more of the following check boxes.

      Check box Description

      Risk for authentication

      Enable for the login form to prevent automated attacks

      Risk for password change

      Enable for the password change form to prevent automated attacks

      Risk for password reset

      Enable for the password reset and account unlock features to prevent automated attacks

      Risk for username recovery

      Enable for the username recovery features to prevent automated attacks

  6. Optional: Set the device profile settings for the PingOne Protect adapter:

    1. Go to Authentication > Integration > IdP Adapters.

    2. Select your PingOne Protect IdP adapter from the list.

    3. On the IdP Adapter tab, click Show Advanced Fields.

    4. Optional: Enable Include Device Dynamic Profile.

    When enabled, the adapter will load the device profiling page if it hasn’t already received the device profile payload from the provider.

Direct changes to Javascript files

In addition to the configuration in the PingFederate administrative console, you must make the following change directly to the relevant Javascript file if you want the device data in the SDK payload to be provided as a signed JWT.

  • Open the file <installation directory>\server\default\conf\template\assets\scripts\captcha\signals.js.

  • Add this line: universalDeviceIdentification: true

The option of using a signed JWT was introduced in version 1.0.4 of the integration kit.

Provider settings reference

Standard fields
Field Value Description

PingOne Environment

<PingOne Connection>

Your PingOne Environment. Create connections in System > External Systems > PingOne Connections.

This field is blank by default.

PingOne Risk Policy

<PingOne Risk Policy Name>

The risk policy used by PingOne for the risk evaluation. Overrides the environment and global default policy selections. This list is populated when you select a PingOne Environment.
Advanced fields
Field Value Description

Use Targeted Policies

  • Enabled

  • Disabled

When enabled, PingFederate uses the targeted risk policies that have been defined for the environment, rather than using a specific risk policy.

If you select the Use Targeted Policies checkbox, the targeted policies will be used even if a specific risk policy is currently selected from the PingOne Risk Policy list.

Password Encryption

  • SHA-256

  • SHA-384

  • Disable

For improved detection of bots and brute force attacks, use the Password Encryption option by selecting one of the SHA-2 hash functions. When this option is enabled, part of the password is hashed and passed to PingOne Protect.

Follow Recommended Action

  • Enabled

  • Disabled

In certain situations, the response from PingOne Protect includes not just an overall risk level but also a "recommended action", for example, BOT_MITIGATION or AITM MITIGATION. These recommended actions are passed forward and you can configure the PingFederate policy to act upon the recommendation. Enable this option if you want the provider to automatically stop the transaction if the response includes one of these recommended actions.

Failure Mode

  • Continue with fallback policy decision

  • Fail

Use this option to specify how to proceed if PingOne Protect is unavailable or an error occurs: fail the user’s sign-on attempt or continue with a pre-determined policy decision (set with Fallback Policy Decision Value).

Fallback Policy Decision Value

  • LOW

  • MEDIUM (default)

  • HIGH

  • unknown

If you set Failure Mode to Continue with fallback policy decision, use the Fallback Policy Decision Value field to enter the risk result to use if PingOne Protect is unavailable or an error occurs ("LOW", "MEDIUM", "HIGH", or "unknown") .

API Request Timeout

2000 (default)

The amount of time in milliseconds that PingFederate allows when establishing a connection with PingOne Protect or waiting for a response to a request. A value of 0 disables the timeout.

Proxy Settings

  • No Proxy

  • System Defaults (default)

  • Custom

To use a proxy for outbound HTTP requests, set Proxy Settings to System Defaults or set the value to Custom to specify a custom proxy host and port.

Custom Proxy Host

<Proxy server host>

The proxy server host name to use when Proxy Settings is set to Custom.

This field is blank by default.

Custom Proxy Port

<Proxy server port>

The proxy server port to use when Proxy Settings is set to Custom.

This field is blank by default.

Custom Connection Pool

50 (default)

The number of connections to PingOne Protect. Can be between 25 and 200. Recommended that the number be left at the default value.

Collect PingID Device Trust Attributes

  • Enabled

  • Disabled

When enabled, the Protect (Signals) SDK collects attributes from the PingID Device Trust Agent and sends them to PingOne Protect.

PingID Device Trust Agent Port

<Port number>

The port number to use when connecting to the PingID Device Trust Agent. If left blank, the default port (9400) is used.

PingID Device Trust Agent Timeout

<Number of milliseconds>

The time, in milliseconds, that PingFederate allows for establishing a connection with the PingID Device Trust Agent. Value must be between 200 and 10,000. If left blank, the value used is the value that was set in the Protect (Signals) SDK.

Browser-based Location

  • Don’t get location (default)

  • Get location - consent window shown by Protect Provider

  • Get location - consent window shown separately

This option instructs the Protect (Signals) SDK to include the browser-based location if the user consents to the inclusion of this information. Select Get location - consent window shown by Protect Provider if you want PingFederate to trigger the consent window. Select Get location - consent window shown separately if you want one of your own pages to trigger the consent window.