PingOne Protect Evaluation node

The PingOne Protect Evaluation node contacts PingOne to calculate the risk level and other risk-related details associated with an event.

Depending on how you configure your risk policies in PingOne, the response could return a risk score, a risk level such as high, medium, or low, and recommended actions to take, such as mitigation against bots.

For more information, refer to PingOne Protect > How it Works.

Compatibility

Product	Compatible?
Advanced Identity Cloud	Yes
PingAM (self-managed)	Yes
Ping Identity Platform (self-managed)	Yes

Product

Compatible?

Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

This node can use shared state variables that contain the PingOne user.id and user.name as input. If these are not available, the node uses the UserId and Username variables.

This node requires that you have initialized PingOne Protect in your client application. For example, by using a PingOne Protect Initialization node node previously in the journey or by initializing the SDK within the app itself.

Dependencies

This node requires a PingOne Worker Service configuration so that it can connect to your PingOne instance and send it the necessary data to make risk evaluations.

The client application must be using ForgeRock SDK 4.4.0 or later.

Configuration

Property Usage

PingOne Worker Service ID

The ID of the PingOne worker service for connecting to PingOne.

Target App ID

Optional. If the user is attempting to access a PingOne application through the journey, add its v4 UUID client ID.

This correlates the authentication with the application in PingOne, allowing you to filter by the Resource Id that matches the entered Target App ID when viewing the audit log in PingOne.

For example, 12345678-abcd-4567-abcd-a123b123c123.

Risk Policy Set ID

The ID of the risk policy in PingOne.

To view risk policies in the PingOne administration console, navigate to Threat Protection > Risk Policies.

If not specified, the environment’s default risk policy set is used.

Flow Type

The type of flow or event for which the risk evaluation is being carried out.

Choose from:

REGISTRATION: Initial registration of an account.
AUTHENTICATION: Standard authentication for login or actions such as password change.
ACCESS: Verification of whether the user can access the relevant application.
AUTHORIZATION: Verification of whether the user is authorized to perform a specific action such as a profile change.
TRANSACTION: Authentication carried out in the context of a purchase or other one-time transaction.

The default is AUTHENTICATION.

Device Sharing Type

Whether the device is shared between users or not.

Choose from:

UNSPECIFIED
SHARED
PRIVATE

The default is SHARED.

User Type

The type of user associated with the event.

Choose from:

PING_ONE: User exists within the PingOne environment.
EXTERNAL: User exists outside PingOne, such as a federated user.

The default is EXTERNAL.

Score Threshold

Scoring higher than this value results in evaluation continuing along the Exceeds Score Threshold outcome.

The default is 300.

Recommended Actions

A list of recommended actions the risk evaluation could return. Each entry in the list becomes a node outcome.

If the evaluation score does not exceed the Score Threshold value, and a recommended action is present in the response from PingOne Protect, the journey continues down the matching entry in this list.

Possible values are:

BOT_MITIGATION: PingOne suspects the client may be automated or a bot. You should route the journey to a CAPTCHA node or similar next step to mitigate against bots.
AITM_MITIGATION: PingOne suspects an adversary-in-the-middle (AitM) attack. You should route the journey to the failure node, and consider locking the account, and force a password change to mitigate against these attacks.

Pause Behavioral Data

After receiving the device signal, instruct the client to pause collecting behavioral data.

Default: Selected

Node State Attribute For User ID

The node state variable that contains the user.id as it appears in PingOne.

If left blank, the node uses the current context UserId as the user.id.

Node State Attribute For Username

The node state variable that contains the user.name as it appears in PingOne.

If left blank, the node uses the current context Username as the user.name.

Store Risk Evaluation

Stores the risk evaluation response in the transient node state under a key named PingOneProtectEvaluationNode.RISK.

The default is not enabled.

The key is empty if the node is unable to retrieve a risk evaluation from PingOne.

Outputs

If you enable the Store Risk Evaluation property, the node outputs the risk evaluation response JSON in a state variable named PingOneProtectEvaluationNode.RISK.

Outcomes

High: The risk evaluation level is considered high.
Medium: The risk evaluation level is considered medium.
Low: The risk evaluation level is considered low.
Exceeds Score Threshold: The score returned is higher than the configured threshold.
Failure: The risk evaluation could not be completed.
Recommended Actions: The risk evaluation recommended a mitigation action to take, and it matched a value in the Recommended Actions list.

Currently, the only value possible is BOT_MITIGATION, which recommends you check for the presence of a human, for example, by using a CAPTCHA node.
ClientError: The client returned an error when attempting to capture the data to perform a risk evaluation.

Outcome precedence

Evaluation of the journey continues along an outcome based on the response received and which fields are present in it, as follows:

Figure 1. Risk evaluation outcome path precedence

If you have configured the Score Threshold property and the result contains a score that exceeds it, evaluation continues along the Exceeds Score Threshold outcome path.
If you have not configured the Score Threshold property, or the score does not exceed it, but have added a value in the Recommended Actions list that matches one in the response, evaluation continues along the relevant dynamic outcome path. For example, the BOT_MITIGATION outcome path.
If you have not configured the Score Threshold property, or the score does not exceed it, and have not added a matching value in the Recommended Actions list, then evaluation continues along the relevant level path, one of Low, Medium, or High.

Example

The following example journey leverages PingOne Protect functionality to perform a risk evaluation on a client app. The client app is built using the ForgeRock SDKs.

Figure 2. Example PingOne Protect journey

1 The PingOne Protect Initialization node instructs the SDK to initialize the PingOne Protect Signals API with the configured properties.

Initialize the PingOne Protect Signals API as early in the journey as possible, before any user interaction.

+ This enables it to gather sufficient contextual data to make an informed risk evaluation.

The user enters their credentials, which are verified against the identity store.
2 The PingOne Protect Evaluation node performs a risk evaluation against a risk policy in PingOne.

The example journey continues depending on the outcome:

High

The journey requests that the user respond to a push notification.

Medium or Low

The risk is not significant, so no further authentication factors are required.

Exceeds Score Threshold

The score returned is higher than the configured threshold and is considered too risky to complete successfully.

Failure

The risk evaluation could not be completed, so the authentication attempt continues to the Failure node.

BOT_MITIGATION

The risk evaluation returned a recommended action to check for the presence of a human, so the journey continues to a CAPTCHA node.

ClientError

The client returned an error when attempting to capture the data to perform a risk evaluation, so the authentication attempt continues to the Failure node.
3 An instance of the PingOne Protect Result node returns the Success result to PingOne, which can be viewed in the console to help with analysis and risk policy tuning.
4 A second instance of the PingOne Protect Result node returns the Failed result to PingOne, which can be viewed in the console to help with analysis and risk policy tuning.