PingGateway 2024.11

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 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:

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

"cookieName": configuration expression<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>, 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"
    }
  }
}