PingOneProtectEvaluationFilter
Passes data to PingOne Protect and gets a risk evaluation for an incoming request.
PingGateway makes a risk evaluation request to PingOne Protect. The PingOne Protect response returns a risk evaluation including the following items PingGateway retains in the evaluation context:
-
Risk level (
low,medium, orhigh) -
Risk score, a single aggregated numerical value
The PingOneProtectEvaluationFilter records the evaluation in a PingOneProtectEvaluationContext object. Configure a PingOneProtectThreatLevelRoutingHandler to act on the risk level set in the context. As an alternative, use a DispatchHandler to act on the risk score.
Usage
{
"name": string,
"type": "PingOneProtectEvaluationFilter",
"config": {
"pingOneService": PingOneService reference,
"failureHandler": Handler reference,
"userId": runtime expression<string>,
"policySet": configuration expression<string>,
"lowRiskEvaluationThrottlePeriod": configuration expression<duration>,
"nonEvaluatedUrls": configuration expression<boolean>,
"deviceProfile": {
"callbackEndpoint": configuration expression<string>,
"enabled": configuration expression<boolean>,
"lifetime": configuration expression<duration>,
"cookieName": configuration expression<string>,
"noJavaScriptMessage": configuration expression<string>,
"timeout": configuration expression<duration>,
"failureAction": configuration expression<string>
}
}
}Properties
pingOneService
"pingOneService": Handler reference, required
The PingOneService to access the evaluation endpoint in the PingOne environment.
failureHandler
"failureHandler": Handler reference, optional
The Handler PingGateway calls when an error occurs.
Default: Return an HTTP 403 Forbidden response; if the request to the evaluation endpoint fails, PingGateway denies access by default.
userId
"userId": runtime expression<string>, optional
An expression setting the user identifier, if available; for example, if the user has already authenticated in the route.
PingGateway raises an error if the expression resolves to null.
Default: A UUID that remains the same for the lifetime of the session
policySet
"policySet": configuration expression<string>, optional
The PingOne Protect policy set to use.
Default: The default policy set for the evaluation service
lowRiskEvaluationThrottlePeriod
"lowRiskEvaluationThrottlePeriod": configuration expression<duration>, optional
When PingOne Protect returns a low risk level for an incoming request, PingGateway waits until this period expires before making another risk evaluation request for the same session.
Set this to zero to make a risk evaluation request for every incoming request.
Default: 2 minutes
nonEvaluatedUrls
"nonEvaluatedUrls": configuration expression<boolean>, optional
A boolean conditional expression matching request URLs to exclude from risk evaluation.
This setting exists for intermediate flows, such as CDSSO requests, that PingGateway shouldn’t evaluate for risk. Don’t use it to exclude ordinary request URIs from risk evaluation.
Default: false (evaluate risk for all request URLs)
deviceProfile
"deviceProfile": object, optional
The settings governing collection and use of device profile data from the user-agent.
After PingGateway collects device profile data, it stores the data in cookies on the user-agent.
The user-agent returns these to PingGateway in the Cookie request header.
Set the maxTotalHeadersSize for the PingGateway server ports
large enough to avoid HTTP 431 Request Header Fields Too Large errors; for example:
"connectors": [
{
"port": 8080,
"maxTotalHeadersSize": 32768
},
{
"port": 8443,
"maxTotalHeadersSize": 32768,
"tls": "TlsConf"
}
],Default: Don’t collect device profile data.
"callbackEndpoint": configuration expression<string>, required-
PingGateway endpoint to transform and manage the collected device profile data.
This endpoint must:
-
Match the
"condition"for the route so PingGateway routes the device profile callback correctly. -
Be different from the callback or redirect endpoints for any other filters in the route, such as a CrossDomainSingleSignOnFilter, a DataPreservationFilter, or a FragmentFilter.
For example, if the route has
"condition": "${find(request.uri.path, '^/home/cdsso')}", and a CrossDomainSingleSignOnFilter with"redirectEndpoint": "/home/cdsso/redirect", choose a different path under the base request URI path like"callbackEndpoint": "/home/cdsso/profilecallback". -
"enabled": configuration expression<boolean>, optional-
Enable device profiling.
Default:
true
"lifetime": configuration expression<duration>, optional-
How long to keep collected device profile data before forcing it to be collected again.
Default: 5 minutes
"noJavaScriptMessage": configuration expression<string>, optional-
PingGateway collects device profile data on the user-agent by sending it a self-submitting form page that uses JavaScript to retrieve the profile information.
When the user-agent won’t run the script, the page displays this message to the end user.
Default:
Javascript is disabled in your browser
"timeout": configuration expression<duration>, optional-
How long to wait for the user-agent to respond with device profile data.
Default: 500 milliseconds
"failureAction": configuration expression<string>, optional-
Action to take when this filter fails to collect device profile data or collection times out; one of:
-
deny: Deny the request without further risk evaluation. -
proceed: Allow risk evaluation to continue without device profile data.
Default:
deny -
Example
The following example prepares PingGateway to make requests to PingOne Protect for risk evaluation.
It doesn’t request risk evaluation for CDSSO redirect requests to /home/cdsso/redirect.
The policy set identifier depends on your PingOne Protect deployment:
{
"name" : "PingOneProtectEvaluationFilter-1",
"type" : "PingOneProtectEvaluationFilter",
"config" : {
"pingOneService" : "PingOneService-1",
"policySet": "47447388-fa5a-40f7-b3f1-24fbbbbc30",
"userId" : "${contexts.cdsso.claimsSet.subject}",
"nonEvaluatedUrls" : "${find(request.uri.path, '/home/cdsso/redirect')}",
"deviceProfile": {
"callbackEndpoint": "/home/cdsso/profilecallback"
}
}
}