PingGateway 2024.11

PolicyEnforcementFilter

Requests and enforces policy decisions from AM. For more information, refer to PingGateway’s Policy enforcement and AM’s Authorization guide.

AM can deny access with advice in the policy decision response. The advice indicates how to authenticate the user for access to the resource. PingGateway stores attributes and advices in the policyDecision context. For information, refer to PolicyDecisionContext.

When you precede a PolicyEnforcementFilter in a Chain with a SingleSignOnFilter or CrossDomainSingleSignOnFilter, PingGateway reacts to AM advices in the policy decision:

  • AuthLevelConditionAdvice: Authenticate the user to reach the specified authentication level.

  • AuthSchemeConditionAdvice: Authenticate the user based on the details of the specified scheme.

  • AuthenticateToRealmConditionAdvice: Authenticate the user to the specified realm.

  • AuthenticateToServiceConditionAdvice: Authenticate the user with the specified authentication journey or chain. (AM has deprecated authentication chains.)

  • AuthenticateToTreeConditionAdvice: Authenticate the user with the specified authentication journey.

  • TransactionConditionAdvice: Perform additional actions to authenticate the user for one-time access to the protected resource.

To respond to advices from AM:

  • Use the PolicyEnforcementFilter in a Chain.

  • Add a SingleSignOnFilter or CrossDomainSingleSignOnFilter before the PolicyEnforcementFilter.

If you don’t precede it with an SSO filter, the PolicyEnforcementFilter ignores the advice. When AM returns advice, the PolicyEnforcementFilter denies access with HTTP 403 Forbidden by default.

If you can’t use a SingleSignOnFilter or CrossDomainSingleSignOnFilter before the PolicyEnforcementFilter, it’s still possible to enable PingGateway to respond to advices:

  • Write a script to respond to advice from AM.

    For details about the advice types AM returns, refer to Policy decision advice in the AM documentation.

  • Use a scriptable filter or handler in the "failureHandler" of the PolicyEnforcementFilter to trigger the script.

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 PingGateway 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, PingGateway receives a notification from AM when a policy decision is created, deleted, or updated.

You can find more information about setting up WebSocket notifications, using them to clear the policy cache, and including them in the server logs in 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": {
      "enabled": configuration expression<boolean>,
      "defaultTimeout": configuration expression<duration>,
      "executor": Executor service reference,
      "maximumSize": configuration expression<number>,
      "maximumTimeToCache": configuration expression<duration>,
      "onNotificationDisconnection": configuration expression<enumeration>
    },
    "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": AmService reference, required

The AM instance to use for policy decisions.

pepRealm

"pepRealm": configuration expression<string>, optional

The AM realm where the policy set is located.

Default: The realm declared for amService.

ssoTokenSubject

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

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

ssoTokenSubject can take the value of the session token from the following sources:

  • When the PolicyEnforcementFilter is preceded by a SingleSignOnFilter, ${contexts.ssoToken.value}.

  • When the PolicyEnforcementFilter is preceded by a CrossDomainSingleSignOnFilter, ${contexts.ssoToken.value} or ${contexts.cdsso.token}.

  • When the PolicyEnforcementFilter isn’t preceded by a SingleSignOnFilter or CrossDomainSingleSignOnFilter, ssoTokenSubject usually points to the token value.

    The token value can be in the request message, a header, or a cookie. For example, the ssoTokenSubject can point to a header value, such as ${request.headers.cookie name}, where cookie name is the AM session cookie name.

    Requests that return a policy decision with advices fail with an HTTP 403 and no advice handling.

jwtSubject

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

claimsSubject

"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}"

Learn more in the example of policy enforcement using claimsSubject.

cache

"cache": object, optional

Enable and configure caching of policy decisions from AM based on Caffeine.

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

{
  "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>
  }
}
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"
}

Default: Policy decisions aren’t cached.

"enabled": configuration expression<boolean>, optional

Enable or disable caching of policy decisions.

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 the policy decision remains valid, PingGateway 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, PingGateway 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 PingGateway receives no notifications for AM events. If the cache isn’t cleared it can become outdated and PingGateway 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 aren’t cached, but don’t update the cache with these requests.

    • When the notification service is reconnected:

      • Continue to use the existing cache.

      • Query AM for incoming requests that aren’t 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 don’t update the cache with these requests.

    • When the notification service is reconnected:

      • Query AM for all requests that aren’t 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 aren’t cached, but don’t update the cache with these requests.

    • When the notification service is reconnected:

      • Query AM for all requests that aren’t 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

application

"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

environment

"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 where a policy applies. For example, environment conditions can specify 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

"failureHandler": Handler reference, optional

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

In the following example, the failureHandler passes the request to a StaticResponseHandler to display a message:

"failureHandler": {
    "type": "StaticResponseHandler",
    "config": {
        "status": 403,
        "headers": {
            "Content-Type": [
                "text/plain; charset=UTF-8"
            ]
        },
        "entity": "Restricted area. You don't have sufficient privileges."
    }
}

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

resourceUriProvider

"resourceUriProvider": ResourceUriProvider reference, optional

Use one of the following providers to return a resource URL to include in policy decision requests to AM:

The PolicyEnforcementFilter uses the returned resource URL to identify the policy decision in the policy cache.

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

Default: RequestResourceUriProvider configured to use the request URI with all query parameters included.

Maximize the cache hit ratio by managing the returned resource URL in conjunction with AM policies:

Strip all query parameters from the returned resource URL

Consider the following AM policy that matches requests on the specified path. The policy ignores query parameters:

https://ig.example.com:8443/app

The following requests match the path but have additional query parameters:

https://ig.example.com:8443/app?day=monday
https://ig.example.com:8443/app?day=monday&place=london
https://ig.example.com:8443/app?day=monday&place=london&building=x

When includeQueryParams in RequestResourceUriProvider is true, the ResourceUriProvider includes all query parameters in requests for policy decisions. The PolicyEnforcementFilter requests a policy desicion for the first request /app?day=monday and caches the descision. The second request app?day=monday&place=london doesn’t match the cached decision, so the PolicyEnforcementFilter requests another policy decision and adds it to the cache. Similarly for the third request.

When includeQueryParams in RequestResourceUriProvider is false, the ResourceUriProvider strips all query parameters from the requests. The PolicyEnforcementFilter requests a policy decision for the first request without query parameters and caches the policy desicion. The following two requests without query parameters match the cached decision and PingGateway uses the cached decision without consulting AM.

Include only specified query parameters in the returned resource URL

Consider a similar example where an AM policy matches requests on the specified path and having a specified query parameter:

https://ig.example.com:8443/app?day=monday

The following requests match the path and query parameter, but two of them have additional query parameters:

https://ig.example.com:8443/app?day=monday
https://ig.example.com:8443/app?day=monday&place=london
https://ig.example.com:8443/app?day=monday&place=london&building=x

Because the policy requires a query parameter, you can’t use RequestResourceUriProvider to strip all query parameters from the requests.

Instead, use a ScriptableResourceUriProvider to include the ?day=monday query parameter but strip all other query parameters.

Query order is important. The following queries are semantically the same but don’t match: ?day=monday&place=london and ?place=london&day=monday. 
"resourceUriProvider": {
  "type": "ScriptableResourceUriProvider",
  "config": {
    "type": "application/x-groovy",
    "source": [
      "// Define a list of parameters to keep",
      "def keepOnly = { [ 'place', 'day' ].contains(it.key) }",
      "// Build a new URI based on the original request URI",
      "return new MutableUri(request.uri).with { uri ->",
      "  // Build a filtered and normalized query string",
      "  uri.rawQuery = new Form().with { form ->",
      "    // Keep only the wanted parameters and sort by name",
      "    form.addAll(request.queryParams.findAll(keepOnly).sort())",
      "    return form.toQueryString()",
      "  }",
      "  // Return the full modified URI",
      "  return uri.toASCIIString()",
      "}"
    ]
  }
}

authenticateResponseRequestHeader

authenticateResponseRequestHeader: configuration expression<string>, optional

A header to include in a request to manage the way PingGateway 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).

Learn more in the example showing how to deny requests with advice in a header.

Default: x-authenticate-response

useLegacyAdviceEncoding (deprecated)

useLegacyAdviceEncoding: configuration expression<boolean>, optional

This property is deprecated and should be used only to support SDK in legacy installations. Learn more in the Deprecated section of the Release Notes.

  • true: Don’t encode advices.

  • false: Encode advices with the encoder used by the AM version.

Default: false

Examples

You can find examples of policy enforcement in Policy enforcement.

More information

org.forgerock.openig.openam.PolicyEnforcementFilter

org.forgerock.openig.openam.PolicyDecisionContext

PolicyDecisionContext

AM’s Authorization guide