--- title: Risk Policies description: 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. component: pingone-api page_id: pingone-api:protect:risk-policies canonical_url: https://developer.pingidentity.com/pingone-api/protect/risk-policies.html section_ids: value-comparison-conditions: Value comparison conditions ip-range-conditions: IP range conditions override-policies: Override policies combining-predictors: Combining predictors weighted-policies: Weighted policies score-policies: Score policies condition-type: Condition type risk-staging-policy-set: Risk staging policy set targeted-risk-policies: Targeted risk policies using-mitigations-in-your-policies: Using mitigations in your policies assigning-admin-roles-and-permissions-to-this-service: Assigning admin roles and permissions to this service base-risk-policy-set-data-model: Base risk policy set data model risk-policies-data-model: Risk policies data model risk-policies-events-generated: Risk policies events generated --- # 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](#get-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: ```none { "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. ```none { "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:**- A policy set can include overrides or [mitigations](#using-mitigations-in-your-policies), but not both. - Overrides cannot be included in [targeted policies](#targeted-risk-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 | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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: ```none { "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. ```none { "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](#put-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. ```none "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. ```none { "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" } } ``` ## Assigning admin roles and permissions to this service Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to [PingOne Permissions by Service](../platform/reference/roles-and-permissions-in-pingone/permissions-by-service.html) for the service-specific permissions. You can also choose to assign admin roles based on particular service resources. Refer to [PingOne Permissions by Resource](../platform/reference/roles-and-permissions-in-pingone/permissions-by-resource.html) when assigning admin roles per service resources. Admin assignments to roles are set by: * [Automatic assignment for some roles](../platform/roles/predefined-roles.html#automatic-role-assignment). * [Group Role Assignments](../platform/group-role-assignments/group-role-assignments.html). * [User Role Assignments](../platform/users/user-role-assignments.html). Refer to [Roles Management](../platform/roles.html) for more information. ## 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](#risk-evaluations) 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](/pingone/platform/v1/api/#audit-reporting-events) for the events generated. > **Collapse: Related topics** > > * [Create a risk policy set](#post-create-risk-policy-set)