To define the risk configuration, the risk API uses a risk policy set with risk policy conditions defined within the policy set.

Risk policy sets

Risk policy sets are containers for specific risk logic. You can define multiple risk policy sets and deploy them to initiate different authentication flow actions based on the calculated risk. For example, you can define a risk policy set that includes condition logic to block all high-risk IP addresses. Risk policy sets contain a list of ordered risk policies.

Risk policies

Risk policies are made up of the following three components:

Value comparison rules

Value comparison rules compare a placeholder to a value, as shown in the following example:

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

The following table shows supported placeholders and identifies whether the placeholder can be used in value comparison conditions.

Property Description
${details.impossibleTravel} For more information, see the “Details data model” table in the Risk Evaluations topic.
${details.userRiskBehavior.level} For more information, see the “Details data model” table in the Risk Evaluations topic.
${details.ipAddressReputation.level} For more information, see the “Details data model” table in the Risk Evaluations topic.
${details.anonymousNetworkDetected} For more information, see the “Details data model” table in the Risk Evaluations topic.
${details.ipVelocityByUser.level} Available if you’ve signed the data consent and the intelligence.allowDataConsent property in the PingOne license is set to true. See the “Risk predictor data model” in Risk Predictors for more information.
${details.userVelocityByIp.level} Available if you’ve signed the data consent and the intelligence.allowDataConsent property in the PingOne license is set to true. See the “Risk predictor data model” in Risk Predictors for more information.
${details.userRiskBehavior.level} Available only if you’ve signed the data consent and the intelligence.allowDataConsent property in the PingOne license is set to true. See the “Risk predictor data model” in Risk Predictors for more information.

IP range rule

IP range rule designates IP addresses for whitelisting and blacklisting.

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

Weighted average condition

The rule is evaluated as true if the weighted average calculates between the minimum score and the maximum score.

A weight value is assigned to each rule according to its significance, which is determined by the organization’s administrator. The following sample rule shows the weight for two rules: ipRisk 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.ipRisk}",
      "weight": 9
    },
    {
      "value": "${details.aggregatedWeights.geoVelocity}",
      "weight": 4
    }
  ],
  "between": {
    "minScore": 60,
    "maxScore": 90
  }
}

The following table shows supported placeholders and identifies whether the placeholder can be used in weighted average conditions.

Property Description
${details.aggregatedWeights.ipRisk} The placeholder used in a weighted average condition to associate a weight value for the ipRisk rule.
${details.aggregatedWeights.geoVelocity} The placeholder used in a weighted average condition to associate a weight value for the geoVelocity rule.
${details.aggregatedWeights.anonymousNetwork} The placeholder used in a weighted average condition to associate a weight value for the anonymousNetwork rule.
${details.aggregatedWeights.userRiskBehavior} The placeholder used in a weighted average condition to associate a weight value for the userRiskBehavior rule. Available only if you’ve signed the data consent and the intelligence.allowDataConsent property in the PingOne license is set to true.
${details.aggregatedWeights.ipVelocityByUser} The placeholder used in a weighted average condition to associate a weight value for the ipVelocityByUser rule. Available only if you’ve signed the data consent and the intelligence.allowDataConsent property in the PingOne license is set to true. See Risk Predictors for more information.
${details.aggregatedWeights.userVelocityByIp} The placeholder used in a weighted average condition to associate a weight value for the userVelocityByIp rule. Available only if you’ve signed the data consent and the intelligence.allowDataConsent property in the PingOne license is set to true. See Risk Predictors for more information.

Risk policy set data model

Property Description
createdAt The time the resource was created (format ISO-8061).
default A boolean that specifies whether this risk policy set is the environment’s default risk policy set, which is used whenever an explicit policySet ID is not specified in the risk policy evaluation request. If this property is not specified, the value defaults to false, and this risk policy set is not regarded as the default risk policy set for the environment. When this property is set to true (in PUT or POST requests), the default property of all other risk policy sets in the environment is set to false.
defaultResult A result object that specifies the default result returned if none of the conditions in the policy set are evaluated to true. At this time, the defaultResultLevel value must be LOW.
description A string that specifies a description for this policy set. This is an optional property. Valid characters consist of any Unicode letter, mark (for example, accent, umlaut), numeric character, punctuation character, or space. Maximum size is 1024 characters.
environment.id A string that specifies the environment resource’s unique identifier.
id A string that specifies the resource’s unique identifier.
name A string that specifies a name for this policy set. Valid characters consist of any Unicode letter, mark (for example, accent, umlaut), numeric character, forward slash, dot, apostrophe, underscore, space, or hyphen. Maximum size is 256 characters.
riskPolicies An array of policies related to this policy set.
updatedAt The time the resource was last updated (format ISO-8061).

Risk policy data model

Property Description
condition The condition logic that determines when a policy is evaluated to true and when it is evaluated to false.
createdAt The time the resource was first created (format ISO-8061).
description A string that specifies a description for this risk policy. This is an optional property. Valid characters consist of any Unicode letter, mark (for example, accent, umlaut), numeric character, punctuation character, or space. Maximum size is 1024 characters.
environment.id A string that specifies the environment resource’s unique identifier.
id A string that specifies the resource’s unique identifier.
name A string that specifies a name for this risk policy. Valid characters consist of any Unicode letter, mark (for example, accent, umlaut), numeric character, forward slash, dot, apostrophe, underscore, space, or hyphen. Maximum size is 256 characters.
priority An integer that specifies priority of the policy inside a risk policy set, designating which policy should run first. This is a read-only value. The priority is determined by the order in which policies are listed in the policy set. The first policy in the list is assigned priority 1 and is evaluated first. The next policy in the list is assigned priority 2 and so on.
result A result object that specifies the result returned if the policy is evaluated as true. If several policies are evaluated as true, the result related to the highest priority policy is returned. for more information, see the Result attribute data model in the Risk Evaluations topic.
updatedAt The time the resource was last updated (format ISO-8061).

Risk policy limitations

There are limitations on the arrangement of the policies in the risk policy set. These limitations enforce separation between override policies and weighted policies.

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.

Weighted policies

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: