PolicyEnforcementFilter

Requests policy decisions from AM, which allows or denies the request based on the request context, the request URI, and the AM policies.

Supported with AM 5 and later versions.

Processing Requests After a Policy Decision

After a policy decision, IG continues to process requests as follows:

  • If the request is allowed, processing continues.

  • If the request is denied with advices, IG checks whether it can respond to the advices. If IG can respond, it sends a redirect and information about how to meet the conditions in the advices.

    By default, the request is redirected to AM. If the SingleSignOnFilter property loginEndpoint is configured, the request is redirected to that endpoint.

  • If the request is denied without advice, or if IG cannot respond to the advice, IG forwards the request to a failureHandler declared in the PolicyEnforcementFilter. If there is no failureHandler, IG returns a 403 Forbidden.

  • If an error occurs during the process, IG returns 500 Internal Server Error.

Using Advices From Policy Decisions

Attributes and advices returned by the policy decision are stored in the policyDecision context. For information, see PolicyDecisionContext.

IG responds to the following advice types from AM:

  • AuthLevel: The minimum authentication level at which a user-agent must authenticate to access a resource.

  • AuthenticateToService: The name of an authorization chain or service to which a user-agent must authenticate to access a resource.

  • AuthenticateToRealm: The name of a realm to which a user-agent must authenticate to access a resource.

  • AuthScheme: The name of an authentication module to which a user-agent must authenticate to access a resource, the policy set name, and the authentication timeout.

  • Transaction: The additional actions that a user-agent must perform before having a one-time access to the protected resource. Supported with AM 5.5 and later versions.

Notes on Configuring Policies in AM

In the AM policy, remember to configure the Resources parameter with the URI of the protected application.

The request URI from IG must match the Resources parameter defined in the AM policy. If the URI of the incoming request is changed before it enters the policy filter (for example, by rebasing or scripting), remember to change the Resources parameter in AM policy accordingly.

WebSocket Notifications for Policy Changes

When WebSocket notifications are set up for changes to policies, IG receives a notification from AM when a policy decision is created, deleted, or updated.

For information about setting up WebSocket notifications, using them to clear the policy cache, and including them in the server logs, see WebSocket Notifications.

Usage

{
  "name": string,
  "type": "PolicyEnforcementFilter",
  "config": {
    "amService": AmService reference,
    "pepRealm": string,
    "ssoTokenSubject": runtime expression<string>,
    "jwtSubject": runtime expression<string>,
    "claimsSubject": map or runtime expression<map>,
    "cache": object,
    "application": configuration expression<string>,
    "environment": map or runtime expression<map>,
    "failureHandler": handler reference,
    "resourceUriProvider": ResourceUriProvider reference
  }
}

Properties

"amService": AmService reference, required

The AmService object to use for the following properties:

  • agent, the credentials of the IG agent in AM. When the agent is authenticated, the token can be used for tasks such as getting the user’s profile, making policy evaluations, and connecting to the AM notification endpoint.

  • realm: Realm of the IG agent in AM.

  • url, the URL of an AM service to use for session token validation and authentication.

  • ssoTokenHeader, the name of the HTTP header that provides the session token created by AM

  • amHandler, the handler to use when requesting policy decisions from AM.

  • version: The version of the AM server.

    See also AmService.

"pepRealm": string, optional

The AM realm where the policy set is located.

Default: The realm declared for amService.

"ssoTokenSubject": _runtime expression<string>, required if neither of the following properties are present: jwtSubject, claimsSubject

The AM SSO or CDSSO token ID string for the subject making the request to the protected resource.

ssoTokenSubject can take the following values:

  • ${contexts.ssoToken.value}, when the SingleSignOnFilter is used for authentication

  • ${contexts.ssoToken.value} or ${contexts.cdsso.token}, when the CrossDomainSingleSignOnFilter is used for authentication

When there is no SSO (API protection), ssoTokenSubject usually points to a header value such as ${request.headers.iPlanetDirectoryPro[0]}, where iPlanetDirectoryPro is the name of the default AM session cookie. To find the name of your AM session cookie, see Find the Name of Your AM Session Cookie.

"jwtSubject": _runtime expression<string>, required if neither of the following properties are present: ssoTokenSubject, claimsSubject

The JWT string for the subject making the request to the protected resource.

To use the raw id_token (base64, not decoded) returned by the OpenID Connect Provider during authentication, place an OAuth2ClientFilter filter before the PEP filter, and then use ${attributes.openid.id_token} as the expression value.

"claimsSubject": _map or runtime expression<map>, required if neither of the following properties are present: jwtSubject, ssoTokenSubject

A representation of JWT claims for the subject.

The claim "sub" must be specified. Other claims are optional.

When this property is an expression, its evaluation must give an object of type Map<String, Object>.

"claimsSubject": "${attributes.openid.id_token_claims}"

When this property is a map, the structure must have the format Map<String, Object>. The value is evaluated as an expression.

"claimsSubject": {
  "sub": "${attributes.subject_identifier}",
  "iss": "openam.example.com"
}

For an example of using claimsSubject as a map, see Example Policy Enforcement Using claimsSubject on this reference page.

"application": configuration expression<string>, optional

The ID of the AM policy set to use when requesting policy decisions.

Default: iPlanetAMWebAgentService, provided by AM’s default policy set

cache: object, optional

Enable and configure caching of policy decisions from AM, based on Caffeine. For more information, see the GitHub entry, Caffeine .

{
  "cache": {
    "enabled": configuration expression<boolean>,
    "defaultTimeout": configuration expression<duration>,
    "executor": executor service reference,
    "maximumSize": configuration expression<number>,
    "maximumTimeToCache": configuration expression<duration>,
    "onNotificationDisconnection": configuration expression<enumeration>
  }
}

Default: Policy decisions are not cached.

Policy decisions that contain advices are never cached.

The following code example caches AM policy decisions without advices for these times:

  • One hour, when the policy decision doesn’t provide a ttl value.

  • The duration specified by the ttl, when ttl is shorter than one day.

  • One day, when ttl is longer than one day.

"cache": {
  "enabled": true,
  "defaultTimeout": "1 hour",
  "maximumTimeToCache": "1 day"
}
enabled: configuration expression<boolean>, optional

Enable or disable caching of policy decisions.

When a policy decision is cached, IG can reuse the policy decision without repeatedly asking AM for a new policy decision. When caching is disabled, IG must ask AM to make a decision for each request.

Default: false

defaultTimeout: configuration expression<duration>, optional

The default duration for which to cache AM policy decisions.

If an AM policy decision provides a valid ttl value to specify the time until which the policy decision remains valid, IG uses that value or the maxTimeout.

Default: 1 minute

executor: executor service reference, optional

An executor service to schedule the execution of tasks, such as the eviction of entries in the cache.

Default: ForkJoinPool.commonPool()

"maximumSize": configuration expression<number>, optional

The maximum number of entries the cache can contain.

Default: Unlimited/unbound.

maximumTimeToCache: configuration expression<duration>, optional

The maximum duration for which to cache AM policy decisions.

If the ttl value provided by the AM policy decision is after the current time plus the maximumTimeToCache, IG uses the maximumTimeToCache.

The duration cannot be zero or unlimited.

onNotificationDisconnection: configuration expression<enumeration>, optional

The strategy to manage the cache when the WebSocket notification service is disconnected, and IG receives no notifications for AM events. If the cache is not cleared it can become outdated, and IG can allow requests on revoked sessions or tokens.

Cached entries that expire naturally while the notification service is disconnected are removed from the cache.

Use one of the following values:

  • NEVER_CLEAR

    • When the notification service is disconnected:

      • Continue to use the existing cache.

      • Deny access for requests that are not cached, but do not update the cache with these requests.

    • When the notification service is reconnected:

      • Continue to use the existing cache.

      • Query AM for incoming requests that are not found in the cache, and update the cache with these requests.

  • CLEAR_ON_DISCONNECT

    • When the notification service is disconnected:

      • Clear the cache.

      • Deny access to all requests, but do not update the cache with these requests.

    • When the notification service is reconnected:

      • Query AM for all requests that are not found in the cache. (Because the cache was cleared, the cache is empty after reconnection.)

      • Update the cache with these requests.

  • CLEAR_ON_RECONNECT

    • When the notification service is disconnected:

      • Continue to use the existing cache.

      • Deny access for requests that are not cached, but do not update the cache with these requests.

    • When the notification service is reconnected:

      • Query AM for all requests that are not found in the cache. (Because the cache was cleared, the cache is empty after reconnection.)

      • Update the cache with these requests.

Default: CLEAR_ON_DISCONNECT

"environment": map or runtime expression<map>, optional

A list of strings to forward to AM with the request for a policy decision, that represent the environment (or context) of the request. Forward any HTTP header or any value that the AM policy definition can use.

AM can use the environment conditions to set the circumstances under which a policy applies. For example, environment conditions can specify that the policy applies only during working hours or only when accessing from a specific IP address.

If this property is a map, the structure must have the format Map<String, List<String>>. In the following example, the PolicyEnforcementFilter forwards standard and non-standard request headers, an ID token, and the IP address of the subject making the request:

"environment": {
  "H-Via": "${request.headers['Via']}",
  "H-X-Forwarded-For": "${request.headers['X-Forwarded-For']}",
  "H-myHeader": "${request.headers['myHeader']}",
  "id_token": [
    "${attributes.openid.id_token}"
  ],
  "IP": [
    "${contexts.client.remoteAddress}"
  ]
}

If this property is an expression, its evaluation must give an object of type Map<String, List<String>>.

"environment": "${attributes.my_environment}"
"failureHandler": handler reference, optional

Handler to treat the request if it is denied by the policy decision.

In the following example, the failureHandler is a chain with a scriptable filter. If there are some advices with the policy decision, the script recovers the advices for processing. Otherwise, it passes the request to the StaticResponseHandler to display a message.

"failureHandler": {
  "type": "Chain",
  "config": {
    "filters": [
      {
        "type": "ScriptableFilter",
        "config": {
          "type": "application/x-groovy",
          "source": [
            "if (contexts.policyDecision.advices['MyCustomAdvice'] != null) {",
            "  return handleCustomAdvice(context, request)",
            "} else {",
            "  return next.handle(context, request)",
            "}"
          ]
        }
      }
    ],
    "handler": {
      "type": "StaticResponseHandler",
      "config": {
        "status": 403,
        "headers": {
          "Content-Type": [ "text/plain" ]
        },
        "entity": "Restricted area. You do not have sufficient privileges."
      }
    }
  }
}

Provide an inline handler configuration object, or the name of a handler object declared in the heap. See also Handlers.

Default: HTTP 403 Forbidden, the request stops being executed.

"resourceUriProvider": ResourceUriProvider reference, optional

Return the resource URL to include in policy decision requests to AM. Configure one of the following ResourceUriProviders inline or in the heap:

  • RequestResourceUriProvider

  • ScriptableResourceUriProvider

    Default: RequestResourceUriProvider

    RequestResourceUriProvider

    Return the resource URL to include in policy decision requests to AM by using the original URI of the request or the baseURI of the route.

    "resourceUriProvider": {
      "type": "RequestResourceUriProvider",
      "config": {
        "useOriginalUri": runtime expression<boolean>,
        "includeQueryParams": runtime expression<boolean>
      }
    }
    useOriginalUri: runtime expression<boolean>, optional

    In policy decision requests to AM, use the original URI of the request as the resource URL.

    • true: Use the original URI of the request as the resource URL when requesting policy decisions from AM.

    • false: Use the baseURI of the route as the resource URL when requesting policy decisions from AM.

    Default: false

    includeQueryParams: runtime expression<boolean>, optional

    Include query parameters in the resource URL when requesting policy decisions from AM:

    • true: Include query parameters in the resource URL. For example, use the following URL with a query parameter: http://openig.example.com:8080/login?demo=capture.

    • false: Exclude query parameters from the resource URL. For example, exclude the query parameter from the previous example: http://openig.example.com:8080/login.

      For AM policies that specify resource URLs without query parameters, use this option to reduce the amount of cached information.

Default: true

ScriptableResourceUriProvider

Use a script to return the resource URL to include in policy decision requests to AM. The result of the script must be a string that represents the resource to be used in the policy decision request sent to AM.

"resourceUriProvider": {
  "type": "ScriptableResourceUriProvider",
  "config": {
    "type": string,
    "file": expression,                     // Use either "file"
    "source": string or array of strings,   // or "source", but not both.
    "args": object,
    "clientHandler": Handler reference
  }
}

For information about these properties, see Scripts.

The following example script replaces existing query parameters with a single parameter:

"resourceUriProvider": {
  "type": "ScriptableResourceUriProvider",
  "config": {
    "type": "application/x-groovy",
    "source": [
      "request.uri.setQuery('fromIG=true')",
      "return request.uri.toASCIIString()"
    ]
  }
}

Example Policy Enforcement Using claimsSubject

This route is a variant of the route in Enforce AM Policy Decisions In the Same Domain. It enforces a policy decision from AM, using claimsSubject instead of ssoTokenSubject to identify the subject.

To use this route:

  1. Set up AM as described in Enforce AM Policy Decisions In the Same Domain.

  2. In AM, select the policy you created in the previous step, and add a new resource:

    • Resource Type : URL

    • Resource pattern : *://*:*/*

    • Resource value : http://app.example.com:8081/home/pep-claims

  3. In the same policy, add the following subject condition:

    • Any of

    • Type : OpenID Connect/JwtClaim

    • claimName : iss

    • claimValue : openam.example.com

  4. Set an environment variable for the IG agent password, and then restart IG:

    $ export AGENT_SECRET_ID='cGFzc3dvcmQ='

    The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded.

  5. Add the following route to serve static resources, such as .css, for the sample application:

    • Linux

    • Windows

    $HOME/.openig/routes/static-resources.json
    appdata\OpenIG\config\routes\static-resources.json
    {
      "name" : "sampleapp-resources",
      "baseURI" : "http://app.example.com:8081",
      "condition": "${matches(request.uri.path,'^/css')}",
      "handler": "ReverseProxyHandler"
    }
  6. Add the following route to IG:

    • Linux

    • Windows

    $HOME/.openig/routes/04-pep-claims.json
    appdata\OpenIG\config\routes\04-pep-claims.json
    {
      "name": "pep-claims",
      "baseURI": "http://app.example.com:8081",
      "condition": "${matches(request.uri.path, '^/home/pep-claims')}",
      "heap": [
        {
          "name": "SystemAndEnvSecretStore-1",
          "type": "SystemAndEnvSecretStore"
        },
        {
          "name": "AmService-1",
          "type": "AmService",
          "config": {
            "url": "http://openam.example.com:8088/openam",
            "agent": {
              "username": "ig_agent",
              "passwordSecretId": "agent.secret.id"
            },
            "secretsProvider": "SystemAndEnvSecretStore-1",
            "version": "7.1"
          }
        }
      ],
      "handler": {
        "type": "Chain",
        "config": {
          "filters": [
            {
              "name": "SingleSignOnFilter-1",
              "type": "SingleSignOnFilter",
              "config": {
                "amService": "AmService-1"
              }
            },
            {
              "name": "PolicyEnforcementFilter-1",
              "type": "PolicyEnforcementFilter",
              "config": {
                "application": "PEP-SSO",
                "claimsSubject": {
                  "sub": "${contexts.ssoToken.info.uid}",
                  "iss": "openam.example.com"
                },
                "amService": "AmService-1"
              }
            }
          ],
          "handler": "ReverseProxyHandler"
        }
      }
    }
  7. Go to http://openig.example.com:8080/home/pep-claims.

  8. Log in to AM as user demo, password Ch4ng31t.

    AM returns a policy decision that grants access to the sample application.