PingOne Platform APIs

Risk Policies

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, refer to 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}"
}

The IP range rule list has a maximum of 400 CIDRs.

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.

Note:

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

The use of weights in risk policies has been deprecated for new PingOne environments, but weighted policies can still be used in existing environments. For new PingOne environments, use score-based 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 (deprecated)

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

You can use the default policy set to trigger a test policy set in staging, but you cannot put the default policy in staging. In terms of the data model, the default policy set can contain a triggers object, but cannot be the policy set in any triggers.policySet object.

Targeted risk policies

For standard risk policies, you must choose the risk policy to pass to the risk evaluation. Targeted risk policies allow you to define risk policies for different "targets" - combinations of transaction types, user groups, and applications that are being accessed. You can then order the targeted risk policies that you defined. When a risk evaluation is carried out, these targeted policies are processed in the order that you specified. The risk policy that is ultimately used for the risk evaluation will be the first one whose conditions (transaction type, user group, application) are met.

The following JSON snippet shows how to specify the target for a risk policy. For details, refer to the targets object in the Risk policies data model and the Create Risk Policy Set - Targeted Policy with Mitigations example.

    "targets":{
        "condition": { "and": [{
            "list": ["AUTHENTICATION", "AUTHORIZATION"],
            "contains": "${event.flow.type}"
          },
          {
            "list": ["Sales"],
            "contains": "${event.user.groups}"
          },
          {
            "list": ["6b6f867b-d768-4c2c-a9b6-6816da00d824", "845c9918-94d7-430c-b3d8-eafafc215fd9"],
            "contains": "${event.targetResource.id}"
          }]
        }
    }

Using mitigations in your policies

You can choose to include mitigations in your risk policies. In this context, a mitigation is an action that you recommend if a given condition is met, for example, deny access if the email reputation predictor indicates high risk. In situations where the condition is met, the action that you recommended be taken is returned in the risk evaluation response as the value of the result.mitigations[].action field.

The following JSON snippet shows how to define mitigations in a risk policy (within the riskPolicies array). For details, refer to the result.mitigations array in the Risk policies data model and the Create Risk Policy Set - Targeted Policy with Mitigations example.

    {
        "name" : "USER_LOCATION_ANOMALY",
        "result" : {
          "mitigations" : [ {
            "action" : "CUSTOM",
            "customAction" : "CustomActionForUserLocationAnomaly"
          }],
          "type" : "MITIGATION"
        },
        "condition" : {
          "value" : "${details.userLocationAnomaly.level}",
          "equals" : "High",
          "type" : "VALUE_COMPARISON"
        }
      },
      {
        "name" : "VELOCITY",
        "result" : {
          "mitigations" : [ {
            "action" : "DENY_AND_SUSPEND"
          } ],
          "type" : "MITIGATION"
        },
        "condition" : {
          "value" : "${details.ipVelocityByUser.level}",
          "equals" : "High",
          "type" : "VALUE_COMPARISON"
        }
      },{
        "name" : "USER_RISK_BEHAVIOR",
        "result" : {
          "mitigations" : [ {
            "action" : "VERIFY"
          } ],
          "type" : "MITIGATION"
        },
        "condition" : {
          "value" : "${details.userBasedRiskBehavior.level}",
          "equals" : "Medium",
          "type" : "VALUE_COMPARISON"
        }
      },
      {
        "name" : "EMAIL_REPUTATION",
        "result" : {
          "mitigations" : [ {
            "action" : "MFA",
            "mfaAuthenticationPolicyId" : "{{deviceAuthenticationPolicyID}}"
          } ],
          "type" : "MITIGATION"
        },
        "condition" : {
          "value" : "${details.emailReputation.level}",
          "equals" : "High",
          "type" : "VALUE_COMPARISON"
        }
      },
      {
        "name" : "IP_REPUTATION",
        "result" : {
          "mitigations" : [ {
            "action" : "APPROVE"
          } ],
          "type" : "MITIGATION"
        },
        "condition" : {
          "value" : "${details.ipRisk.level}",
          "equals" : "Low",
          "type" : "VALUE_COMPARISON"
        }
    }

Base risk policy set data model

Property Type Required? Mutable? Description

createdAt

Date

N/A

Read-only

The date and time the resource was created (format ISO-8061).

default

Boolean

Optional

Mutable

Indicates whether this risk policy set is the environment’s default risk policy set. This is used whenever an explicit policySet ID is not specified in the risk evaluation request. If this property is not specified when you create or update a risk policy, the value defaults to false, and this risk policy set is not regarded as the default risk policy set for the environment. If you set this property to true, the default property of all other risk policies in the environment is set to false.

defaultResult

Object

Optional

Mutable

Contains the default result returned if none of the conditions in the policy are evaluated to true. At this time, the defaultResult.level value must be LOW.

description

String

Optional

Mutable

A description for this policy set. 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

String

Required

Immutable

The environment resource’s unique identifier.

evaluatedPredictors

Array

N/A

Read-only

The IDs of the risk predictors that are evaluated in the policy. Included in responses to requests to get risk policies.

id

String

Required

Immutable

The resource’s unique identifier.

name

String

Required

Mutable

The name for this policy set. Valid characters consist of any Unicode letter, mark (such as, accent, umlaut), # (numeric), / (forward slash), . (period), ' (apostrophe), _ (underscore), space, or - (hyphen). Maximum size is 256 characters.

riskPolicies

Array

Required

Mutable

The conditions associated with this policy set. Refer also to [Risk policies data model]{#risk-policies-data-model} below.

riskPolicySetTargets.user.matchedGroups

Array

N/A

Read-only

The user groups specified in the policy target that the current user belongs to.

riskPolicySetTargets.user.matchedGroups[].name

String

N/A

Read-only

The name of the user group.

targetedRiskPolicySetsOrder

Array

Optional

Mutable

The targetedRiskPolicySetsOrder array represents the order that was defined for the processing of targeted risk policies in the environment. It contains the IDs of the individual targeted policies. This array is included in the response when you read one or all risk policies and include the expand query parameter set to order in the URL. You can also use targetedRiskPolicySetsOrder to specify a new order for the targeted policies, refer to the [Reorder Targeted Risk Policies]((#post-reorder-targeted-risk-policies) example.

triggers

Object[]

Optional

Mutable

Array that contains trigger definitions for staging mode.

triggers.type

String

Required

Immutable

Trigger type; must be POLICY_SET_STAGING.

triggers.policySet

Object

Required

Immutable

Contains the policy set identifier to trigger.

triggers.policySet.id

String

Required

Immutable

UUID of the policy set to trigger in staging mode.

triggers.expiresAt

String

Required

Immutable

Date and time at which the trigger expires.

updatedAt

Date

N/A

Read-only

The date and time the resource was last updated (format ISO-8061).

Risk policies data model

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

Property Type Required? Mutable? Description

condition

Object

Required

Mutable

Contains the condition logic that determines when a policy is evaluated to true and when it is evaluated to false.

condition.aggregatedScores

Array

Required/Optional

Mutable

Required for score-based policies. The elements in the array are value-score pairs, representing the score that should be assigned to a specific predictor when it is determined that there is a high risk for the predictor.

condition.aggregatedScores.value

String

Required

Mutable

Text that identifies a specific risk predictor in the environment. It uses the form ${details.xxxxxxx.level}, where the string between details and level is the compact name of the relevant predictor.

condition.aggregatedScores.score

Integer

Required

Mutable

The score you want to assign to the predictor when it is determined that there is a high risk for the predictor. Value should be between 0 and 100. 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.

condition.value

String

Optional

Mutable

When defining an override or mitigation, use condition.value to specify the predictor attribute that is checked for the value specified with the condition.equals parameter, for example, ${details.userLocationAnomaly.level}.

condition.equals

String

Optional

Mutable

When defining an override or mitigation, use condition.equals to specify the risk level that the condition is looking for when checking the predictor that you specified with condition.value. For risk predictors with three levels, the value of equals should be High, Medium, or Low. For boolean risk predictors, such as anonymous network detection. the value of equals should be true or false.

condition.type

String

Required

Mutable

Indicates the type of policy you are defining. Can be one of the following values: AGGREGATED_SCORES, AGGREGATED_WEIGHTS (deprecated), VALUE_COMPARISON, and IP_RANGE (for override policies or custom predictors).

condition.between.minScore

Integer

Required/Optional

Mutable

Required for policies of type AGGREGATED_SCORES or AGGREGATED_WEIGHTS. The beginning of the risk score range that will be translated into the specified risk level (MEDIUM or HIGH). Must be between 0 and 1000.

condition.between.maxScore

Integer

Required/Optional

Mutable

Required for policies of type AGGREGATED_SCORES or AGGREGATED_WEIGHTS. The end of the risk score range that will be translated into the specified risk level (MEDIUM or HIGH). Must be between 0 and 1000.

createdAt

Date

Required

Immutable

The date and time the resource was first created (format ISO-8061).

description

String

Optional

Mutable

A description for this risk policy. Valid characters consist of any Unicode letter, mark (for example, accent, umlaut), # (numeric), / (forward slash), . (period), ' (apostrophe), _ (underscore), space, or - (hyphen). Maximum size is 1024 characters.

environment.id

String

Required

Immutable

The environment resource’s unique identifier.

id

String

Required

Immutable

The resource’s unique identifier.

name

String

Required

Mutable

The name to use for the condition. Valid characters consist of any Unicode letter, mark (for example, accent, umlaut), # (numeric), / (forward slash), . (period), ' (apostrophe), _ (underscore), space, or - (hyphen). Maximum size is 256 characters.

priority

Integer

N/A

Read-only

The index of the element in the riskPolicies array.

result

Object

Required

Mutable

The result object is used to specify the risk level that should be assigned if the defined condition is met. When defining mitigations, result is used to specify the action that is being recommended.

result.level

String

Required

Mutable

Contains the risk level that is returned if the condition is evaluated as true. If several policies are evaluated as true, the result related to the lowest priority condition is returned. For more information, refer to the Result attribute data model in Risk Evaluations.

result.mitigations

Array

Optional

Mutable

For mitigations that you define, contains the action that is being recommended if the specified condition is met.

result.mitigations[].action

String

Required

Mutable

The action that is being recommended if the condition specified for the mitigation is met. Can take any of the following values: APPROVE, VERIFY, MFA, DENY, DENY_AND_SUSPEND, CUSTOM. If you set action to MFA, use mfaRegistrationPolicyId and mfaAuthenticationPolicyId to specify the IDs of the MFA registration policy and MFA authentication policy that should be used. If you set action to VERIFY, use verifyPolicyId to specify the ID of the Verify policy that should be used. If you set action to CUSTOM, use customAction to specify the custom action that you want to recommend.

result.mitigations[].customAction

String

Optional

Mutable

If you set the action parameter to CUSTOM, use customAction to specify the custom action that you want to recommend.

result.mitigations[].mfaAuthenticationPolicyId

String

Optional

Mutable

If you set the action parameter to MFA, use mfaAuthenticationPolicyId to specify the ID of the MFA policy that should be used for authentication flows.

result.mitigations[].mfaRegistrationPolicyId

String

Optional

Mutable

If you set the action parameter to MFA, use mfaRegistrationPolicyId to specify the ID of the MFA policy that should be used for registration flows.

result.mitigations[].verifyPolicyId

String

Optional

Mutable

If you set the action parameter to VERIFY, use verifyPolicyId to specify the ID of the Verify policy that should be used.

result.type

String

Optional

Mutable

Can be one of two values: MITIGATION, MITIGATION_FALLBACK. When defining a mitigation, you must set result.type to MITIGATION. Policies that include mitigations must also include a fallback action. For the fallback action, result.type must be set to MITIGATION_FALLBACK.

targets

Object

Optional

Mutable

For targeted policies, used to define the conditions for applying the policy.

targets.condition

Object

Optional

Mutable

Used to specify the conditions for applying the policy - the type of flows, the user groups, and the applications that are being accessed.

targets.condition.and

Array

Optional

Mutable

Array of the conditions for applying the policy. It is mandatory to include in the array the relevant transaction types. The relevant user groups and applications are optional. Each element in the array contains the target transaction types/user groups/applications and the event attribute that is checked.

targets.condition.and[].list

Array

Optional

Mutable

Used to list the strings for the target transaction types, user groups, or applications, for example, ["AUTHENTICATION", "AUTHORIZATION"]. For transaction types, should contain one or more of the following: REGISTRATION,AUTHENTICATION,ACCESS,AUTHORIZATION,TRANSACTION. For user groups, should contain the name of one or more user groups. For applications, should contain the PingOne ID of one or more applications.

targets.condition.and[].contains

String

Optional

Mutable

The event attribute that is checked for the values specified in the list parameter. For transaction type, this should be set to ${event.flow.type}. For user groups, this should be set to ${event.user.groups}. For applications, this should be set to ${event.targetResource.id}.

targets.condition.and[].type

String

N/A

Read-only

Included in risk policy responses. For transaction types, value returned is STRING_LIST. For user groups, value returned is GROUPS_INTERSECTION. For transaction types, value returned is STRING_LIST.

targets.condition.type

String

N/A

Read-only

Included in risk policy responses for targeted policies. Value returned is AND if there is more than one condition, and value returned is VALUE_COMPARISON if there is only one condition.

updatedAt

Date

Required

Immutable

The date and time the resource was last updated (format ISO-8061).

Risk policies events generated

Refer to Audit Reporting Events for the events generated.

Related topics