--- title: GrantSwapJwtAssertionOAuth2ClientFilter description: Transforms requests for OAuth 2.0 access tokens into secure JWT bearer grant type requests. Propagates transformed requests to Identity Cloud or AM to obtain an access token. component: pinggateway version: 2023.11 page_id: pinggateway:reference:GrantSwapJwtAssertionOAuth2ClientFilter canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/GrantSwapJwtAssertionOAuth2ClientFilter.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2025-08-13T11:08:28Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/GrantSwapJwtAssertionOAuth2ClientFilter.html section_ids: GrantSwapJwtAssertionOAuth2ClientFilter-usage: Usage GrantSwapJwtAssertionOAuth2ClientFilter-properties: Properties GrantSwapJwtAssertionOAuth2ClientFilter-example: Example GrantSwapJwtAssertionOAuth2ClientFilter-moreinformation: More information --- # GrantSwapJwtAssertionOAuth2ClientFilter Transforms requests for OAuth 2.0 access tokens into secure [JWT bearer grant type](https://docs.pingidentity.com/pingam/7.4/am-oauth2/oauth2-jwt-bearer-grant.html) requests. Propagates transformed requests to Identity Cloud or AM to obtain an access token. Use this filter with Identity Cloud or AM to increase the security of less-secure grant-type requests, such as [Client credentials grant](https://docs.pingidentity.com/pingam/7.4/am-oauth2/oauth2-client-cred-grant.html) requests or [Resource owner password credentials grant](https://docs.pingidentity.com/pingam/7.4/am-oauth2/oauth2-ropc-grant.html) requests. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | The GrantSwapJwtAssertionOAuth2ClientFilter obtains access tokens from the `/oauth2/access_token` endpoint. To prevent unwanted or malicious access to the endpoint, make sure only a well-defined set of clients can use this filter.Consider the following options to secure access to the GrantSwapJwtAssertionOAuth2ClientFilter:- Deploy IG on a trusted network. - Use mutual TLS (mTLS) and X.509 certificates for authentication between clients and IG. For more information, refer to [OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens](https://tools.ietf.org/html/draft-ietf-oauth-mtls). - Configure an [AllowOnlyFilter](AllowOnlyFilter.html) in front of the GrantSwapJwtAssertionOAuth2ClientFilter to control access within a route. - Define restrictive [Route](Route.html) conditions to allow access only for expected grant-type requests. For example, define a route condition that requires a specific client ID, grant-type, or scope. - Configure a [ScriptableFilter](ScriptableFilter.html) in front of the GrantSwapJwtAssertionOAuth2ClientFilter to validate requests. | For an example that uses GrantSwapJwtAssertionOAuth2ClientFilter, refer to [Secure the OAuth 2.0 access token endpoint](../identity-cloud-guide/grant-swap.html). ## Usage ```json { "name": string, "type": "GrantSwapJwtAssertionOAuth2ClientFilter", "config": { "clientId": configuration expression, "scopes": [ runtime expression, ... ] or ResourceAccess reference, "assertion": object, "secretsProvider": SecretsProvider reference, "signature": object, "encryption": object, "failureHandler": Handler reference } } ``` ## Properties * `"clientId"`: *configuration expression<[string](preface.html#definition-string)>, optional* The OAuth 2.0 client ID to use for authentication. * `"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 RequestFormResourceAccess or 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\, or array of runtime expression\ to represent one or more scopes. * RequestFormResourceAccess <[reference](preface.html#definition-reference)> A ResourceAccess that transfers scopes from the inbound request to a JWT bearer grant-type request. In the following example request, the ResourceAccess extracts scopes from the request: ```curl $ POST 'http://openig.example.com:8081/am/oauth2/access_token' header 'Content-Type: application/x-www-form-urlencoded' urlencoded form-data 'grant_type=client_credentials' urlencoded form-data 'client_id=service-account' urlencoded form-data 'scope=fr:idm:*' ``` Default: Empty - ScriptableResourceAccess <[reference](preface.html#definition-reference)> A script that evaluates each request dynamically and returns the scopes that the request needs to access the protected resource. The script must return a `Set`. For information about the properties of ScriptableResourceAccess, refer to [Scripts](Scripts.html). ```json { "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 * `"assertion"`: *[object](preface.html#definition-object), required* The JWT claims. The GrantSwapJwtAssertionOAuth2ClientFilter checks that all mandatory fields are present and sets the JWT expiry. The filter doesn't check the fields in `otherClaims`. ```json { "assertion": { "issuer": runtime expression, "subject": runtime expression, "audience": runtime expression, "expiryTime": runtime expression, "otherClaims": map> } } ``` * `"issuer"`: *[string](preface.html#definition-string), required* The JWT `iss` claim. Can't be null. * `"subject"`: *[string](preface.html#definition-string), required* The JWT `sub` claim. Can't be null. * `"audience"`: *[string](preface.html#definition-string), required* The JWT `aud` claim. Can't be null. * `"expiryTime"`: *[duration](preface.html#definition-duration), required* The JWT `exp` claim. Can't be `zero` or `unlimited`. Default: 2 minutes * `"otherClaims"`: *[map](preface.html#definition-map) or map, optional* A map of additional JWT claims with the format `Map>`, where: * Key: Claim name * Value: Claim value Use the following format: ```json { "otherClaims": { "string": "runtime expression", ... } } ``` The filter doesn't check `otherClaims` in the JWT. * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), required* The [SecretsProvider](secrets.html#SecretsProvider) to use to resolve queried secrets, such as passwords and cryptographic keys. Provide either the name of a SecretsProvider object defined in the heap or specify a SecretsProvider object inline. * `"signature"`: *[object](preface.html#definition-object), optional* A JWT signature to validate the authenticity of claims and data. ```json { "signature": { "secretId": configuration expression, "includeKeyId": configuration expression } } ``` * `"secretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required if `signature` is used* The secret ID of the key to sign the JWT. The secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types). * `"includeKeyId"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* A flag to include the ID of the signature key in the JWT header: * `true`: Include the flag * `false`: Don't include the flag Default: `true` * `"failureHandler"`: *Handler <[reference](preface.html#definition-reference)>, optional* Handler to manage a failed request. Provide an inline handler configuration object or the name of a handler object declared in the heap. Default: `500 Internal Server Error`, the request stops being executed. ## Example For an example that uses GrantSwapJwtAssertionOAuth2ClientFilter, refer to [Secure the OAuth 2.0 access token endpoint](../identity-cloud-guide/grant-swap.html). ## More information [org.forgerock.openig.filter.oauth2.client.GrantSwapJwtAssertionOAuth2ClientFilter](../_attachments/apidocs/org/forgerock/openig/filter/oauth2/client/GrantSwapJwtAssertionOAuth2ClientFilter.html)