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, such as bot mitigation.

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

Compatibility

Product	Compatible?
ForgeRock Identity Cloud	Yes
ForgeRock Access Management (self-managed)	Yes
ForgeRock Identity Platform (self-managed)	Yes

Product

Compatible?

ForgeRock Identity Cloud

Yes

ForgeRock Access Management (self-managed)

Yes

ForgeRock Identity Platform (self-managed)

Yes

Inputs

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

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

Dependencies

This node requires you place PingOne Protect Initialize node previously in the journey.

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

Configuration

The configuration properties are as follows:

Property Type Usage

Property	Type	Usage
PingOne Service ID	String	The ID of the PingOne service for connecting to PingOne.
Target App ID	String	Optional. The ID of the target application.
Risk Policy Set ID	String	Optional. The ID of the risk policy set. If not specified, the environment’s default risk policy set is used.
Flow Type	String	The type of flow or event for which the risk evaluation is being carried out. Default: `AUTHENTICATION`. Options are: 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 profile change. TRANSACTION. Authentication carried out in the context of a purchase or some other one-time transaction.
Device Sharing Type	String	Whether the device is shared between users. Default: `SHARED`. Options are: `UNSPECIFIED` `SHARED` `PRIVATE`
User Type	String a	The type of user associated with the event. Default: `EXTERNAL`. * EXTERNAL. User who exists outside PingOne, such as a federated user. * PING_ONE. User who exists within the PingOne environment.
Score Threshold	Number	The `Exceed Scores Threshold` outcome when the risk score is greater than the score limit. Typically, this property is an indicator that authentication should be mitigated. Default: 300.
Recommended Actions	List<String>	The list of recommended actions returned from the risk evaluation. Each entry in the list becomes a node outcome. If the 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.
Pause Behavioral Data	Boolean	After receiving the device signal, instruct the client to pause collecting behavioral data. Default: `True`.
Node State Attribute For User ID	String	Optional. The Node state variable that contains the `user.id` as it displays in PingOne Protect. If left blank, the node uses the current context `UserId` as the `user.id`.
Node State Attribute For Username	String	Optional. The Node state variable that contains the `user.name` as it displays in PingOne Protect. If left blank, the node uses the current context `Username` as the `user.name`.
Store Risk Evaluation	Boolean	Stores the risk evaluation response in the node state under a key named `PingOneProtectEvaluationNode.RISK`. Default: `False`. NOTE: The key is empty if the node is unable to retrieve a risk evaluation from PingOne.

PingOne Service ID

String

The ID of the PingOne service for connecting to PingOne.

Target App ID

String

Optional. The ID of the target application.

Risk Policy Set ID

String

Optional. The ID of the risk policy set. If not specified, the environment’s default risk policy set is used.

Flow Type

String

The type of flow or event for which the risk evaluation is being carried out. Default: AUTHENTICATION. Options are:

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 profile change.
TRANSACTION. Authentication carried out in the context of a purchase or some other one-time transaction.

Device Sharing Type

String

Whether the device is shared between users. Default: SHARED. Options are:

UNSPECIFIED
SHARED
PRIVATE

User Type

String a

The type of user associated with the event. Default: EXTERNAL.

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

Score Threshold

Number

The Exceed Scores Threshold outcome when the risk score is greater than the score limit. Typically, this property is an indicator that authentication should be mitigated. Default: 300.

Recommended Actions

List<String>

The list of recommended actions returned from the risk evaluation. Each entry in the list becomes a node outcome. If the 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.

Pause Behavioral Data

Boolean

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

Node State Attribute For User ID

String

Optional. The Node state variable that contains the user.id as it displays in PingOne Protect. If left blank, the node uses the current context UserId as the user.id.

Node State Attribute For Username

String

Optional. The Node state variable that contains the user.name as it displays in PingOne Protect. If left blank, the node uses the current context Username as the user.name.

Store Risk Evaluation

Boolean

Stores the risk evaluation response in the node state under a key named PingOneProtectEvaluationNode.RISK. Default: False.

NOTE: 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 (transient state) named PingOneProtectEvaluationNode.RISK.

Outcomes

The PingOne Protect Evaluation node parses part of the Risk Evaluation API response, and routes it to the corresponding outcome.

Outcome Result Description

Outcome	Result	Description
High	`result.level = HIGH`	The risk evaluation level is considered a `HIGH` risk score.
Medium	`result.level = MEDIUM`	The risk evaluation level is considered a `MEDIUM` risk score.
Low	`result.level = LOW`	The risk evaluation level is considered a `LOW` risk score.
Exceed Score Threshold	`result.score > score.limit`	The risk score exceeds the configured score threshold (300) and is considered too risky to complete successfully.
<Failure>		The risk evaluation could not be completed, such as PingOne server down, API failure.
<Bot_mitigation>		The risk evaluation returned a recommended action to check for the presence of a human-simulated bot, so the evaluation continues to a CAPTCHA node.
Error		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.

High

result.level = HIGH

The risk evaluation level is considered a HIGH risk score.

Medium

result.level = MEDIUM

The risk evaluation level is considered a MEDIUM risk score.

Low

result.level = LOW

The risk evaluation level is considered a LOW risk score.

Exceed Score Threshold

result.score > score.limit

The risk score exceeds the configured score threshold (300) and is considered too risky to complete successfully.

The risk evaluation could not be completed, such as PingOne server down, API failure.

<Bot_mitigation>

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

Error

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.

Error/Messages

Messages:

"Unable to get username attribute for identity '{}', returning username for Account Name."
"Outcome not found for recommended action '{}'"
"PingOne Protect risk evaluation failed"

Audit log attribute:

PINGONE_RISK_EVALUATE_ID: Indicates the ID of the created evaluation.
PINGONE_RISK_ENV_ID: Indicates the PingOne environment.

Example

Refer to the Set up your journey section for an example of setting up this node in your journey.