Use the /riskPolicies
administrative API
endpoint to create a risk policy in PingAccess.
- Sign on to the local PingAccess system and start a non-Internet Explorer (IE) browser.
-
Sign on to the API doc page at
https://<host>:<admin-port>/pa-admin-api/v3/api-docs/.
https://localhost:9000/pa-admin-api/v3/api-docs/
Use the normal administrator username, Administrator, and your password.
-
Expand /riskPolicies, then expand
POST
/riskPolicies
. -
Click Paste Model Template.
This button is located just underneath the RiskPolicy field.
-
Fill out the RiskPolicy field using the
RiskPolicyView operation model in the API docs.
You must provide a <className>, <configuration>, and <name> for the risk policy before you can save it. If you don't specify an <id>, this value will be auto-generated when you save the risk policy.
-
Create a PingOne risk policy to
fill out the <configuration>.
A PingOne risk policy uses the following parameters:
- pingOneConnectionId
- The ID of the
PingOne Connection
you created in step 2f of Connecting PingAccess and PingOne Protect. This parameter takes a string value as input. - pingOneRiskPolicyId
- The id of the PingOne risk policy that you want to
use to perform risk evaluation. This optional parameter
takes a string value as input. A value of
null tells PingOne Protect to use a default
policy.Note:
You can only configure a PingOne risk policy in PingOne Protect. For more information, see https://docs.pingidentity.com/bundle/pingone/page/zvv1605740355923.html.
- highRiskPolicy
- A policy that tells PingAccess what action to
take if the returned risk score from an end-user's request
is
HIGH
. This parameter takes aRiskPolicyItem
as input. For more information, see step 5b. - mediumRiskPolicy
- A policy that tells PingAccess what action to
take if the returned risk score from an end-user's request
is
MEDIUM
. This parameter takes aRiskPolicyItem
as input. For more information, see step 5b. - lowRiskPolicy
- A policy that tells PingAccess what action to
take if the returned risk score from an end-user's request
is
LOW
. This parameter takes aRiskPolicyItem
as input. For more information, see step 5b. - failedRiskPolicy
- A policy that tells PingAccess what action to
take if the returned risk score is an invalid value or if
the risk evaluation service is unavailable. This parameter
takes a
RiskPolicyItem
as input. For more information, see step 5b. - riskCheckInterval
- The rate at which PingAccess requests an
evaluation from PingOne Protect
for the same end-user. This optional parameter takes an
integer value configured in milliseconds as input and can
range from zero up to a full day. The default value is
20000 ms (20 seconds).Tip:
To have PingOne Protect perform an evaluation on every request that an end-user makes, you can set this value to 0. However, evaluating every request could slow down your environment's performance.
- userIdAttribute
- Tells PingOne Protect what kind of user attribute to define as an end-user's user id. This parameter takes a string value as input.
-
Create a
RiskPolicyItem
for the highRiskPolicy, mediumRiskPolicy, lowRiskPolicy, and failedRiskPolicy.A
RiskPolicyItem
tells PingAccess what to do with the information it receives. It uses the following parameters:- type
- The type of policy you want to respond to the evaluation
PingOne Protect generated.
Possible responses include:
- authChallenge
- An authentication challenge policy, which directs the user to reauthenticate. If you select this option, you must provide an authenticationChallengePolicyId and authenticationValidityPeriod.
- rule
- A rule, which PingAccess evaluates to determine how to proceed. If you select this option, you must provide the ruleId of a specific web rule.
- ruleset
- A rule set, which PingAccess evaluates to determine how to proceed. If you select this option, you must provide a rulesetId.
- allow
- Permits the end-user's request. If you select this option, you don't need to fill out another parameter.
- deny
- Rejects the end-user's request. If you select this option, you must provide a rejectionHandlerId.
Note:type is mandatory in a
RiskPolicyItem
, but the following parameters are only required if you select a corresponding type option.
- authenticationValidityPeriod
- A permissible window of time since the user last authenticated before they should be challenged to authenticate again. If you set this parameter to five minutes, for example, PingAccess waits for five minutes after the user's last authentication to prompt them to reauthenticate if their risk score returns to the same level.
- authenticationChallengePolicyId
- The id of a specific authentication challenge policy you want to use. Requires a string value.
- ruleId
- The ID of a specific rule you want to use. Requires an integer value.
- ruleSetId
- The ID of a specific ruleset you want to use. Requires an integer value.
- rejectionHandlerId
- The ID of the rejection handler that you want to use. Requires an integer value.
-
Create a PingOne risk policy to
fill out the <configuration>.
-
Click Try it out! to save your risk policy.
After you've created a risk policy, you can assign it to a specific application or resource through the
/applications
or/applications/resources
endpoint.