Package org.forgerock.openig.openam

Class PolicyEnforcementFilter

java.lang.Object

org.forgerock.openig.openam.PolicyEnforcementFilter

All Implemented Interfaces:

Filter

public class PolicyEnforcementFilter
extends Object
implements Filter

This filter requests policy decisions from Access Management which evaluates the original URI based on the context and the policies configured, and according to the decisions, allows or denies the current request.

If the decision denies the request, a 403 FORBIDDEN is returned. If an error occurred during the process, a 500 INTERNAL SERVER ERROR is returned.

Policy decisions are cached for each filter and eviction is based on the "time-to-live" given in the policy decision returned by AM, if this one exceed the duration expressed in the cacheMaxExpiration, then the value of cacheMaxExpiration is used to cache the policy.

 {
      "type": "PolicyEnforcementFilter",
      "config": {
          "amService"              : AmService            [REQUIRED]
          "application"            : Expression<string>   [OPTIONAL]
          "ssoTokenSubject"        : runtime Expression<String>
                                                          [OPTIONAL - must be specified if no jwtSubject or
                                                                      claimsSubject ]
          "jwtSubject"             : runtime Expression<String>
                                                          [OPTIONAL - must be specified if no ssoTokenSubject or
                                                                      claimsSubject ]
          "claimsSubject"          : runtime Expression<Map>
                                                          [OPTIONAL - must be specified if no jwtSubject or
                                                                      ssoTokenSubject - instance of
                                                                      Map<String, Object> JWT claims ]
          "environment"            : runtime Expression<Map>
                                                          [OPTIONAL - instance of Map<String, List<Object>>]
          "failureHandler          : handler,             [OPTIONAL - default to 403]
          "resourceUriProvider"    : provider             [OPTIONAL - default to a RequestResourceUriProvider.]
          "authenticateResponseRequestHeader"
                                   : Expression<string>   [OPTIONAL - The name of the request header to use for
                                                                      authentication response checks, only supported
                                                                      in combination with the SingleSignOnFilter.
                                                                      Defaults to
                                                           {@link DEFAULT_AUTHENTICATE_RESPONSE_REQUEST_HEADER_NAME}.]
          "useLegacyAdviceEncoding": Expression<boolean>  [OPTIONAL - Deprecated - as it is intended to support a very
                                                                      specific use-case. It should not be configured
                                                                      in the general case.
                                                                      If configured to true then forces use of legacy
                                                                      advice format encoding (none). Default is false,
                                                                      meaning formatting is according to AM version.]
          "cache"                  : object,              [OPTIONAL - cache configuration. Default is no caching.]
              "enabled"            : Expression<boolean>  [OPTIONAL - default to false. Enable or not the caching of
                                                                      the policy decisions.]
              "defaultTimeout"     : Expression<duration> [OPTIONAL - default to 1 minute. If no valid ttl value is
                                                                      provided by the policy decision, we'll cache
                                                                      it during that duration.]
              "maximumTimeToCache" : Expression<duration> [OPTIONAL - If a ttl is provided by the policy decision
                                                                      but if it is greater that this value then
                                                                      we'll use the maximumTimeToCache ("zero" and
                                                                      "unlimited" are not acceptable values).]
              "executor"           : executor             [OPTIONAL - By default, ForkJoinPool#commonPool()
                                                                      is used.]
              "maximumSize"        : Expression<long>     [OPTIONAL - Sets the maximum size of the cache.]
              "onNotificationDisconnection": enum         [OPTIONAL - What to do if AM goes offline:
                                                                      NEVER_CLEAR, CLEAR_ON_DISCONNECT,
                                                                      CLEAR_ON_RECONNECT.
                                                                      Default is: CLEAR_ON_DISCONNECT.]
      }
  }
  
 

This heaplet adds an HeadlessAuthenticationFilter to the amHandler's chain and its role is to retrieve and set the SSO token header of this given user (REST API calls must present the session token, aka SSO Token, in an HTTP header as proof of authentication).

The "attributes" and "advices" from the policy decision are saved in a PolicyDecisionContext.

Example of use:

 {
      "name": "PEPFilter",
      "type": "PolicyEnforcementFilter",
      "config": {
          "amService": "amService",
          "application": "myApplication",
          "ssoTokenSubject": "${attributes.SSOCurrentUser}",
          "claimsSubject": "${attributes.claimsSubject}",
          "environment": {
              "DAY_OF_WEEK": [
                  "Saturday"
              ]
          }
      }
  }
  
 

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	PolicyEnforcementFilter.Heaplet	Creates and initializes a policy enforcement filter in a heap environment.

Constructor Summary

Constructors

Constructor	Description
PolicyEnforcementFilter(RequestHandler requestHandler, Handler failureHandler, SessionService sessionService, ResourceUriProvider resourceUriProvider)	Creates a new enforcement filter.

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.
void	setApplication(String application)	Sets the application where the policies are defined.
void	setClaimsSubject(AsyncFunction<Bindings,Map<String,Object>,NeverThrowsException> claimsSubject)	Sets a function that returns a map of JWT claims to their values, for the subject.
void	setEnvironment(AsyncFunction<Bindings,Map<String,List<Object>>,NeverThrowsException> environment)	The environment passed from the client making the authorization request as a sets a map of keys to lists of values.
void	setJwtSubject(Expression<String> jwtSubject)	Sets the JWT string for the subject.
void	setSsoTokenSubject(Expression<String> ssoTokenSubject)	Sets the SSO token for the subject.

Methods inherited from class java.lang.Object

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

Constructor Details

PolicyEnforcementFilter

public PolicyEnforcementFilter(RequestHandler requestHandler,
 Handler failureHandler,
 SessionService sessionService,
 ResourceUriProvider resourceUriProvider)

Creates a new enforcement filter.

Parameters:

requestHandler - The CREST handler to use for asking the policy decisions.

failureHandler - The handler which will be invoked when policy denies access.

sessionService - The sessionService to use to validate the subject's token

resourceUriProvider - A resourceUriProvider to provide the policy request resource.

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.

setApplication

public void setApplication(String application)

Sets the application where the policies are defined. If none, AM will use the iPlanetAMWebAgentService.

Parameters:

application - The application where the policies are defined. If none, AM will use the iPlanetAMWebAgentService.

setClaimsSubject

public void setClaimsSubject(AsyncFunction<Bindings,Map<String,Object>,NeverThrowsException> claimsSubject)

Sets a function that returns a map of JWT claims to their values, for the subject.

Parameters:

claimsSubject - A function that returns a map of JWT claims for the subject.

setEnvironment

public void setEnvironment(AsyncFunction<Bindings,Map<String,List<Object>>,NeverThrowsException> environment)

The environment passed from the client making the authorization request as a sets a map of keys to lists of values.

Parameters:

environment - A function that returns a map of keys to lists of values.

setSsoTokenSubject

public void setSsoTokenSubject(Expression<String> ssoTokenSubject)

Sets the SSO token for the subject.

Parameters:

ssoTokenSubject - The SSO Token for the subject.

setJwtSubject

public void setJwtSubject(Expression<String> jwtSubject)

Sets the JWT string for the subject.

Parameters:

jwtSubject - The JWT string for the subject.