--- title: PingOneProtectEvaluationFilter description: Configure PingOneProtectEvaluationFilter to pass request data to PingOne Protect and retrieve a risk evaluation for use in routing decisions component: pinggateway version: 2026 page_id: pinggateway:reference:PingOneProtectEvaluationFilter canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/PingOneProtectEvaluationFilter.html revdate: 2025-08-14T15:26:17Z section_ids: usage: Usage properties: Properties PingOneProtectEvaluationFilter-pingOneService: pingOneService PingOneProtectEvaluationFilter-failureHandler: failureHandler PingOneProtectEvaluationFilter-userId: userId PingOneProtectEvaluationFilter-policySet: policySet PingOneProtectEvaluationFilter-lowRiskEvaluationThrottlePeriod: lowRiskEvaluationThrottlePeriod PingOneProtectEvaluationFilter-nonEvaluatedUrls: nonEvaluatedUrls PingOneProtectEvaluationFilter-deviceProfile: deviceProfile example: Example more_information: More information --- # 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`, or `high`) * Risk score, a single aggregated numerical value The PingOneProtectEvaluationFilter records the evaluation in a [PingOneProtectEvaluationContext](PingOneProtectEvaluationContext.html) object. Configure a [PingOneProtectThreatLevelRoutingHandler](PingOneProtectThreatLevelRoutingHandler.html) to act on the risk level set in the context. As an alternative, use a [DispatchHandler](DispatchHandler.html) to act on the risk score. ## Usage ```none { "name": string, "type": "PingOneProtectEvaluationFilter", "config": { "pingOneService": PingOneService reference, "failureHandler": Handler reference, "userId": runtime expression, "policySet": configuration expression, "lowRiskEvaluationThrottlePeriod": configuration expression, "nonEvaluatedUrls": configuration expression, "deviceProfile": { "callbackEndpoint": configuration expression, "enabled": configuration expression, "lifetime": configuration expression, "cookieName": configuration expression, "noJavaScriptMessage": configuration expression, "timeout": configuration expression, "failureAction": configuration expression } } } ``` ## Properties ### pingOneService `"pingOneService"`: *Handler [reference](preface.html#definition-reference), required* The [PingOneService](PingOneService.html) to access the evaluation endpoint in the PingOne environment. ### failureHandler `"failureHandler"`: *Handler [reference](preface.html#definition-reference), optional* The [Handler](Handlers.html) 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](preface.html#definition-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](preface.html#definition-string)>, optional* The PingOne Protect policy set to use. Default: The default policy set for the evaluation service ### lowRiskEvaluationThrottlePeriod `"lowRiskEvaluationThrottlePeriod"`: *configuration expression<[duration](preface.html#definition-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](preface.html#definition-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](preface.html#definition-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: ```none "connectors": [ { "port": 8080, "maxTotalHeadersSize": 32768 }, { "port": 8443, "maxTotalHeadersSize": 32768, "tls": "TlsConf" } ], ``` Default: Don't collect device profile data. * `"callbackEndpoint"`: *configuration expression<[string](preface.html#definition-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. * Remain unique to this filter and route. Don't reuse it in other routes or filters, such as a [CrossDomainSingleSignOnFilter](CrossDomainSingleSignOnFilter.html), a [DataPreservationFilter](DataPreservationFilter.html), or a [FragmentFilter](FragmentFilter.html), or in protected applications. 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](preface.html#definition-boolean)>, optional* Enable device profiling. Default: `true` * `"lifetime"`: *configuration expression\, optional* How long to keep collected device profile data before forcing it to be collected again. Default: 5 minutes - `"cookieName"`: *configuration expression<[string](preface.html#definition-string)>, optional* PingGateway stores collected device profile data on the user-agent in one or more cookies with this name. If the device profile cookie data exceeds 4 KBytes, PingGateway automatically splits it into multiple cookies each with a numeric suffix to determine the order. Default: `ig_profile` * `"noJavaScriptMessage"`: *configuration expression<[string](preface.html#definition-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\, optional* How long to wait for the user-agent to respond with device profile data. Default: 500 milliseconds * `"failureAction"`: *configuration expression<[string](preface.html#definition-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: ```json { "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" } } } ``` ## More information [org.forgerock.openig.ping.protect.PingOneProtectEvaluationFilter](../_attachments/apidocs/org/forgerock/openig/ping/protect/PingOneProtectEvaluationFilter.html)