Package org.forgerock.openig.ping.protect

Class PingOneProtectEvaluationFilter

java.lang.Object

org.forgerock.openig.ping.protect.PingOneProtectEvaluationFilter

All Implemented Interfaces:

Filter

public class PingOneProtectEvaluationFilter
extends Object
implements Filter

The PingOneProtectEvaluationFilter supports integration with PingOne Protect. Requests are intercepted and evaluated by PingOne Protect. The evaluation result is packaged in a PingOneProtectEvaluationContext so that it can be used later in the route to determine the appropriate course of action, such as routing the request based on risk level or score.

Failures may be managed via a failure handler, which is supplied with a FailureContext.

 {
      "type": "PingOneProtectEvaluationFilter",
      "config": {
         "pingOneService"       : Config Expression<URI>      [REQUIRED - The PingOne environment service endpoint.]
         "failureHandler"       : Handler                     [OPTIONAL - Handler called upon error - defaults to 403
                                                                          Forbidden. That is, failure to communicate
                                                                          with the evaluation endpoint will deny by
                                                                          default.]
         "userId"               : Runtime Expression<String>  [OPTIONAL - Expression indicating how 'userId' should be
                                                                          obtained if available - see note (1).
                                                                          Defaults to a unique UUID.]
         "policySet"            : Config Expression<String>   [OPTIONAL - The policy set to use - defaults to
                                                                          evaluation service default.]
         "lowRiskEvaluationThrottlePeriod": Config Expression<Duration>
                                                              [OPTIONAL - Limit calls to PingOne Protect evaluations
                                                                          within a period of the given duration, for
                                                                          low-risk evaluations - see note (2).
                                                                          A value of zero forces all requests to be
                                                                          evaluated. Default is 2 minutes.]
         "nonEvaluatedUrls"     : Runtime Expression<Boolean> [OPTIONAL - A runtime boolean expression indicating
                                                                          request URL(s) that should be excluded from
                                                                          risk evaluation - see note (3). Defaults to
                                                                          false - indicating all should be evaluated.
         "deviceProfile"        : { object }                  [OPTIONAL - Device profiling config - see note (4).]
      }
  }
  
 

1. The 'userId' indicates how the user id should be obtained if available, via an expression - i.e. if user is already authenticated in the route. Otherwise, a UUID that is stable over the session lifetime is used.
2. The 'lowRiskEvaluationThrottlePeriod' is intended to reduce load on the PingOne Protect endpoint. 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. A value of zero forces all requests to be evaluated by Protect.
3. The 'nonEvaluatedUrls' explicitly excludes matching request URLs from being risk evaluated, in order to support complex authentication scenarios, where intermediate flows should not be evaluated for risk - e.g. cross-domain single sign-on redirects. When encountered, the previous evaluation result will be used to route the request. Note that this should not be used to prevent ordinary request URIs from being evaluated (with no prior evaluation result).
4. Provision of 'deviceProfile', with 'enabled' true will cause PingGateway to conduct device profiling prior to making a risk evaluation call to PingOne Protect. See PingOneProtectDeviceProfileFilter for more information. See PingOneProtectDeviceProfileFilter.HeapletSupport for 'deviceProfile' config.

The example configuration below illustrates PingOne Protect risk evaluation:

 {
     "name" : "riskEvaluationFilter",
     "type" : "PingOneProtectEvaluationFilter",
     "config" : {
       "pingOneService" : "MyPingOneEnv",
       "policySet": "47447388-fa5a-40f7-b3f1-24fbbbbc30",
       "lowRiskThrottlePeriod": "10 minutes",
       "nonEvaluatedUrls": "${find(request.uri.path, '/home/cdsso/redirect')}"
     }
 }
 
 

Notes:

• The lowRiskThrottlePeriod is set to 10 minutes, so if a risk evaluation for a request evaluates to 'low', then subsequent requests within that 10-minute period (and within this HTTP session) will also be considered to be low-risk. The first request after the period completes, will cause a new risk evaluation call to Protect.
• This config expects the cross-domain SSO (CrossDomainSingleSignOnFilter) to play a part of the post-evaluation actions, and so has configured the nonEvaluatedUrls condition to exclude the CrossDomainSingleSignOnFilter redirect URI, so that it is not itself evaluated.

See Also:

• PingOneService
• PingOneProtectEvaluationContext
• PingOneProtectThreatLevelRoutingHandler
• PingOneProtectFeedbackFilter

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	PingOneProtectEvaluationFilter.Heaplet	Creates and initialises a PingOneProtectEvaluationFilter in a heap environment.

Method Summary

Modifier and Type	Method	Description
Promise<Response,NeverThrowsException>	filter(Context context, Request request, Handler next)	Filters the request and/or response of an exchange.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

filter

public Promise<Response,NeverThrowsException> filter(Context context,
 Request request,
 Handler next)

Description copied from interface: Filter

Filters the request and/or response of an exchange. To pass the request to the next filter or handler in the chain, the filter calls next.handle(context, request).

This method may elect not to pass the request to the next filter or handler, and instead handle the request itself. It can achieve this by merely avoiding a call to next.handle(context, request) and creating its own response object. The filter is also at liberty to replace a response with another of its own by intercepting the response returned by the next handler.

Specified by:

filter in interface Filter

Parameters:

context - The request context.

request - The request.

next - The next filter or handler in the chain to handle the request.

Returns:

A Promise representing the response to be returned to the client.