OAuth2ResourceServerFilter

Validates a request containing an OAuth 2.0 access token. The filter expects an OAuth 2.0 token from the HTTP Authorization header of the request, such as the following example header, where the OAuth 2.0 access token is 1fc…ec9:

Authorization: Bearer 1fc...ec9

The filter performs the following tasks:

Extracts the access token from the request header.
Uses the configured access token resolver to resolve the access token against an Authorization Server, and validate the token claims.
Checks that the token has the scopes required by the filter configuration.
Injects the access token info into the OAuth2Context.

The following errors can occur during access token validation:

Error Response from the filter to the user agent

Error	Response from the filter to the user agent
Combination of the filter configuration and access token result in an invalid request to the Authorization Server.	`HTTP 400 Bad Request`
There is no access token in the request header.	`HTTP 401 Unauthorized WWW-Authenticate: Bearer realm="PingGateway"`
The access token isn’t valid, for example, because it has expired.	`HTTP 401 Unauthorized`
The access token doesn’t have all of the scopes required in the OAuth2ResourceServerFilter configuration.	`HTTP 403 Forbidden`

Combination of the filter configuration and access token result in an invalid request to the Authorization Server.

HTTP 400 Bad Request

There is no access token in the request header.

HTTP 401 Unauthorized WWW-Authenticate: Bearer realm="PingGateway"

The access token isn’t valid, for example, because it has expired.

HTTP 401 Unauthorized

The access token doesn’t have all of the scopes required in the OAuth2ResourceServerFilter configuration.

HTTP 403 Forbidden

Usage

{
  "name": string,
  "type": "OAuth2ResourceServerFilter",
  "config": {
    "accessTokenResolver": AccessTokenResolver reference,
    "cache": {
      "enabled": configuration expression<boolean>,
      "defaultTimeout": configuration expression<duration>,
      "maxTimeout": configuration expression<duration>,
      "amService": AmService reference,
      "onNotificationDisconnection": configuration expression<enumeration>
    },
    "executor": Executor service reference,
    "requireHttps": configuration expression<boolean>,
    "realm": configuration expression<string>,
    "scopes": [ runtime expression<string>, … ] or ScriptableResourceAccess reference
  }
}

An alternative value for type is OAuth2RSFilter.

Properties

accessTokenResolver

"accessTokenResolver": AccessTokenResolver reference, required

Resolves an access token against an Authorization Server. Configure one of the following access token resolvers:

To decorate an AccessTokenResolver, add the decoration at the accessTokenResolver level. The following example uses the default timer decorator to record the time that a TokenIntrospectionAccessTokenResolver takes to process a request:

{
  "accessTokenResolver": {
    "type": "TokenIntrospectionAccessTokenResolver",
    "config": {
      ...
    },
  "timer": true
  }
}

cache

"cache": object, optional

Configuration of caching for OAuth 2.0 access tokens. By default, access tokens aren’t cached. For an alternative way to cache OAuth 2.0 access tokens, configure a CacheAccessTokenResolver.

When an access token is cached, PingGateway can reuse the token information without repeatedly asking the Authorization Server to verify the access token. When caching is disabled, PingGateway must ask the Authorization Server to verify the access token for each request.

When an access_token is revoked on AM, the CacheAccessTokenResolver can delete the token from the cache when both of the following conditions are true:

The notification property of AmService is enabled.
The delegate AccessTokenResolver provides the token metadata required to update the cache.

When a refresh_token is revoked on AM, all associated access tokens are automatically and immediately revoked.

enabled: configuration expression<boolean>, optional: Enable or disable caching.

Default: false

defaultTimeout: configuration expression<duration>, optional

The duration for which to cache an OAuth 2.0 access token if it doesn’t provide a valid expiry value.

If an access token provides an expiry value that falls before the current time plus the maxTimeout, PingGateway uses the token expiry value.

The following example caches access tokens for these times:

One hour, if the access token doesn’t provide a valid expiry value.
The duration specified by the token expiry value, when the token expiry value is shorter than one day.
One day, when the token expiry value is longer than one day.

"cache": {
  "enabled": true,
  "defaultTimeout": "1 hour",
  "maxTimeout": "1 day"
}

Default: 1 minute

maxTimeout: configuration expression<duration>, optional: The maximum duration for which to cache OAuth 2.0 access tokens.

If an access token provides an expiry value that falls after the current time plus the maxTimeout, PingGateway uses the maxTimeout.

The duration cannot be zero or unlimited.

"amService": AmService reference, optional: The AmService to use for the WebSocket notification service. To evict revoked access tokens from the cache, enable the notifications property of AmService.

onNotificationDisconnection: configuration expression<enumeration>, optional

An amService must be configured for this property to have effect.

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 and 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 and 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 and 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

executor

"executor": Executor service reference, optional

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

Default: ScheduledExecutorService

requireHttps

"requireHttps": configuration expression<boolean>, optional

Whether to require that original target URI of the request uses the HTTPS scheme.

If the received request doesn’t use HTTPS, it is rejected.

Default: true

realm

"realm": configuration expression<string>, optional

The HTTP authentication realm PingGateway includes in the WWW-Authenticate response header field when returning an HTTP 401 Unauthorized status to a user-agent that needs to authenticate.

Default: OpenIG

scopes

"scopes": array of runtime expression<strings> or ResourceAccess <reference>, required

A list of one or more scopes required by the OAuth 2.0 access token. Provide the scopes as strings or through a ResourceAccess such as a ScriptableResourceAccess:

Array of runtime expression<strings>, required if a ResourceAccess isn’t used

A string, array of strings, runtime expression string, or array of runtime expression strings to represent one or more scopes.

ScriptableResourceAccess <reference>

A script that evaluates each request dynamically and returns the scopes the request needs to access the protected resource. The script must return a Set<String>.

Learn about the properties of ScriptableResourceAccess in Scripts.

{
  "name": string,
  "type": "ScriptableResourceAccess",
  "config": {
    "type": configuration expression<string>,
    "file": configuration expression<string>, // Use either "file"
    "source": [ string, ... ],                // or "source", but not both.
    "args": object,
    "clientHandler": Handler reference
  }
}

Default: Empty