--- title: OAuth2ResourceServerFilter description: 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: component: pinggateway version: 2026 page_id: pinggateway:reference:OAuth2ResourceServerFilter canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/OAuth2ResourceServerFilter.html revdate: 2025-06-02T18:01:47Z section_ids: OAuth2ResourceServerFilter-usage: Usage OAuth2ResourceServerFilter-properties: Properties OAuth2ResourceServerFilter-accessTokenResolver: accessTokenResolver OAuth2ResourceServerFilter-cache: cache OAuth2ResourceServerFilter-executor: executor OAuth2ResourceServerFilter-requireHttps: requireHttps OAuth2ResourceServerFilter-realm: realm OAuth2ResourceServerFilter-scopes: scopes OAuth2ResourceServerFilter-example: Examples OAuth2ResourceServerFilter-moreinfo: More information --- # 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`: ```http 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](OAuth2Context.html). The following errors can occur during access token validation: | 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` | | The access token isn't valid, for example, because it has expired. | | | The access token doesn't have all the scopes required in the OAuth2ResourceServerFilter configuration. | `HTTP 403 Forbidden` | ## Usage ```none { "name": string, "type": "OAuth2ResourceServerFilter", "config": { "accessTokenResolver": AccessTokenResolver reference, "cache": { "enabled": configuration expression, "defaultTimeout": configuration expression, "maxTimeout": configuration expression, "amService": AmService reference, "onNotificationDisconnection": configuration expression }, "executor": Executor service reference, "requireHttps": configuration expression, "realm": configuration expression, "scopes": [ runtime expression, …​ ] or ScriptableResourceAccess reference } } ``` An alternative value for type is OAuth2RSFilter. ## Properties ### accessTokenResolver `"accessTokenResolver"`: *AccessTokenResolver [reference](preface.html#definition-reference), required* Resolves an access token against an Authorization Server. Configure one of the following access token resolvers: * [TokenIntrospectionAccessTokenResolver](TokenIntrospectionAccessTokenResolver.html) * [StatelessAccessTokenResolver](StatelessAccessTokenResolver.html) * [ConfirmationKeyVerifierAccessTokenResolver](ConfirmationKeyVerifierAccessTokenResolver.html) * [ScriptableAccessTokenResolver](ScriptableAccessTokenResolver.html) 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: ```none { "accessTokenResolver": { "type": "TokenIntrospectionAccessTokenResolver", "config": { ... }, "timer": true } } ``` ### cache `"cache"`: *[object](preface.html#definition-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](CacheAccessTokenResolver.html). 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](preface.html#definition-boolean)>, optional* Enable or disable caching. Default: `false` - `defaultTimeout`: *configuration expression<[duration](preface.html#definition-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. ```none "cache": { "enabled": true, "defaultTimeout": "1 hour", "maxTimeout": "1 day" } ``` Default: `1 minute` * `maxTimeout`: *configuration expression<[duration](preface.html#definition-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](preface.html#definition-reference), optional* The [AmService](AmService.html) 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](preface.html#definition-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](preface.html#definition-reference), optional* An [executor servic](ScheduledExecutorService.html)e to schedule the execution of tasks, such as the eviction of entries in the access token cache. Default: `ScheduledExecutorService` ### requireHttps `"requireHttps"`: *configuration expression<[boolean](preface.html#definition-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](preface.html#definition-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: No realm is specified. ### scopes `"scopes"`: *array of runtime expression<[strings](preface.html#definition-string)> or ResourceAccess <[reference](preface.html#definition-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](preface.html#definition-string)>, required if a [ResourceAccess](../_attachments/apidocs/org/forgerock/http/oauth2/ResourceAccess.html) 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](preface.html#definition-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`. Learn about the properties of ScriptableResourceAccess in [PingGateway scripts](Scripts.html). ```none { "name": string, "type": "ScriptableResourceAccess", "config": { "type": configuration expression, "file": configuration expression, // Use either "file" "source": [ string, ... ], // or "source", but not both. "args": object, "clientHandler": Handler reference } } ``` Default: Empty ## Examples Learn more in [PingGateway as an OAuth 2.0 resource server](../gateway-guide/oauth2.html#about-oauth2-rs). ## More information [org.forgerock.openig.filter.oauth2.OAuth2ResourceServerFilterHeaplet](../_attachments/apidocs/org/forgerock/openig/filter/oauth2/OAuth2ResourceServerFilterHeaplet.html) [org.forgerock.http.oauth2.OAuth2Context](../_attachments/apidocs/org/forgerock/http/oauth2/OAuth2Context.html) [org.forgerock.http.oauth2.AccessTokenInfo](../_attachments/apidocs/org/forgerock/http/oauth2/AccessTokenInfo.html) [OAuth2Context](OAuth2Context.html) [ConfirmationKeyVerifierAccessTokenResolver](ConfirmationKeyVerifierAccessTokenResolver.html) [TokenIntrospectionAccessTokenResolver](TokenIntrospectionAccessTokenResolver.html) [StatelessAccessTokenResolver](StatelessAccessTokenResolver.html) [ScriptableAccessTokenResolver](ScriptableAccessTokenResolver.html) [The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749) [The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://www.rfc-editor.org/rfc/rfc6750)