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 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 are made up of the following three components:
Condition
Policy logic to define when the policy is evaluated to true and when it is evaluated to false.
Result
Policy logic to define what should be returned in case the condition is evaluated to true.
Priority
A priority ranking to define the execution order of the different policies contained in the policy set.
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. |
IP range rule designates IP addresses for whitelisting and blacklisting.
{
"ipRange": ["1.1.1.1/16", "2.2.2.2/24"],
"contains": "${transaction.ip}"
}
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. |
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). |
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). |
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:
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
.