--- 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: latest page_id: auth-node-ref:pingone:pingone-protect-evaluation canonical_url: https://docs.pingidentity.com/auth-node-ref/latest/pingone/pingone-protect-evaluation.html page_aliases: ["auth-node-pingone-protect-evaluation.adoc"] superseded_by: https://docs.pingidentity.com/auth-node-ref/latest/pingone/pingone-protect-evaluation.html section_ids: example: Example availability: Availability inputs: Inputs dependencies: Dependencies configuration: Configuration outputs: Outputs outcomes: Outcomes outcome_precedence: Outcome precedence errors: Errors --- # 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). ## Example The following example journey leverages PingOne Protect functionality to perform a risk evaluation. ![Example PingOne Protect journey](_images/pingone-protect-example-journey.png)Figure 1. Example PingOne Protect journey * a The [PingOne Protect Initialize node](pingone-protect-initialize.html) instructs the Ping SDK or Advanced Identity Cloud hosted pages to initialize a PingOne Signals (Protect) SDK with the configured properties. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Initialize a PingOne Signals (Protect) SDK 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. | In the subsequent nodes, the end user enters their credentials, which are verified against the identity store. * b 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 isn't significant, so no further authentication factors are required. The journey continues to a [PingOne Protect Result node](pingone-protect-result.html) that returns the success result to PingOne. * `Exceeds Score Threshold` The score returned is higher than the configured threshold and is considered too risky to complete successfully. The journey continues to a [PingOne Protect Result node](pingone-protect-result.html) that returns the failed result to PingOne. * `Failure` The risk evaluation could not be completed, so the authentication attempt continues to the Failure node. * `TEMP_EMAIL_MITIGATION` The risk evaluation returned a recommended action regarding the possibility of a temporary email address. The journey continues to an [Inner Tree Evaluator node](../inner-tree-evaluator.html) that requires the user to respond to a push notification. * `BOT_MITIGATION` The risk evaluation returned a recommended action to check for the presence of a human. The journey continues to a [CAPTCHA node](../captcha.html). * `AITM_MITIGATION` The risk evaluation returned a recommended action regarding the possible presence of an adversary-in-the-middle attack. The journey continues to a [PingOne Protect Result node](pingone-protect-result.html) that returns the failed result to PingOne. * `ClientError` The client returned an error when attempting to capture the data to perform a risk evaluation. The journey continues to the Failure node. * c An instance of the [PingOne Protect Result node](pingone-protect-result.html) returns the `Success` result to PingOne to help with analysis and risk policy tuning. * d A second instance of the [PingOne Protect Result node](pingone-protect-result.html) returns the `Failed` result to PingOne to help with analysis and risk policy tuning. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | You can broadly observe the risk evaluation results in the [PingOne threat protection dashboard](https://docs.pingidentity.com/pingone/threat_protection_using_pingone_protect/p1_protect_dashboard.html). You can also use an audit to [review specific risk evaluation results](https://docs.pingidentity.com/pingone/threat_protection_using_pingone_protect/p1_protect_reviewing_risk_evaluations.html), including the JSON response from the risk evaluation. | ## Availability | Product | Available? | | ------------------------------------- | ---------- | | PingOne Advanced Identity Cloud | Yes | | PingAM (self-managed) | Yes | | Ping Identity Platform (self-managed) | Yes | | | | | - | ----------------------------------------------------------- | | | You can't use this node inside a [Page node](../page.html). | ## Inputs This node can use shared state variables that contain the PingOne `user.id` and `user.name` as input. If these aren't 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 Initialize 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 to connect to your PingOne instance and send it the necessary data to make risk evaluations. Find more information in [Set up PingOne workers and configure them as Advanced Identity Cloud services](https://docs.pingidentity.com/pingoneaic/integrations/pingone-set-up-workers.html). 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, letting you 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`. If you enable Use Node State Attribute For Target App ID", the node uses this value as a key to retrieve the required value from node state. Otherwise, the node uses the literal value provided in this field. | | Use Node State Attribute For Target App ID | Lets you set a dynamic target app ID. Setting this to `true` instructs the node to get the target app ID from the shared node state, in the variable specified by the value of Target App ID.You should use a [Scripted Decision node](../scripted-decision.html) before this node in the journey to add the target app ID to the shared state variable specified by the value of Target App ID. If you don't set a value for Target App ID the node ignores this setting. | | Target App Name | (Optional) If the user is attempting to access a PingOne application through the journey, add its resource name.This correlates the authentication with the application in PingOne, letting you filter the [audit log](https://docs.pingidentity.com/pingone/monitoring/p1_reporting.html) by the Resource name that matches the value of the Target App Name.For example:```json "event": { "completionStatus": "SUCCESS", "targetResource": { "id": "12345678-abcd-4567-abcd-a123b123c123", "name": "MyApp" }, ... } ``` If you enable Use Node State Attribute For Target App Name", the node uses this value as a key to retrieve the required value from node state. Otherwise, the node uses the literal value provided in this field. If you don't set a value for Target App ID, the node ignores this setting. | | Use Node State Attribute For Target App Name | Lets you set a dynamic target app name. Setting this to `true` instructs the node to get the target app name from the shared node state, in the variable specified by the value of Target App Name.Use a [Scripted Decision node](../scripted-decision.html) before this node in the journey to add the target app name to the shared state variable specified by the value of Target App Name. If you don't set a value for Target App Name the node ignores this setting. | | 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. If you enable Targeted Policies Evaluation, this value is ignored. If you enable Use Node State Attribute For Risk Policy Set ID, the node uses this value as a key to retrieve the required value from node state. Otherwise, the node uses the literal value provided in this field. | | Use Node State Attribute For Risk Policy Set ID | Lets you set a dynamic risk policy set ID. Setting this to `true` instructs the node to get the risk policy set ID from the shared node state, in the variable specified by the value of Risk Policy Set ID.You should use a [Scripted Decision node](../scripted-decision.html) before this node in the journey to add the risk policy set ID to the shared state variable specified by the value of Risk Policy Set ID. If you don't set a value for Risk Policy Set ID the node ignores this setting. If a value corresponding to the key provided in Risk Policy Set ID can't be found, no value is sent to PingOne and the default risk policy is applied. | | Targeted Policies Evaluation | When enabled, the API request sent to PingOne Protect includes a `targeted` property that's set to `true`. This property specifies that PingOne's risk evaluation should process the targeted risk policies defined in the user's PingOne environment instead of using a specific risk policy.PingOne responds with the name and ID of the selected risk policy. For example:```json "riskPolicySet": { "id": "f394426f-9b71-4e01-ac78-2956a2e92ac2", "name": "Score-based policy", "targeted": true }, ```Find more information in [Risk policies](https://docs.pingidentity.com/pingone/threat_protection_using_pingone_protect/p1_protect_risk_policies.html) in the PingOne documentation.Default: Not enabled | | 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`. | | Authentication Flow Subtype | If the Flow Type is `AUTHENTICATION`, select the flow subtype for which the risk evaluation is being carried out.Choose from:- `NONE` - `ACCOUNT_RECOVERY` - `ACTIVE_SESSION` - `KERBEROS` - `NEO_CREDENTIALS` - `PASSKEY` - `PASSWORDLESS` - `USER_CERTIFICATION` - `USER_PASSWORD` - `USERNAME_RECOVERY`The default is `NONE`.If you use the Node State Attribute For Flow Subtype to set the subtype dynamically, that value takes precedence over the static value set here.Learn more about flow types and subtypes in [Risk Evaluations](https://apidocs.pingidentity.com/pingone/platform/v1/api/#risk-evaluations) in the PingOne API documentation. | | Authorization Flow Subtype | If the Flow Type is `AUTHORIZATION`, select the flow subtype for which the risk evaluation is being carried out.Choose from:- `NONE` - `ADD_ADDRESS` - `ADD_MFA` - `ADD_PAYEE` - `ADD_PHONE_NUMBER` - `ADD_USER` - `CHANGE_PASSWORD` - `DELETE_MFA` - `DELETE_PAYEE` - `UPDATE_ADDRESS`The default is `NONE`.If you use the Node State Attribute For Flow Subtype to set the subtype dynamically, that value takes precedence over the static value set here.Learn more about flow types and subtypes in [Risk Evaluations](https://apidocs.pingidentity.com/pingone/platform/v1/api/#risk-evaluations) in the PingOne API documentation. | | Node State Attribute For Flow Subtype | Lets you set a dynamic flow subtype. Setting a value here instructs the node to get the risk flow subtype from this variable in the shared node state.Use a [Scripted Decision node](../scripted-decision.html) before this node in the journey to add the flow subtype to this shared state variable.This field applies only to `AUTHENTICATION` and `AUTHORIZATION` flow types. The dynamic flow subtype takes precedence over any static value set in the Authentication Flow Subtype or Authorization Flow Subtype fields. | | Device Sharing Type | Whether the device is shared between users or not.Choose from:- `UNSPECIFIED` - `SHARED` - `PRIVATE`The default is `SHARED`. | | 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 doesn't 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. - `TEMP_EMAIL_MITIGATION` PingOne suspects the user has entered a temporary email address. Temporary email addresses are often associated with malicious activities. You should route the journey to an [Inner Tree Evaluator node](../inner-tree-evaluator.html), [Scripted Decision node](../scripted-decision.html), or similar, that requires the user to authenticate with a second factor. | | 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 you leave this field blank, or if you provide a variable name but the node can't find it in the node state, it uses the current context `UserId` from the user object as the `user.id`. | | Node State Attribute For Username | The node state variable that contains the `user.name` value to send to PingOne Protect.If you leave this field blank, the node uses the current context `Username` as the `user.name`. If you're using this node in a registration journey associated with a risk policy that includes an Email reputation risk predictor, you must map this attribute to a node state attribute that contains an email address. | | Node State Attribute For User Groups | The node state variable that contains a list of group names to send to PingOne Protect.Use a [Scripted Decision node](../scripted-decision.html) before this node in the journey to add the group names to this shared state variable.The node sends group names under the `event` object. For example:```json "event": { "user": { "groups": [ {"name": "employees"}, {"name": "uk"} ] }, ... } ```- If you leave this field blank, the node uses the current context from the user object. - If you provide a variable name and that variable is *not* in the node state, the node sends no group information to PingOne Protect. It doesn't use the current context from the user object. | | Store Risk Evaluation | Stores the risk evaluation response in the transient node state under a key named `PingOneProtectEvaluationNode.RISK`.Default: Not enabledThe key is empty if the node can't retrieve a risk evaluation from PingOne. | | Node State Attribute For Custom Attributes | The node state variable that contains any custom attributes you want to send to PingOne.Use a [Scripted Decision node](../scripted-decision.html) before this node in the journey to create the node state variable and add it to the shared state.> **Collapse: Example** > > The Scripted Decision Node script adds a map of attributes to the node state. The values of these attributes are *objects* so the node supports strings, integers, and complex objects. > > ```javascript > var details = { > "name": "test-details" > } > var customAttributes = { > "customAttribute1": 20, > "customAttribute2": nodeState.get("username"), > "customAttribute3": details > }; > nodeState.putShared("exampleCustomAttributes", customAttributes); > action.goTo("true"); > ``` > > In this example, the value of the Node State Attribute For Custom Attributes property must be `exampleCustomAttributes`. > > These custom attributes are included in the API request to PingOne Protect in the data under `event.customAttributes`. For example: > > ```json > { > "event": { > "completionStatus": "SUCCESS", > "ip": "127.0.0.1", > "flow": { > "type": "AUTHENTICATION" > }, > "user": { > "id": "id=ce3c42e2-6f9c-4451-8590-9ee40fad3f83,ou=user,o=alpha,ou=services,ou=am-config", > "type": "EXTERNAL" > }, > "sharingType": "SHARED", > "browser": { > "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36" > }, > "device": { > "id": "Id-5a71aeee-0382-4fa3-b903-499cf2a331fb", > "externalId": "example-external-device-ID", > "os": { > "name": "Mac OS X" > }, > "browser": { > "name": "Firefox" > } > }, > "customAttributes": { > "customAttribute1": 20, > "customAttribute2": "bjensen", > "customAttribute3": { > "name": "test-details" > } > } > } > } > ``` | | Node State Attribute For Device External ID | The node state variable that contains an external device ID to send to PingOne Protect in the evaluation request.This property lets you send a custom device ID to PingOne Protect in addition to the device ID provided by the Signals SDK. For example, if your mobile native app incorporates a WebView, the mobile Signals SDK and the web Signals SDK would provide different device IDs. You can use this property to send a single, consistent device ID to PingOne Protect.If you set a value here, the node attempts to find this attribute in the node state and adds its value to the request if it's present and not null. If the attribute isn't in the node state, the node logs a warning.If you leave this field blank, no device external ID is sent in the request. | | Node State Attribute For Event Session ID | The node state variable that contains the session ID to send to PingOne Protect in the risk evaluation request.You can use this session ID to track requests sent to PingOne Protect.If you set a value here, the node attempts to find this attribute in the node state and adds its value to the request if it's present and not `null`. If the attribute isn't in the node state, the node logs a warning.If you leave this field blank, the node sends the Advanced Identity Cloud audit tracking ID for the session. | ## Outputs If you enable the Store Risk Evaluation property, the node outputs the risk evaluation response JSON in a state variable named `PingOneProtectEvaluationNode.RISK`. The node outputs the following data to shared state: * `PINGONE_VERIFY_DELIVERY_METHOD_KEY` The selected delivery method * `PINGONE_VERIFY_TRANSACTION_ID_KEY` The transaction ID to send to PingOne * `PINGONE_VERIFY_TIMEOUT_KEY` The timeout to send to PingOne * `TRANSACTION_POLL_INTERVAL`: The poll interval to send to PingOne * `PINGONE_VERIFY_EVALUATION_FAILURE_REASON_KEY` If the node couldn't obtain the risk evaluation from PingOne, the failure reason. ## 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 couldn't 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 possible values are: * `BOT_MITIGATION`, which recommends you check for the presence of a human, such as by using a CAPTCHA node. * `AITM_MITIGATION`, on suspicion of an adversary-in-the-middle (AitM) attack. The recommended action is to route the journey to the failure node, consider locking the account, and force a password change to mitigate against these attacks. * `TEMP_EMAIL_MITIGATION`, on suspicion of temporary email addresses. The recommended action is to require the user to authenticate with a second factor. * `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 the fields present in the response: ![Risk evaluation outcome path precedence](https://kroki.io/plantuml/svg/eNqVlOFO2zAQx7_7KU7eB7aItWvHgAFiKlCgEi2IlqFJSMhNLo1V165sp6VDPNBeY0-2cwJrhwJo_eCkvv_9_D_7nPoaA_odmunCylHm4fcvaH5qbsDH8NiEC6lH0ElQe-kXJLNTY4WXRrMib5BJB7FJEOjpDQwRcocJ4F2scidnqBYgNSm0xjikwVz67BVqgDqT-rmwCMaCQzuTMbpaEXkxD4ymlUyaonXg8jirhASHCkdCQUGQ6ArqPDOQiRmGWbTkXmoSChhKnYQFFeVqhyBGFnFCoreKWKuzPecXCveZoKpnFD-SlC0mcE8rXoik4DbZA0tMnBfIEID62oGIxyNrcp0cGkXWvRXaTakO7Yn6wPbqj2DmxlJTgJhPvO3VyVdAq7IjTEWu_LHRvicmCPwU1Qy9jAWvVvXlT4TGxiqjZzweGJugLZcaxridNp4LnvlJvmKSbq1i-plIzDwU4m2OjLGdS-nGgDOh8vKQLbqpoZPYZZqIUDQs45zTPLnjO3DPOf0H4Aqp9WiCd9tHnasuX38KuNhYpECjttHc_rLV-DtuLiUmt3HQ8NbJyWX7pDVoH91etzsnp4P-EmQxNhM6uQSTVtHZLmQcnA9uu51Bh5I6572l2i-mBfF76-yqzYvZBxopHUIpTKbwPooaNegHf3StqKTMqCSKbjRdnlSO8tCYQhdXC5FW_fYBfIY65P1AF0UfqIHeYRObaWMnitqFylXxTO7JOsJU-GyXksZSKYaKGpxQe3E4nR1abL9nSmjprVmDy2XJ8Fhzhb-J8HGGrsre0mA3iOiob3QUvYBdtXmjj6ll8E5MpgrXgT_fZ75b0ItKAF6phT4udHfp80DhzzUClY3CowhCm-GNFg5SodSQ2rVMiEWgQRRxfnZ-HaTl_Opun5l51c6uePqH89iUlaguJjKf_A_tlDqzmnVKF-RNEm18uSeseJcpK8c_kgbpsQ==)Figure 2. Risk evaluation outcome path precedence 1. If you've 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`. ## Errors * If a recommended action outcome isn't defined, the node logs the following warning: `Outcome not found for recommended action action` * If PingOne Protect couldn't perform the risk assessment, for whatever reason, the node logs the following warning: `PingOne Protect risk evaluation failed` * If you've configured the node to read the Target App ID, Risk Policy Set ID, or any custom attributes from a shared state attribute, and it's unable to read these values from the shared state, it logs the following warning: `Expected attribute to be defined in node state`