--- title: GrantSwapJwtAssertionOAuth2ClientFilter description: Transforms requests for OAuth 2.0 access tokens into secure JWT bearer grant type requests. Propagates transformed requests to PingOne Advanced Identity Cloud or AM to obtain an access token. component: pinggateway version: 2026 page_id: pinggateway:reference:GrantSwapJwtAssertionOAuth2ClientFilter canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/GrantSwapJwtAssertionOAuth2ClientFilter.html revdate: 2026-01-15 section_ids: GrantSwapJwtAssertionOAuth2ClientFilter-usage: Usage GrantSwapJwtAssertionOAuth2ClientFilter-properties: Properties GrantSwapJwtAssertionOAuth2ClientFilter-clientId: clientId GrantSwapJwtAssertionOAuth2ClientFilter-scopes: scopes GrantSwapJwtAssertionOAuth2ClientFilter-assertion: assertion GrantSwapJwtAssertionOAuth2ClientFilter-secretsProvider: secretsProvider GrantSwapJwtAssertionOAuth2ClientFilter-signature: signature GrantSwapJwtAssertionOAuth2ClientFilter-encryption: encryption GrantSwapJwtAssertionOAuth2ClientFilter-failureHandler: failureHandler 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/8.1/am-oauth2/oauth2-jwt-bearer-grant.html) requests. Propagates transformed requests to PingOne Advanced Identity Cloud or AM to obtain an access token. Use this filter with PingOne Advanced Identity Cloud or AM to increase the security of less-secure grant-type requests, such as [Client credentials grant](https://docs.pingidentity.com/pingam/8.1/am-oauth2/oauth2-client-cred-grant.html) requests or [Resource owner password credentials grant](https://docs.pingidentity.com/pingam/8.1/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 PingGateway on a trusted network. - Use mutual TLS (mTLS) and X.509 certificates for authentication between clients and PingGateway. 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. | ## Usage ```none { "name": string, "type": "GrantSwapJwtAssertionOAuth2ClientFilter", "config": { "clientId": configuration expression, "scopes": [ runtime expression, …​ ] or ResourceAccess reference, "assertion": { "issuer": runtime expression, "subject": runtime expression, "audience": runtime expression, "expiryTime": runtime expression, "otherClaims": map> }, "secretsProvider": SecretsProvider reference, "signature": { "secretId": configuration expression, "includeKeyId": configuration expression }, "encryption": { "secretId": secret-id, "algorithm": configuration expression, "method": configuration expression }, "failureHandler": Handler reference } } ``` ## Properties ### clientId `"clientId"`: *configuration expression<[string](preface.html#definition-string)>, optional* The OAuth 2.0 client ID to use for authentication. ### 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 configuration, 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 string, or array of runtime expression strings 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: ```console $ curl --request POST 'https://am.example.com:8888/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`. 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 ### assertion `"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`. * `"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: ```none { "otherClaims": { "string": "runtime expression", ... } } ``` The filter doesn't check `otherClaims` in the JWT. ### secretsProvider `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), required* The [SecretsProvider](SecretsProvider.html) to query for passwords and cryptographic keys. ### signature `"signature"`: \_[object](preface.html#definition-object), "signature" and/or "encryption" is required A JWT signature to validate the authenticity of claims and data. * `"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` ### encryption `"encryption"`: *[object](preface.html#definition-object), "signature" and/or "encryption" is required* Configuration to encrypt the JWT. This property takes precedence over the [signature](#GrantSwapJwtAssertionOAuth2ClientFilter-signature) setting. * `"secretId"`: *[secret-id](preface.html#definition-secretid), optional* The secret ID of the key used to encrypt the JWT. The value is mapped to key `aliases` in [KeyStoreSecretStore](KeyStoreSecretStore.html). This secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types). - `"algorithm"`: *configuration expression<[string](preface.html#definition-string)>, required* The algorithm used to encrypt the JWT. Learn about available algorithms in [RFC 7518: "alg" (Algorithm) Header Parameter Values for JWE](https://www.rfc-editor.org/rfc/rfc7518#section-4.1). * `"method"`: *configuration expression<[enumeration](preface.html#definition-enumeration)>, required* The method used to encrypt the JWT. Learn about available methods in [RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE](https://www.rfc-editor.org/rfc/rfc7518#section-5.1). ### failureHandler `"failureHandler"`: *Handler <[reference](preface.html#definition-reference)>, optional* [Handler](Handlers.html) to manage a failed request. Provide an inline handler configuration object or the name of a handler object declared in the heap. Default: PingGateway returns HTTP 500 Internal Server Error and stops processing the request. ## Example You can find an example that uses this filter in [Securing the OAuth 2.0 access token endpoint with PingOne Advanced Identity Cloud](../aic/grant-swap.html). ## More information [org.forgerock.openig.filter.oauth2.client.GrantSwapJwtAssertionOAuth2ClientFilter](../_attachments/apidocs/org/forgerock/openig/filter/oauth2/client/GrantSwapJwtAssertionOAuth2ClientFilter.html)