--- title: PingOne Protect Evaluation node description: The PingOne Protect Evaluation node contacts PingOne to calculate the risk level and other risk-related details associated with an event. component: auth-node-ref version: 8 page_id: auth-node-ref::pingone-protect-evaluation canonical_url: https://docs.pingidentity.com/auth-node-ref/8/pingone-protect-evaluation.html page_aliases: ["auth-node-pingone-protect-evaluation.adoc"] section_ids: availability: Availability inputs: Inputs dependencies: Dependencies configuration: Configuration outputs: Outputs outcomes: Outcomes outcome_precedence: Outcome precedence example: Example --- # 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. Learn more in [PingOne Protect > How it Works](https://docs.pingidentity.com/pingone/threat_protection_using_pingone_protect/p1_protect_introduction.html). | | | | - | ----------------------------------------------------------------------------------------------------------------------------------- | | | This node isn't compatible with the 8.0 Platform UI provided for self-managed AM, Ping Identity Platform, and ForgeOps deployments. | ## Availability | Product | Available? | | ------------------------------------- | ---------- | | PingOne 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've initialized PingOne Protect in your client application. For example, by using a [PingOne Protect Initialization node](pingone-protect-initialize.html) 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 Ping 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](https://docs.pingidentity.com/pingone/monitoring/p1_reporting.html) in PingOne.For example, `12345678-abcd-4567-abcd-a123b123c123`. | | Risk Policy Set ID | The ID of the [risk policy](https://docs.pingidentity.com/pingone/threat_protection_using_pingone_protect/p1_protect_risk_policies.html) in PingOne.To view risk policies in the PingOne admin console, go 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 could 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, such as 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: ![Risk evaluation outcome path precedence](https://kroki.io/plantuml/svg/eNqVlOFO2zAQx7_7KU7eB7aItWsHgwFiKlCgEi2IlqFJSMhNLo1V165sp6VDPNBeY0-2cwJrhwJo_eCkvv_9_D_7nPoaA_odmunCylHm4fcvaH5qbsDH8NiEC6lH0ElQe-kXJLNTY4WXRrMib5BJB7FJEOjpDQwRcocJ4F2scidnqBYgNSm0xjikwVz67BVqgDqT-rmwCMaCQzuTMbpaEXkxD4ymlUyaonXg8jirhASHCkdCQUGQ6ArqPDOQiRmGWbTkXmoSChhKnYQFFeVqhyBGFnFCoreKWKuzPecXCveZoKpnFD-SlC0mcE8rXoik4DbZA0tMnBfIEID62oGIxyNrcp0cGkXWvRXaTakO7Yn6wPbqj2DmxlJTgJhPvO3VyVdAq7IjTEWu_LHRvicmCPwU1Qy9jAWvVvXlT4TGxiqjZzweGJugLZcaxridNp4LnvlJvmKSbq1i-plIzDwU4m2OjLGdS-nGgDOh8vKQLbqpoZPYZZqIUDQs45zTPLnjO3DPOf0H4Aqp9WiCd9tHnasuX38KuNhYpECjttHc3txq_B2_LCUmt3HQ8NbJyWX7pDVoH91etzsnp4P-EmQxNhM6uQSTVtHZLmQcnA9uu51Bh5I6572l2i-mBfF76-yqzYvZBxopHUIpTKbwPooaNegHf3StqKTMqCSKbjRdnlSO8tCYQhdXC5FW_fYBfIY65P1AF0UfqIHeYRObaWMnitqFylXxTO7JOsJU-GyXksZSKYaKGpxQe3E4nR1abL9nSmjprVmDy2XJ8Fhzhb-J8HGGrsre0mA3iOiob3QUvYBdtXmjj6ll8E5MpgrXgT_fZ75b0ItKAF6phT4udHfp80DhzzUClY3CowhCm-GNFg5SodSQ2rVMiEWgQRRxfnZ-HaTl_Opun5l51c6uePqH89iUlaguJjKf_A_tlDqzmnVKF-RNEm18uSeseJcpK8c_jArpsA==)Figure 1. Risk evaluation outcome path precedence 1. 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. 2. 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. 3. 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 Ping SDKs. ![Example PingOne Protect journey](_images/pingone-protect-example-journey.png)Figure 2. Example PingOne Protect journey * 1 The [PingOne Protect Initialization node](pingone-protect-initialize.html) 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](pingone-protect-evaluation.html) 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. * `AITM_MITIGATION` The risk evaluation returned a recommended action regarding the possible presence of an adversary-in-the-middle attack, so the journey continues to the Failure 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](pingone-protect-result.html) 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](pingone-protect-result.html) returns the `Failed` result to PingOne, which can be viewed in the console to help with analysis and risk policy tuning.