GrantSwapJwtAssertionOAuth2ClientFilter

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.

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 requests or Resource owner password credentials grant 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.
Configure an AllowOnlyFilter in front of the GrantSwapJwtAssertionOAuth2ClientFilter to control access within a route.
Define restrictive Route 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 in front of the GrantSwapJwtAssertionOAuth2ClientFilter to validate requests.

Usage

{
  "name": string,
  "type": "GrantSwapJwtAssertionOAuth2ClientFilter",
  "config": {
    "clientId": configuration expression<string>,
    "scopes": [ runtime expression<string>, … ] or ResourceAccess reference,
    "assertion": {
      "issuer": runtime expression<string>,
      "subject": runtime expression<string>,
      "audience": runtime expression<string>,
      "expiryTime": runtime expression<duration>,
      "otherClaims": map<string, runtime expression<string>>
    },
    "secretsProvider": SecretsProvider reference,
    "signature": {
      "secretId": configuration expression<secret-id>,
      "includeKeyId": configuration expression<boolean>
    },
    "encryption": {
      "secretId": secret-id,
      "algorithm": configuration expression<string>,
      "method": configuration expression<enumeration>
    },
    "failureHandler": Handler reference
  }
}

Properties

clientId

"clientId": configuration expression<string>, optional

The OAuth 2.0 client ID to use for authentication.

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 configuration, such as a RequestFormResourceAccess or 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.

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

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

assertion

"assertion": 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, required: The JWT iss claim. Can’t be null.

"subject": string, required: The JWT sub claim. Can’t be null.

"audience": string, required: The JWT aud claim. Can’t be null.

"expiryTime": duration, required: The JWT exp claim. Can’t be zero or unlimited.

Default: 2 minutes

"otherClaims": map or map, optional

A map of additional JWT claims with the format Map<String, RuntimeExpression<String>>, where:

Key: Claim name
Value: Claim value

Use the following format:

{
  "otherClaims": {
    "string": "runtime expression<string>",
    ...
  }
}

The filter doesn’t check otherClaims in the JWT.

secretsProvider

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to query for passwords and cryptographic keys.

signature

"signature": _object, "signature" and/or "encryption" is required

A JWT signature to validate the authenticity of claims and data.

"secretId": configuration expression<secret-id>, required if signature is used: The secret ID of the key to sign the JWT. The secret ID must point to a CryptoKey.

"includeKeyId": configuration expression<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, "signature" and/or "encryption" is required

Configuration to encrypt the JWT.

This property takes precedence over the signature setting.

"secretId": secret-id, optional: The secret ID of the key used to encrypt the JWT. The value is mapped to key aliases in KeyStoreSecretStore.

This secret ID must point to a CryptoKey.

"algorithm": configuration expression<string>, required: The algorithm used to encrypt the JWT.

Learn about available algorithms in RFC 7518: "alg" (Algorithm) Header Parameter Values for JWE.

"method": configuration expression<enumeration>, required: The method used to encrypt the JWT.

Learn about available methods in RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE.

failureHandler

"failureHandler": Handler <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: PingGateway returns HTTP 500 Internal Server Error and stops processing the request.

Example

You can find an example that uses this filter in Secure the OAuth 2.0 access token endpoint.

More information

org.forgerock.openig.filter.oauth2.client.GrantSwapJwtAssertionOAuth2ClientFilter

PingGateway 2024.11