Risk policies enable you to customize the risk evaluations to your specific needs. Risk policies are containers for specific risk logic. You can define multiple risk policies and deploy them to initiate different authentication flow actions based on the calculated risk. By default, every PingOne environment has an associated system-level default risk policy set.

For more information about the default risk policies, see the example response in Read Risk Policy Sets. Each risk policy set contains a list of risk policies. The maximum number of policy sets per environment is 100; the maximum number of policies per policy set is 100.

Risk policies have the components:

• Condition

  A Boolean predicate that defines when the policy element is evaluated to true and when it is evaluated to false.

• Result

  Defines the final result of the risk evaluation when the condition is evaluated to true.

Value comparison conditions

Value comparison conditions compare a placeholder to a value. For example:

{
  "value": "${some.placeholder}",
  "equals": "some value"
}

The value is the outcome of one of the risk predictors.

IP range conditions

IP range conditions designate IP addresses for whitelisting and blacklisting.

{
  "ipRange": ["1.1.1.1/16", "2.2.2.2/24"],
  "contains": "${transaction.ip}"
}

Override policies

Override policies are the ones with the highest priority. They should be listed at the beginning of the riskPolicies array. They can have value comparison condition rules or IP range condition rules. The risk policy array can have no override policies or multiple override policies.

Combining predictors

There are two methods of combining the predictors - Weights and Scores. When you use the Weights approach, you are determining relative weights that should be used when calculating the individual risk score for each predictor. When you use the Scores approach, you can exercise more control over the overall calculation because you can specify an exact numerical score that should be assigned when PingOne Protect determines that there is a medium or high risk level for a predictor.

Weighted policies

Weighted policies allow you to combine results from multiple predictors.

Weighted policies determine risk based on aggregated weighted risk score. These policies must be listed in the riskPolicies array after all override policies are specified. An aggregated risk score involves two weighted policies, and these policies must be the last policies in the riskPolicies array.

The weighted policies that determine the aggregated risk score complement each other and are subject to these restrictions:

• The first weighted policy should have result.level=MEDIUM and the second should have result.level=HIGH.

• The value for the condition.aggregatedWeights attribute for both policies must be the same.

• The value for the condition.between.maxScore attribute for the HIGH weighted policy must be 100.

• The value of the condition.between attribute for the two policies must be complementary. For example, if the HIGH policy has condition.between.minScore = 70, the MEDIUM policy should have condition.between.maxScore = 70.

• condition.type should be set to AGGREGATED_WEIGHTS.

• Choose the weight value assigned to each predictor outcome according to its significance. The following example shows the weight for two predictors: ipAddressReputation at 9 and the weight for geoVelocity at 4. The maximum and minimum scores are set at 60 and 90, respectively:

{
  "aggregatedWeights": [
    {
      "value": "${details.aggregatedWeights.ipAddressReputation}",
      "weight": 9
    },
    {
      "value": "${details.aggregatedWeights.geoVelocity}",
      "weight": 4
    }
  ],
  "between": {
    "minScore": 60,
    "maxScore": 90
  }
}

The value of value consists of the identifier for a specific predictor, and it takes the form ${details.aggregatedWeights.geoVelocity}, where the string after aggregatedWeights is the compact name of the relevant predictor.

Score policies

The JSON content below shows an example of a policy set that uses the Scores approach to risk calculation.

Details to note about the use of score policies:

• If you are including overrides in the policy set, they must precede the score policies.

• The policy set must include two score policies - one that includes the score range that should be translated into MEDIUM risk, and one that includes the score range that should be translated into HIGH risk.

• In terms of order, the MEDIUM policy must precede the HIGH policy.

• Use condition.between.minScore and condition.between.maxScore to define the ranges for MEDIUM risk and HIGH risk. The maxScore for MEDIUM risk should always equal the minScore for HIGH risk.

• condition.type should be set to AGGREGATED_SCORES.

• The condition object should contain an aggregatedScores object that consists of an array of value/score pairs. The value of value consists of the identifier for a specific predictor, and it takes the form ${details.userLocationAnomaly.level}, where the string between details and level is the compact name of the relevant predictor. The value of score is the score you want to assign to that predictor when it is determined that there is a high risk for the predictor. If it is determined that there is medium risk, the predictor will automatically be assigned a score equal to half of the value you specified for high risk.

• The array in condition.aggregatedScores must be identical in the MEDIUM policy that you define and the HIGH policy that you define.

{
    "id": "944fa7b4-e280-4932-80e7-01853ac9ce6d",
    "name": "aa",
    "default": false,
    "defaultResult": {
        "level": "Low"
    },
    "riskPolicies": [
        {
            "name": "ANONYMOUS_NETWORK_DETECTION",
            "result": {
                "level": "HIGH"
            },
            "condition": {
                "value": "${details.anonymousNetworkDetected}",
                "equals": true
            }
        },
        {
            "name": "GEOVELOCITY_ANOMALY",
            "result": {
                "level": "MEDIUM"
            },
            "condition": {
                "value": "${details.impossibleTravel}",
                "equals": true
            }
        },
        {
            "name": "Medium score policy",
            "result": {
                "level": "MEDIUM"
            },
            "condition": {
                "type" : "AGGREGATED_SCORES",
                "aggregatedScores": [
                    {
                        "value": "${details.userLocationAnomaly.level}",
                        "score": 40
                    },
                    {
                        "value": "${details.anonymousNetwork.level}",
                        "score": 60
                    },
                    {
                        "value": "${details.ipRisk.level}",
                        "score": 40
                    }
                ],
                "between": {
                    "minScore": 700,
                    "maxScore": 900
                }
            }
        },
        {
            "name": "High score policy",
            "result": {
                "level": "HIGH"
            },
            "condition": {
                "type" : "AGGREGATED_SCORES",
                "aggregatedScores": [
                    {
                        "value": "${details.userLocationAnomaly.level}",
                        "score": 40
                    },
                    {
                        "value": "${details.anonymousNetwork.level}",
                        "score": 60
                    },
                    {
                        "value": "${details.ipRisk.level}",
                        "score": 40
                    }
                ],
                "between": {
                    "minScore": 900,
                    "maxScore": 1000
                }
            }
        }
    ]
}

Condition type

The condition.type field indicates the type of policy you are defining. It can take any of the following values:

• AGGREGATED_SCORES
• AGGREGATED_WEIGHTS
• VALUE_COMPARISON
• IP_RANGE (for override policies or custom predictors)

Risk staging policy set

Risk staging policy allows you to test a policy set in parallel with another policy set. You link an existing policy set to the test policy set with a triggers object in the existing policy set, which points to the test policy set in its triggers.policySet object. Every time the existing policy set runs, it triggers the test policy set to also run. While in staging, the test policy set runs but only records its evaluation. A trigger expires 3 months from when it is set. Use Update Risk Policy Set to add the triggers object to an existing policy set.

Base risk policy set data model

Risk policies data model

This table lists the fields and objects that can be included in each of the elements in the riskPolicies array.

Audit reporting events

To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

Related topics