Package org.forgerock.openig.openam

Class 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

    • 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.