Package org.forgerock.openig.filter.oauth2.client

Class GrantSwapJwtAssertionOAuth2ClientFilter

java.lang.Object

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

All Implemented Interfaces:

Filter

public class GrantSwapJwtAssertionOAuth2ClientFilter
extends Object
implements Filter

Creates and initializes a Filter supporting the transformation of a request - e.g. OAuth2 client-credentials or resource-owner - to a secure JWT-assertion profile request. The intent is that this filter will be configured as part of a route proxying traffic to an authorization service's /access_token endpoint.

The filter is configured with mandatory claims to include in the JWT, which may be derived from the inbound request or other available data. Optional other claims can be configured via 'otherClaims'. The JWT should be secured appropriately with signing or encryption. The resulting JWT is validated to ensure all mandatory fields are present after expression-evaluation and the 'expiryTime' is set. The 'otherClaims' are not validated.

The GrantSwapJwtAssertionOAuth2ClientFilter has the following configuration:

 {
      "type": "GrantSwapJwtAssertionOAuth2ClientFilter",
      "config": {
        "failureHandler"  : Handler                        [OPTIONAL - Handler called upon error - defaults to
                                                                       400 response with error details. (1)]
        "clientId"        : Runtime expression<String>     [OPTIONAL - OAuth2 client identifier. (2)]
        "scopes"          : [ Runtime expression<String> ] [OPTIONAL - List of requested OAuth2 scopes. (3)]
        "assertion"       : {                              [REQUIRED - JWT values.]
          "issuer"        :   Runtime expression<string>      [REQUIRED - The JWT issuer ('iss').]
          "subject"       :   Runtime expression<string>      [REQUIRED - The JWT subject ('sub').]
          "audience"      :   Runtime expression<string>      [REQUIRED - The JWT audience ('aud').]
          "expiryTime"    :   Runtime expression<duration>    [REQUIRED - The JWT expiry time ('exp'). Must be a
                                                                          positive value and cannot be unlimited.
                                                                          Defaults to 2 minutes.]
          "otherClaims"   :   Runtime expression<Map>         [OPTIONAL - Map of any additional claims to include in
                                                                          the JWT, mapping claim name to value.
                                                                          Default is empty - no additional claims.]
        }

        JWT security configuration is as per the JwtBuilderFilter (4)
      }
 }
 
 

1. Routes containing a GrantSwapJwtAssertionOAuth2ClientFilter are intended to front an authorization service /access_token endpoint. So, by default, failures are treated as if this route is itself an /access_token endpoint, returning a response with status Status.BAD_REQUEST, containing details of the 'error' and 'error_description' as per the RFC 6749 OAuth2 specification.
2. 'clientId' is not needed when the route handler (the access_token endpoint handler) is protected by a client authentication filter. It must be configured when used with ForgeRock Identity Cloud service accounts.
3. 'scopes' may be configured as a set of expressions, or may be extracted from the inbound request through configuration of a RequestFormResourceAccess in the heap
4. JWT signature configuration should be as per the JwtBuilderFilter. See signature, and further examples documented there.

Important note on security:

The GrantSwapJwtAssertionOAuth2ClientFilter transforms an access_token request into a JWT Bearer access_token request in order to increase security of the request proxied to the Authorization Server. A route containing this filter must therefore be robustly protected to prevent unintended (or malicious) client access. The route may be protected in a number of ways, such as:

• Deployment in IG only on a trusted network (within the trust boundary)
• Use of mTLS between the client and IG to ensure mutual authentication
• Inclusion of an AllowOnlyFilter in the route prior to this filter to enforce client access restrictions (e.g. on IP address)
• Restrictions in place in the route condition to reduce route exposure to only expected requests - e.g. enforce clientId, grant-type and/ or scope
• Specialized request validation using a ScriptableFilter

See Also:

• RFC 7523 - JWT Bearer Authorization Grant
• AllowOnlyFilter supporting request authorization - e.g. safe-lists
• ResourceAccess and subtypes to manage how request scopes are obtained
• JwkSetHandler where IG as the JWT issuer can expose its public keys

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	GrantSwapJwtAssertionOAuth2ClientFilter.Heaplet	Creates and initialises an GrantSwapJwtAssertionOAuth2ClientFilter in a heap environment.

Method Summary

Modifier and Type	Method	Description
Promise<Response,NeverThrowsException>	filter(Context context, Request request, Handler next)	Filters the request and/or response of an exchange.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

filter

public Promise<Response,NeverThrowsException> filter(Context context,
 Request request,
 Handler next)

Description copied from interface: Filter

Filters the request and/or response of an exchange. To pass the request to the next filter or handler in the chain, the filter calls next.handle(context, request).

This method may elect not to pass the request to the next filter or handler, and instead handle the request itself. It can achieve this by merely avoiding a call to next.handle(context, request) and creating its own response object. The filter is also at liberty to replace a response with another of its own by intercepting the response returned by the next handler.

Specified by:

filter in interface Filter

Parameters:

context - The request context.

request - The request.

next - The next filter or handler in the chain to handle the request.

Returns:

A Promise representing the response to be returned to the client.