PingOne Platform APIs

PingOne Protect

PingOne Protect applies machine learning and configurable, intelligent security policies to analyze user identity and detect potential threats. It combines multiple risk factors to calculate and retrieve risk scores that can identify and challenge high-risk sign-on attempts while providing a frictionless experience for trusted users.

A client initiates a risk evaluation by sending event information in the following request:

POST {{apiPath}}/v1/environments/{{envID}}/riskEvaluations

The request body specifies the activity to evaluate, such as the user, the user’s IP address, the flow type, and optionally a device profile gathered by the PingOne Signals (Protect) SDK. The event is evaluated against the risk policies in the environment’s risk policy set, and the response returns a risk level for the event along with result details.

PingOne Protect components

The PingOne Protect service provides these capabilities to configure and retrieve risk evaluations:

  • Risk policies. A risk policy is determined by your specific configuration settings. The risk policy enables you to customize a risk evaluation to fit your use case. The policy is used during a risk evaluation to calculate the risk scores for received events. To learn more, refer to Risk Policies.

  • Risk evaluations. Use risk evaluations to calculate the risk level and other risk-related details associated with a received event based on the environment’s settings and data provided in the event. To learn more, refer to Risk Evaluations.

  • Risk predictors. Risk predictors are employed by risk policies, and define thresholds for certain criteria (such as, IP Velocity, User Velocity, or User Location Anomaly) to determine whether there’s the potential for fraudulent user behavior. To learn more, refer to Risk Predictors.

Refer also to PingOne Protect’s integration with Ping Gateway for on-premise use of PingOne Protect with web applications protected by PingGateway.

This service requires PING_ONE_RISK in the Bill of Materials (BOM) for your environment. To check the BOM for the list of PingOne products associated with your environment, refer to Read One Bill of Materials. If PING_ONE_RISK is not in the BOM, contact your PingOne administrator to check whether your license supports adding this product to your environment.

Why use PingOne Protect

Attackers target the identity layer. They steal credentials, spam users with push notifications until one is approved (MFA fatigue), intercept authentication traffic with adversary-in-the-middle proxies, and sign on with bots and anonymizing networks. Static authentication policies cannot distinguish these attempts from legitimate ones because they treat every sign-on the same way.

PingOne Protect addresses this by scoring every event in real time, so the level of friction matches the level of risk:

  • Reduce fraud without adding friction. Trusted users from known devices on expected networks sign on without additional challenges, while suspicious events are stepped up or blocked.

  • Combat MFA fatigue. Low-risk sign-ons can skip MFA entirely, resulting in fewer push notifications, which lowers the probability of unintentional approvals.

  • Identify threats. Predictors such as bot detection, adversary-in-the-middle detection, and anonymous network detection identify attacks that are not recognized by simple sign on.

  • Fine-tune risk predictors. You configure the weights of individual predictors and the thresholds that map scores to risk levels, so the policy reflects your tolerance for fraud versus user friction.

  • Learn user behavior. Behavioral predictors train on your traffic and improve over time.

How PingOne Protect works

PingOne Protect works with your authentication flow. It calculates risk for an event and returns a risk score that your flow uses to determine the next sign-on actions. The workflow includes these steps:

  1. Gather event data. The application, orchestration flow, or integration kit collects context about the sign-on attempt, such as the user identity, the request location, device and browser information, and the current flow.

  2. Request a risk evaluation. The client sends event data to the risk evaluation endpoint. If the request does not specify a risk policy set, the environment uses the default set. The event object identifies the user and the user’s IP address, and information from other predictors to return a meaningful result.

  3. Analyze the event. A risk predictor defines thresholds for certain criteria to determine whether there is the potential for fraudulent user behavior. PingOne Protect leverages the following predictors to learn user behavior and detect anomalies:

    • Adversary-in-the-Middle (AitM)

    • Anonymous network detection

    • Bot detection

    • Device (new device and suspicious device)

    • Email reputation

    • Geovelocity anomaly

    • IP reputation

    • PingID device trust

    • Traffic anomaly

    • User-based risk behavior

    • User location anomaly

    • Velocity (user velocity and IP velocity)

      Each predictor returns its own risk level (Low, Medium, or High). In cases where a level cannot be determined (for example, during a model’s training period), it specifies the reason why the risk level could not be calculated. The following predictors require the Signals (Protect) SDK:

      • adversary-in-the-middle

      • bot detection- suspicious device

      • user-based risk behavior.

  4. Calculate a single result. A risk policy is your configuration of predictors, their weights, and the conditions that map them to a result. The policy aggregates the predictor outcomes into a risk score (a numerical representation of how likely the event is to be malicious) and a risk level (Low, Medium, High).

  5. Act on the result. Based on the response from PingOne Protect, your flow can allow the transaction, deny it, or apply additional mitigation, such as an MFA challenge, a password reset, identity verification, or bot detection measures.

  6. Learn user behavior. After the flow finishes, update the risk evaluation with its completion status (SUCCESS or FAILED). The learning mechanism uses this to improve the precision of future evaluations. You can also send feedback on evaluation accuracy through the riskFeedback endpoint.

PingOne Protect integrations

You can introduce PingOne Protect at any point in a flow where the next action depends on the calculated risk level. Here are some common integration points:

  • PingOne authentication policies. In a PingOne workforce or customer environment, add a risk policy to the application’s registration or authentication policy. PingOne evaluates risk as part of the sign-on flow and can require MFA step-up or deny access based on the risk level.

  • PingOne MFA and PingID policies. Include the risk level that PingOne Protect calculates as a rule in your PingID or PingOne MFA authentication policies, so that each risk level maps to a different MFA action (for example, no challenge for low risk, push verification for medium, and denial for high).

  • PingOne DaVinci flows. Add the PingOne Protect connector to a flow at the point where the next action should be risk-based. You can prompt the user to complete MFA for medium or high risk levels but automatically grant access for low risk. The connector can also issue MFA challenges or deny access in high-risk situations, and the flow updates the evaluation’s completion status.

  • PingFederate. Use the PingOne Protect Integration Kit (or the bundled PingOne Protect adapter) to send transaction information and an optional device profile to PingOne when a user signs on. Including the risk evaluation in your PingFederate authentication policy lets you adjust the user’s authentication requirements dynamically each time they sign on. You can also drive a risk level rule in PingID policies through the PingID adapter.

  • PingOne Advanced Identity Cloud and PingAM journeys. Use the PingOne Protect authentication nodes in your journeys with the login widget or the Ping SDKs, which gather contextual data during a transaction and request the risk evaluation for you.

  • PingGateway. Use PingOne Protect’s integration with PingGateway to evaluate risk for web applications protected by PingGateway, so that on-premise applications get risk-based access decisions at the gateway.

  • Direct API calls. Call the risk evaluation endpoint directly from your application or service. Gather the event data (optionally with the Signals (Protect) SDK), request the evaluation, and branch on the returned level. This pattern suits custom applications, nonstandard flows such as transaction authorization or password reset, and environments without an orchestration engine.

  • Third-party and custom risk data. Send third-party risk scores to PingOne Protect as custom attributes on the event, then build custom predictors on that data and include them in your risk policies alongside the built-in ones.

When there is not enough information for a predictor to provide a risk level, that predictor’s level is excluded from the overall risk score, and the risk evaluation includes details on why it occurred. Behavioral predictors typically need a training period of a few weeks before their results are reliable.