Auth node reference

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.

Example

The following example journey leverages PingOne Protect functionality to perform a risk evaluation.

Example PingOne Protect journey
Figure 1. Example PingOne Protect journey

  • a The PingOne Protect Initialization node 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 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 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 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 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.

    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 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 returns the Success result to PingOne to help with analysis and risk policy tuning.

  • d A second instance of the PingOne Protect Result node 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. You can also use an audit to review specific risk evaluation results, 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.

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 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 to 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 in PingOne.

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

Use Node State Attribute For Target App ID 1

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 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.

Risk Policy Set ID

The ID of the risk policy 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.

Use Node State Attribute For Risk Policy Set ID 1

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 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.

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 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, Scripted Decision node, 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 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.

Default: Not enabled

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

Node State Attribute For Custom Attributes 1

The node state variable that contains any custom attributes you want to send to PingOne.

Use a Scripted Decision node before this node in the journey to create the node state variable and add it to the shared state.

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.

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:

{
  "event": {
    "ip": "127.0.0.1",
    "flow": {
      "type": "AUTHENTICATION"
    },
    "user": {
      "id": "id=bjensen,ou=user,o=alpha,ou=services,ou=am-config",
      "name": "bjensen",
      "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"
    },
    "customAttributes": {
      "customAttribute1": 20,
      "customAttribute2": "bjensen",
      "customAttribute3": {
        "name": "test-details"
      }
    }
  }
}

(1) Currently available only in the rapid release channel.

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 was unable to 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 which fields are present in it, as follows:

Risk evaluation outcome path precedence
Figure 2. 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.

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 wasn’t able to 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