org.forgerock.openig.openam

Class PolicyEnforcementFilter

java.lang.Object

org.forgerock.openig.openam.PolicyEnforcementFilter

All Implemented Interfaces:

org.forgerock.http.Filter

public class PolicyEnforcementFilter
extends Object
implements org.forgerock.http.Filter

This filter requests policy decisions from OpenAM 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": {
          "openamUrl"              :    uriExpression,      [REQUIRED]
          "pepUsername"            :    expression,         [REQUIRED*]
          "pepPassword"            :    expression,         [REQUIRED*]
          "pepRealm"               :    String,             [OPTIONAL*- default value is the one used for "realm"
                                                                        attribute]
          "amHandler"              :    handler,            [OPTIONAL - by default it uses the
                                                                        'ForgeRockClientHandler' provided in heap.]
          "realm"                  :    String,             [OPTIONAL - default is '/']
          "ssoTokenHeader"         :    String,             [OPTIONAL]
          "application"            :    String,             [OPTIONAL]
          "ssoTokenSubject"        :    expression,         [OPTIONAL - must be specified if no jwtSubject or
                                                                        claimsSubject ]
          "jwtSubject"             :    expression,         [OPTIONAL - must be specified if no ssoTokenSubject or
                                                                        claimsSubject ]
          "claimsSubject"          :    map/expression,     [OPTIONAL - must be specified if no jwtSubject or
                                                                        ssoTokenSubject - instance of
                                                                        Map<String, Object> JWT claims ]
          "environment"            :    map/expression,     [OPTIONAL - instance of Map<String, List<Object>>]
          "executor"               :    executor,           [OPTIONAL - by default uses 'ScheduledThreadPool'
                                                                        heap object]
          "failureHandler          :    handler,            [OPTIONAL - default to 403]
          "cache"                  :    object,             [OPTIONAL - cache configuration. Default is no caching.]
              "enabled"            :    boolean,            [OPTIONAL - default to false. Enable or not the caching of
                                                                        the policy decisions.]
              "defaultTimeout"     :    duration,           [OPTIONAL - default to 1 minute. If no valid ttl value is
                                                                        provided by the policy decision, we'll cache
                                                                        it during that duration.]
              "maxTimeout"         :    duration,           [OPTIONAL - If a value is provided by the policy decision
                                                                        but is greater that this value then we'll use
                                                                        that value. ("zero" and "unlimited" are not
                                                                        acceptable values).]
      }
  }
  
 

(*) "pepUsername" and "pepPassword" are the credentials, and "pepRealm" is the realm of the user who has access to perform the operation.

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": {
          "openamUrl": "http://example.com:8090/openam/",
          "pepUsername": "bjensen",
          "pepPassword": "${system['pep.password']}",
          "application": "myApplication",
          "ssoTokenSubject": "${attributes.SSOCurrentUser}",
          "claimsSubject": "${attributes.claimsSubject}",
          "environment": {
              "DAY_OF_WEEK": [
                  "Saturday"
              ]
          }
      }
  }
  
 

See Also:

Requesting Policy Decisions in OpenAM

Nested Class Summary

Nested Classes

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

Constructor Summary

Constructors

Constructor and Description
PolicyEnforcementFilter(org.forgerock.json.resource.RequestHandler requestHandler, org.forgerock.http.Handler failureHandler) Creates a new OpenAM enforcement filter.

Method Summary

Modifier and Type	Method and Description
org.forgerock.util.promise.Promise<org.forgerock.http.protocol.Response,org.forgerock.util.promise.NeverThrowsException>	filter(org.forgerock.services.context.Context context, org.forgerock.http.protocol.Request request, org.forgerock.http.Handler next)
void	setApplication(String application) Sets the application where the policies are defined.
void	setClaimsSubject(org.forgerock.util.Function<Bindings,Map<String,Object>,ExpressionException> claimsSubject) Sets a function that returns a map of JWT claims to their values, for the subject.
void	setEnvironment(org.forgerock.util.Function<Bindings,Map<String,List<Object>>,ExpressionException> 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 Detail

PolicyEnforcementFilter

public PolicyEnforcementFilter(org.forgerock.json.resource.RequestHandler requestHandler,
                               org.forgerock.http.Handler failureHandler)

Creates a new OpenAM 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.

Method Detail

filter

public org.forgerock.util.promise.Promise<org.forgerock.http.protocol.Response,org.forgerock.util.promise.NeverThrowsException> filter(org.forgerock.services.context.Context context,
                                                                                                                                       org.forgerock.http.protocol.Request request,
                                                                                                                                       org.forgerock.http.Handler next)

Specified by:

filter in interface org.forgerock.http.Filter

setApplication

public void setApplication(String application)

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

Parameters:

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

setClaimsSubject

public void setClaimsSubject(org.forgerock.util.Function<Bindings,Map<String,Object>,ExpressionException> 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(org.forgerock.util.Function<Bindings,Map<String,List<Object>>,ExpressionException> 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.