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? |
|---|---|
PingOne Advanced Identity Cloud |
No |
PingAM (self-managed) |
Yes |
Ping Identity Platform (self-managed) |
Yes |
|
This node is not currently compatible with the following user interfaces:
You can only use this node in client applications built using the ForgeRock SDK. Refer to Integrate with PingOne Protect for risk evaluations. |
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, |
||
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:
The default is |
||
Device Sharing Type |
Whether the device is shared between users or not. Choose from:
The default is |
||
User Type |
The type of user associated with the event. Choose from:
The default is |
||
Score Threshold |
Scoring higher than this value results in evaluation continuing along the
The default is |
||
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:
|
||
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 If left blank, the node uses the current context |
||
Node State Attribute For Username |
The node state variable that contains the If left blank, the node uses the current context |
||
Store Risk Evaluation |
Stores the risk evaluation response in the transient node state under a key named The default is not enabled.
|
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:
-
If you have configured the Score Threshold property and the result contains a score that exceeds it, evaluation continues along the
Exceeds Score Thresholdoutcome 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_MITIGATIONoutcome 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
levelpath, one ofLow,Medium, orHigh.
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.
-
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.
MediumorLow-
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
Successresult 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
Failedresult to PingOne, which can be viewed in the console to help with analysis and risk policy tuning.