Identity Gateway 2024.3

ClientCredentialsOAuth2ClientFilter

Authenticates OAuth 2.0 clients by using the client’s OAuth 2.0 credentials to obtain an access token from an Authorization Server, and injecting the access token into the inbound request as a Bearer Authorization header. The access token is valid for the configured scopes.

The ClientCredentialsOAuth2ClientFilter obtains the client’s access token by using the client_credentials grant type. Client authentication is provided by the endpointHandler property, which uses a client authentication filter, such as ClientSecretBasicAuthenticationFilter. The filter refreshes the access token as required.

Use the ClientCredentialsOAuth2ClientFilter in a service-to-service context, where services need to access resources protected by OAuth 2.0.

Usage

{
  "name": string,
  "type": "ClientCredentialsOAuth2ClientFilter",
  "config": {
    "secretsProvider": SecretsProvider reference,
    "tokenEndpoint": configuration expression<url>,
    "scopes": [ configuration expression<string>, ... ],
    "endpointHandler": Handler reference,
    "clientId": configuration expression<sting>, //deprecated
    "clientSecretId": configuration expression<secret-id>, //deprecated
    "handler": Handler reference //deprecated
  }
}

Properties

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to query for passwords and cryptographic keys.

"tokenEndpoint": configuration expression<url>, required

The URL to the Authorization Server’s OAuth 2.0 token endpoint.

"scopes": array of configuration expression<strings>, optional

Array of scope strings to request from the Authorization Server.

Default: Empty, request no scopes.

"endpointHandler": Handler reference, optional

The Handler to exchange tokens on the authorization endpoint.

Configure this property as a Chain, using one of the following client authentication filters:

{
  "name": "myHandler",
  "type": "Chain",
  "config": {
    "handler": "ForgeRockClientHandler",
    "filters": [
      {
        "type": "ClientSecretBasicAuthenticationFilter",
        "config": {
          "clientId": "myConfidentialClient",
          "clientSecretId": "my.client.secret.id",
          "secretsProvider" : "mySystemAndEnvSecretStore",
        }
      }
    ]
  }
}

Default: ForgeRockClientHandler

"clientId": configuration expression<string>, required
This property is deprecated. Use endpointHandler instead. For more information, refer to the Deprecated section of the Release Notes.

The ID of the OAuth 2.0 client registered with the Authorization Server.

If you use the deprecated properties, provide clientId, clientSecretId to obtain the client secret, which authenticates using the client_secret_basic method.

"clientSecretId": configuration expression<secret-id>, required
This property is deprecated. Use endpointHandler instead. For more information, refer to the Deprecated section of the Release Notes.

The ID to use when querying the secretsProvider for the client secret.

This secret ID must point to a GenericSecret.

"handler": Handler reference or inline Handler declaration, optional
This property is deprecated. Use endpointHandler instead. For more information, refer to the Deprecated section of the Release Notes.

The Handler to use to access the Authorization Server’s OAuth 2.0 token endpoint. Provide either the name of a handler object defined in the heap or specify a handler object inline.

Default: ClientHandler

Examples

For an example, refer to Using OAuth 2.0 client credentials.

More information

org.forgerock.openig.filter.oauth2.client.ClientCredentialsOAuth2ClientFilterHeaplet

org.forgerock.openig.filter.oauth2.OAuth2ResourceServerFilterHeaplet

OAuth2ResourceServerFilter

The OAuth 2.0 Authorization Framework

The OAuth 2.0 Authorization Framework: Bearer Token Usage