Allow extension and/or modification of success/error response handlers within `Filter`s

[ddubson]

The purpose of this design charter is to evaluate a strategy for allowing extension and/or modification of success and error response handlers within a set of applicable server endpoints (implemented within Filter classes).

The present state of success and error handlers is that they are implemented mostly as private instance methods within respective Filter classes. (List of Filter classes below).

Success response handlers

Success response handlers should not be fully modifiable as they contain logic critical to a stable operating auth server, but they should be customizable at designated points. The designated points should be decided in advance with the criteria being: should a developer be able to modify this behavior? The approach of allowing the developer to inject Consumer<T> classes in order to extend a certain logic of a handler may be an option.

Success response handlers may be extendable at designated points. A developer should be able to inject their own application logic (e.g. for logging purposes) as needed — after the critical default success response handler.

Error response handlers

Error response handlers are much lighter than success response handlers as they contain less logic and overall have a smaller footprint for any given Filter response.

For example, the following is a subset of Filters contain the same logic for error response handling which may be abstracted into a consistent pattern for a default error response handler:

• OAuth2TokenIntrospectionEndpointFilter
• OAuth2TokenRevocationEndpointFilter
• OAuth2TokenEndpointFilter
• OAuth2DeviceAuthorizationEndpointFilter

Error response handlers may be extendable at designated points. A developer should be able to inject their own application logic (i.e. for logging purposes) as needed — after the critical default error response handler.

Potential approaches

Potential approaches for affording extensions of response handlers:

• Using private scoped, static functions as default success and error handlers, which may then be used in a class using Delegation pattern.
• Disallow overriding default handlers (private methods) as needed.

Potential approaches for affording modifications of default response handlers:

• Usage of Consumer<T> implementations

Appendix

The following is a list of allFilter classes

• Applicable (i.e. success/error handlers are present)
  • OAuth2AuthorizationEndpointFilter
  • OAuth2ClientAuthenticationFilter
  • OAuth2DeviceAuthorizationEndpointFilter
  • OAuth2DeviceVerificationEndpointFilter
  • OAuth2TokenEndpointFilter
  • OAuth2TokenIntrospectionEndpointFilter
  • OAuth2TokenRevocationEndpointFilter
  • OidcUserInfoEndpointFilter
  • OidcClientRegistrationEndpointFilter
  • OidcLogoutEndpointFilter
• Not applicable (i.e. no success/error handlers present)
  • NimbusJwkSetEndpointFilter
  • OAuth2AuthorizationServerMetadataEndpointFilter
  • OidcProviderConfigurationEndpointFilter

Use cases

• Application and/or audit logging of authorization server responses.
• Modify response codes and/or messages as per organizational need.
• Append additional data to success or error responses.

Related open issues

• Dedicated authentication-handler #WiP #1212
• Simplify customizing the access token response #925
• Consider enhancing OAuth2Error with specific error codes #1240
• How-to: Handle errors and customize the OAuth 2.0 Error response #541

[jgrandja]

Thanks for the detailed analysis @ddubson !

As far as the approach goes, I think we should start exposing AuthenticationSuccessHandler and AuthenticationFailureHandler implementations to allow for delegation-based strategy configurations. Furthermore, exposing new class implementations will allow us to add hooks to allow for customizing the default behaviour.

For the first iteration, let's create a new AuthenticationFailureHandler that will be used by:

• OAuth2TokenEndpointFilter
• OAuth2TokenIntrospectionEndpointFilter
• OAuth2TokenRevocationEndpointFilter
• OAuth2DeviceAuthorizationEndpointFilter

For the second iteration, let's see if we can come up with a hook in the new AuthenticationFailureHandler that will allow for reuse and customization for these additional Filter's:

• OAuth2ClientAuthenticationFilter
• OidcUserInfoEndpointFilter
• OidcClientRegistrationEndpointFilter

As far as exposing AuthenticationSuccessHandler's, let's focus on exposing OAuth2TokenEndpointFilter.sendAccessTokenResponse() as a new AuthenticationSuccessHandler, which will resolve gh-925. Let's keep this in a separate PR from the above work.