IG 2023.6

PolicyEnforcementFilter

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

For information about how IG enforces policy decisions from AM, refer to Policy enforcement.

Attributes and advices are stored in the policyDecision context. For information, refer to 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.

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, refer to WebSocket Notifications.

Usage

{
  "name": string,
  "type": "PolicyEnforcementFilter",
  "config": {
    "amService": AmService reference,
    "pepRealm": configuration expression<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,
    "authenticateResponseRequestHeader": configuration expression<string>,
    "useLegacyAdviceEncoding": configuration expression<boolean> //deprecated
  }
}

Properties

"amService": AmService reference, required

The AM instance to use for policy decisions.

"pepRealm": configuration expression<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.cookie name}, where cookie name is the AM session cookie name.

"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 AuthorizationCodeOAuth2ClientFilter filter before the PEP filter, and then use ${attributes.openid.id_token} as the expression value.

See also AuthorizationCodeOAuth2ClientFilter and Expressions.

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

A map of one or more data pairs with the format Map<String, Object>, where:

  • The key is the name of a claim

  • The value is a claim object, or a runtime expression that evaluates to a claims object

The following formats are allowed:

{
  "claimsSubject": {
    "string": "runtime expression<object>",
    ...
  }
}
{
  "claimsSubject": "runtime expression<map>"
}

The claim "sub" must be specified; other claims are optional.

In the following example, the property is a map whose first value is a runtime expression that evaluates to a JWT claim for the subject, and whose second value is a JWT claim for the subject:

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

In the following example, the property is a runtime expression that evaluates to a map with the format Map<String, Object>:

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

For an example that uses claimsSubject as a map, refer to 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 map of one or more data pairs with the format Map<String, Object>, where:

  • The key is the name of a field in the request environment or context, such as a request header

  • The value is the object to forward to AM with a policy decision request, or a runtime expression that evaluates to the object

The following formats are allowed:

{
  "claimsSubject": {
    "string": "runtime expression<object>",
    ...
  }
}
{
  "claimsSubject": "runtime expression<map>"
}

AM uses 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.

Forward any HTTP header or any value that the AM policy definition can use.

In the following example, the property is a map whose values are runtime expressions that evaluate to 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}"
  ]
}
"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; charset=UTF-8" ]
        },
        "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 a 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": configuration expression<boolean>,
    "includeQueryParams": configuration expression<boolean>
  }
}
useOriginalUri: configuration expression<boolean>, optional

A flag to use the original URI of the request as the resource URL in policy decision requests to AM.

  • 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: configuration expression<boolean>, optional

A flag to 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://ig.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://ig.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 a resource URL to include in policy decision requests to AM. The result of the script must be a string that represents the resource URL.

"resourceUriProvider": {
  "type": "ScriptableResourceUriProvider",
  "config": {
    "type": configuration expression<string>,
    "file": configuration expression<string>, // Use either "file"
    "source": [ string, ... ],                // 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()"
    ]
  }
}
authenticateResponseRequestHeader: configuration expression<string>, optional

A header to include in a request to manage the way IG handles policy advices from AM. The header name and value is case-insensitive. The header value can be set as follows:

  • HEADER: Return policy advices in a WWW-Authenticate header as base64-encoded JSON in a parameter called advices.

  • Any other value: Return policy advices as parameters in a redirect response (default).

For information about how the header is used in policy enforcement, refer to Deny requests with advices in a header.

Default: x-authenticate-response

useLegacyAdviceEncoding: configuration expression<boolean>, optional
The use of this property is deprecated and should be used only to support SDK in legacy installations. Refer to the Deprecated section of the Release Notes.

  • True: Do not encode advices

  • False: Encode advices with the encoder used by the AM version

Default: False

Examples

For examples of policy enforcement, refer to Policy enforcement.

More information

org.forgerock.openig.openam.PolicyEnforcementFilter

org.forgerock.openig.openam.PolicyDecisionContext

PolicyDecisionContext

AM’s Authorization guide

Copyright © 2010-2023 ForgeRock, all rights reserved.