PingGateway 2024.9

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.

For an example that uses GrantSwapJwtAssertionOAuth2ClientFilter, refer to Secure the OAuth 2.0 access token endpoint.

Usage

{
  "name": string,
  "type": "GrantSwapJwtAssertionOAuth2ClientFilter",
  "config": {
    "clientId": configuration expression<string>,
    "scopes": [ runtime expression<string>, ... ] or ResourceAccess reference,
    "assertion": object,
    "secretsProvider": SecretsProvider reference,
    "signature": object,
    "encryption": object,
    "failureHandler": Handler reference
  }
}

Properties

"clientId": configuration expression<string>, optional

The OAuth 2.0 client ID to use for authentication.

"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 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<string> 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:

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

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

For information about the properties of ScriptableResourceAccess, refer to 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": 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.

{
  "assertion": {
    "issuer": runtime expression<string>,
    "subject": runtime expression<string>,
    "audience": runtime expression<string>,
    "expiryTime": runtime expression<duration>,
    "otherClaims": map<string, runtime expression<string>>
  }
}
"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 reference, required

The SecretsProvider to query for passwords and cryptographic keys.

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

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

{
  "signature": {
    "secretId": configuration expression<secret-id>,
    "includeKeyId": configuration expression<boolean>
  }
}
"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": object, "signature" and/or "encryption" is required

Configuration to encrypt the JWT.

This property take precedence over GrantSwapJwtAssertionOAuth2ClientFilter.signature.

{
  "encryption": {
    "secretId": secret-id,
    "algorithm": configuration expression<string>,
    "method": configuration expression<enumeration>
  }
}
"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.

For information about available algorithms, refer to RFC 7518: "alg" (Algorithm) Header Parameter Values for JWE.

"method": configuration expression<enumeration>, required

The method used to encrypt the JWT.

For information about available methods, refer to RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE.

"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: 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.

More information

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