PingAccess

Risk policy field descriptions

The following table describes the fields available for managing risk policies on the Risk Policies tab in PingAccess.

Field Required Description

Name

Yes

A unique name for the risk policy.

PingOne Connection

Yes

The PingOne connection that you created in steps 2a-2c of Adding a PingOne connection.

PingOne Risk Policy ID

No

The ID of the PingOne risk policy that you want to use to perform risk evaluation.

A null value tells PingOne Protect to use a default policy.

You can only configure a PingOne risk policy in PingOne Protect.

If you haven’t enabled device profiling in a PingAccess risk policy configuration, then you shouldn’t include New Device or other device-related PingOne predictor types in the associated PingOne risk policy.

Some of these device-related predictor types are included in the default PingOne risk policy. If you haven’t enabled device profiling, make sure to remove the following predictor types from your configuration or adjust the weights or scores associated with them:

  • Anonymous network detection

  • Geovelocity anomaly

  • IP reputation

  • IP velocity

  • New device

  • User location anomaly

Learn more in Risk Policies in the PingOne Cloud Platform documentation.

Risk Check Interval (MS)

No

The rate at which PingAccess requests an evaluation from PingOne Protect for the same end-user.

This field accepts values from zero to a full day. The default value is 20000 ms (20 seconds).

To have PingOne Protect perform an evaluation on every request that an end-user makes, you can set this value to 0. However, evaluating every request could slow down your environment’s performance.

User ID Attribute

Yes

Tells PingOne Protect what kind of user attribute to define as an end user’s user ID.

High Risk Policy Evaluator

Yes

A policy that tells PingAccess what action to take if the returned risk score from an end user’s request is HIGH.

In the High Risk Policy Evaluator list, select one of the following options:

Section
Allow

The default value. Permits the end-user’s request.

Authentication Challenge Policy

Directs the user to reauthenticate. If you select this option, you must select an Authentication Challenge Policy to use. Adjusting the Authentication Validity Period (M) is optional.

Deny

Rejects the end-user’s request. If you select this option, you must select a Rejection Handler to use.

Rule

PingAccess evaluates a rule you specify to determine how to proceed. If you select this option, you must select a specific web Rule to use.

API policy is currently incompatible with this type of policy evaluator. For more information on web policy and API policy, see Applying rules to applications and resources. The following PingAccess rule types are API-specific and thus currently unusable on a protected web application:

Rule Set

PingAccess evaluates a rule set you specify to determine how to proceed. If you select this option, you must select a Rule Set to use.

Medium Risk Policy Evaluator

Yes

A policy that tells PingAccess what action to take if the returned risk score from an end-user’s request is MEDIUM.

In the Medium Risk Policy Evaluator list, select one of the five options described in the High Risk Policy Evaluator table entry.

Low Risk Policy Evaluator

Yes

A policy that tells PingAccess what action to take if the returned risk score from an end user’s request is LOW.

In the Low Risk Policy Evaluator list, select one of the five options described in the High Risk Policy Evaluator table entry.

Failed Risk Policy Evaluator

Yes

A policy that tells PingAccess what action to take if the returned risk score is an invalid value or if the risk evaluation service is unavailable.

In the Failed Risk Policy Evaluator list, select one of the five options described in the High Risk Policy Evaluator table entry.

Device Profiling Method

Yes

Specify if and how you want to collect an end-user’s device profile. The default value is OFF.

Device profiling helps PingOne Protect detect bot-like behavior and trigger step-up authentication in PingAccess.

Device profile collection adds the device profile to the user’s browser as cookies, which are sent to PingAccess during subsequent requests. These cookies are usually 8192 bytes in size. Before enabling device profiling, you should increase the pa.default.maxHttpHeaderSize property in the <PA_HOME>/conf/run.properties file to ensure a smooth transition.

In the Device Profiling Method list, select one of the following options:

Section
OFF

Select OFF if you don’t want to perform device profiling.

Captured by PingAccess

Select Captured by PingAccess to have PingAccess perform device profiling.

When this option is selected, PingAccess periodically interrupts end-user requests to display the Device Profile Page, an HTML page containing a script that collects the end-user’s device profile.

If you select Captured by PingAccess, the web page that you use to capture the device profile must be a GET request without a request body. The GET request must have an Accept header that allows text and HTML responses.

You can also use the pingone.protect.template.title and pingone.protect.template.header properties in the <PA_HOME>/conf/localization/pa-messages.properties file to add messages. For more information, see User-facing page localization reference.

If you select Captured by PingAccess, the following fields become available:

  • Device Profile Interval

  • Device Profile Timeout

  • Device Profile Cookie Prefix

  • Send Device Profile

Captured by Frontend Application

Select Captured by Frontend Application to perform device profiling yourself without interrupting end-user requests.

When this option is selected, you must set embed the PingOne Protect Signals SDK into your own web pages and send the device profile data that you collect to PingAccess using cookies. For more information, see the Device Profile Cookie Prefix table entry.

If you select Captured by Frontend Application, the following fields become available:

  • Device Profile Cookie Prefix

  • Send Device Profile

Device Profile Interval (S)

This field is only available if you set Captured by PingAccess as the Device Profiling Method.

No

Define, in seconds, how frequently PingAccess should interrupt end-user requests to gather device profile data when the Device Profiling Method is set to Captured by PingAccess.

This parameter accepts an integer value between 1-86400 seconds. The default value is 300 seconds.

Device Profile Timeout (MS)

This field is only available if you set Captured by PingAccess as the Device Profiling Method.

No

Define, in milliseconds, how long the device profiling collection script will attempt to collect an end-user’s device profile when the Device Profiling Method is set to Captured by PingAccess.

If this timeout is exceeded, the script can’t send device profile cookies to PingAccess, so PingAccess will follow the Invalid Profile Risk Policy.

The default value is 5000 ms (5 seconds). A minimum value of 1000 ms (1 second) is required.

Device Profile Cookie Prefix

This field is only available if you set Captured by PingAccess or Captured by Frontend Application as the Device Profiling Method.

No

Define the cookie prefix that’s used to send device profile data to PingAccess. The cookie prefix must be a valid token as described by RFC 6265.

The default value is p1_device_prof.

PingAccess expects sequential cookies using this cookie prefix and an index to provide the device profile data.

For example, if you have three device profile cookies, you should order them in the following sequence: p1_device_prof0=<first device profile segment>, p1_device_prof1=<second device profile segment>, p1_device_prof2=<third device profile segment>.

PingAccess concatenates these cookies and sends them to PingOne Protect when performing a risk evaluation for a user request.

Send Device Profile

This check box is only available if you set Captured by PingAccess or Captured by Frontend Application as the Device Profiling Method.

No

Select this check box if you want PingAccess to include device profile cookies in requests made to the protected application. This check box is cleared by default.

Device profile cookies can be large and can sometimes make requests incompatible with backend servers.

Invalid Profile Risk Policy

Yes

A policy that tells PingAccess what action to take in response to an end-user’s request if the device profile information sent to PingAccess is invalid. For example, device profile information could be invalid because it’s missing or because it isn’t being collected as expected.

In the Invalid Profile Risk Policy Evaluator list, select one of the five options described in the High Risk Policy Evaluator table entry.

IP Change Enforcement

Yes

Specify the enforcement strategy that you want to use when PingAccess detects an IP address change from the end user. The default value is NONE.

In the IP Change Enforcement list, select one of the following options:

Section
NONE

PingAccess continues to allow user requests without recollecting device profile data or performing a new risk evaluation.

Reevaluate Risk

Performs a new PingOne Protect risk evaluation without recollecting the device profile.

Collect Device Profile + Reevaluate Risk

Collects the end user’s device profile data again, then performs a new PingOne Protect risk evaluation.

Advanced Settings

To configure advanced settings on a risk policy, expand the Show Advanced Settings section at the bottom of the Risk Policy page. These settings are optional.

Field Description

Device Profile Page

Specify the HTML template that PingAccess should render if the Device Profiling Method is set to Captured by PingAccess.

If you leave this field blank, PingAccess populates it with the <PA_HOME>/conf/template/system/pingone.protect.template.html default HTML template file after you save the risk policy.

This default template contains the code that PingAccess uses to collect device profile data. Making changes to this template might interfere with PingAccess’s ability to collect device profile data. You can make style changes to this template, but you should avoid making functional changes to it.

Max Expected Device Profile Cookies

You must set the Device Profiling Method to Captured by PingAccess to use this configuration option.

Define the number of device profile cookies that PingAccess attempts to reset when it displays the Device Profile Page. The default value is 5. You must specify a value between 1-64.

If PingAccess has seen the user before, it checks the user session data to determine the last set of device profile cookies it was sent and resets those cookies when it displays the device profile page. Max Expected Device Profile Cookies is only used when PingAccess is unable to determine the last set of device profile cookies that it was sent from the user.

If you use the default Device Profile Cookie Prefixp1_device_prof, then PingAccess resets the cookies for p1_device_prof0p1_device_prof1p1_device_prof2p1_device_prof3, and p1_device_prof4 so that the device profile page can edit them with the correct data.