From 6bec78cf6b07c3f99aa8a2a6992a01c9e7d801c1 Mon Sep 17 00:00:00 2001 From: Joe Grandja Date: Mon, 23 May 2022 11:42:13 -0400 Subject: [PATCH] Polish Protocol Endpoints in ref doc Issue gh-672 --- .../src/docs/asciidoc/protocol-endpoints.adoc | 126 ++++++++++++------ 1 file changed, 84 insertions(+), 42 deletions(-) diff --git a/docs/src/docs/asciidoc/protocol-endpoints.adoc b/docs/src/docs/asciidoc/protocol-endpoints.adoc index 05d48edb..530eaa35 100644 --- a/docs/src/docs/asciidoc/protocol-endpoints.adoc +++ b/docs/src/docs/asciidoc/protocol-endpoints.adoc @@ -95,7 +95,7 @@ The supported https://datatracker.ietf.org/doc/html/rfc6749#section-1.3[authoriz [[oauth2-token-introspection-endpoint]] == OAuth2 Token Introspection Endpoint -`OAuth2TokenIntrospectionEndpointConfigurer` provides the ability to customize the https://tools.ietf.org/html/rfc7662[OAuth2 Token Introspection endpoint]. +`OAuth2TokenIntrospectionEndpointConfigurer` provides the ability to customize the https://datatracker.ietf.org/doc/html/rfc7662#section-2[OAuth2 Token Introspection endpoint]. It defines extension points that let you customize the pre-processing, main processing, and post-processing logic for https://datatracker.ietf.org/doc/html/rfc7662#section-2.1[OAuth2 introspection requests]. `OAuth2TokenIntrospectionEndpointConfigurer` provides the following configuration options: @@ -122,8 +122,8 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h ---- <1> `introspectionRequestConverter()`: The `AuthenticationConverter` (_pre-processor_) used when attempting to extract an https://datatracker.ietf.org/doc/html/rfc7662#section-2.1[OAuth2 introspection request] from `HttpServletRequest` to an instance of `OAuth2TokenIntrospectionAuthenticationToken`. <2> `authenticationProvider()`: The `AuthenticationProvider` (_main processor_) used for authenticating the `OAuth2TokenIntrospectionAuthenticationToken`. (One or more may be added to replace the defaults.) -<3> `introspectionResponseHandler()`: The `AuthenticationSuccessHandler` (_post-processor_) used for handling an "`authenticated`" `OAuth2TokenIntrospectionAuthenticationToken` and returning the https://datatracker.ietf.org/doc/html/rfc7662#section-2.2[OAuth2TokenIntrospection]. -<4> `errorResponseHandler()`: The `AuthenticationFailureHandler` (_post-processor_) used for handling an `OAuth2AuthenticationException` and returning the https://datatracker.ietf.org/doc/html/rfc6749#section-5.2[OAuth2Error response]. +<3> `introspectionResponseHandler()`: The `AuthenticationSuccessHandler` (_post-processor_) used for handling an "`authenticated`" `OAuth2TokenIntrospectionAuthenticationToken` and returning the https://datatracker.ietf.org/doc/html/rfc7662#section-2.2[OAuth2TokenIntrospection response]. +<4> `errorResponseHandler()`: The `AuthenticationFailureHandler` (_post-processor_) used for handling an `OAuth2AuthenticationException` and returning the https://datatracker.ietf.org/doc/html/rfc7662#section-2.3[OAuth2Error response]. `OAuth2TokenIntrospectionEndpointConfigurer` configures the `OAuth2TokenIntrospectionEndpointFilter` and registers it with the OAuth2 authorization server `SecurityFilterChain` `@Bean`. `OAuth2TokenIntrospectionEndpointFilter` is the `Filter` that processes OAuth2 introspection requests. @@ -132,13 +132,13 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h * `*AuthenticationConverter*` -- An internal implementation that returns the `OAuth2TokenIntrospectionAuthenticationToken`. * `*AuthenticationManager*` -- An `AuthenticationManager` composed of `OAuth2TokenIntrospectionAuthenticationProvider`. -* `*AuthenticationSuccessHandler*` -- An internal implementation that handles an "`authenticated`" `OAuth2TokenIntrospectionAuthenticationToken` and returns the `OAuth2TokenIntrospection`. +* `*AuthenticationSuccessHandler*` -- An internal implementation that handles an "`authenticated`" `OAuth2TokenIntrospectionAuthenticationToken` and returns the `OAuth2TokenIntrospection` response. * `*AuthenticationFailureHandler*` -- An internal implementation that uses the `OAuth2Error` associated with the `OAuth2AuthenticationException` and returns the `OAuth2Error` response. [[oauth2-token-revocation-endpoint]] == OAuth2 Token Revocation Endpoint -`OAuth2TokenRevocationEndpointConfigurer` provides the ability to customize the https://tools.ietf.org/html/rfc7009[OAuth2 Token Revocation endpoint]. +`OAuth2TokenRevocationEndpointConfigurer` provides the ability to customize the https://datatracker.ietf.org/doc/html/rfc7009#section-2[OAuth2 Token Revocation endpoint]. It defines extension points that let you customize the pre-processing, main processing, and post-processing logic for https://datatracker.ietf.org/doc/html/rfc7009#section-2.1[OAuth2 revocation requests]. `OAuth2TokenRevocationEndpointConfigurer` provides the following configuration options: @@ -166,7 +166,7 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h <1> `revocationRequestConverter()`: The `AuthenticationConverter` (_pre-processor_) used when attempting to extract an https://datatracker.ietf.org/doc/html/rfc7009#section-2.1[OAuth2 revocation request] from `HttpServletRequest` to an instance of `OAuth2TokenRevocationAuthenticationToken`. <2> `authenticationProvider()`: The `AuthenticationProvider` (_main processor_) used for authenticating the `OAuth2TokenRevocationAuthenticationToken`. (One or more may be added to replace the defaults.) <3> `revocationResponseHandler()`: The `AuthenticationSuccessHandler` (_post-processor_) used for handling an "`authenticated`" `OAuth2TokenRevocationAuthenticationToken` and returning the https://datatracker.ietf.org/doc/html/rfc7009#section-2.2[OAuth2 revocation response]. -<4> `errorResponseHandler()`: The `AuthenticationFailureHandler` (_post-processor_) used for handling an `OAuth2AuthenticationException` and returning the https://datatracker.ietf.org/doc/html/rfc6749#section-5.2[OAuth2Error response]. +<4> `errorResponseHandler()`: The `AuthenticationFailureHandler` (_post-processor_) used for handling an `OAuth2AuthenticationException` and returning the https://datatracker.ietf.org/doc/html/rfc7009#section-2.2.1[OAuth2Error response]. `OAuth2TokenRevocationEndpointConfigurer` configures the `OAuth2TokenRevocationEndpointFilter` and registers it with the OAuth2 authorization server `SecurityFilterChain` `@Bean`. `OAuth2TokenRevocationEndpointFilter` is the `Filter` that processes OAuth2 revocation requests. @@ -181,10 +181,10 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h [[oauth2-authorization-server-metadata-endpoint]] == OAuth2 Authorization Server Metadata Endpoint -`OAuth2AuthorizationServerConfigurer` provides support for the https://tools.ietf.org/html/rfc8414[OAuth2 Authorization Server Metadata endpoint]. +`OAuth2AuthorizationServerConfigurer` provides support for the https://datatracker.ietf.org/doc/html/rfc8414#section-3[OAuth2 Authorization Server Metadata endpoint]. `OAuth2AuthorizationServerConfigurer` configures the `OAuth2AuthorizationServerMetadataEndpointFilter` and registers it with the OAuth2 authorization server `SecurityFilterChain` `@Bean`. -`OAuth2AuthorizationServerMetadataEndpointFilter` is the `Filter` that processes https://tools.ietf.org/html/rfc8414[OAuth2 authorization server metadata requests] and returns the https://datatracker.ietf.org/doc/html/rfc8414#section-3.2[OAuth2 authorization server metadata response]. +`OAuth2AuthorizationServerMetadataEndpointFilter` is the `Filter` that processes https://datatracker.ietf.org/doc/html/rfc8414#section-3.1[OAuth2 authorization server metadata requests] and returns the https://datatracker.ietf.org/doc/html/rfc8414#section-3.2[OAuth2AuthorizationServerMetadata response]. [[jwk-set-endpoint]] == JWK Set Endpoint @@ -203,35 +203,79 @@ The JWK Set endpoint is configured *only* if a `JWKSource` `@Be `OidcConfigurer` provides support for the https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[OpenID Connect 1.0 Provider Configuration endpoint]. `OidcConfigurer` configures the `OidcProviderConfigurationEndpointFilter` and registers it with the OAuth2 authorization server `SecurityFilterChain` `@Bean`. -`OidcProviderConfigurationEndpointFilter` is the `Filter` that returns the https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse[provider configuration response]. +`OidcProviderConfigurationEndpointFilter` is the `Filter` that returns the https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse[OidcProviderConfiguration response]. [[oidc-user-info-endpoint]] == OpenID Connect 1.0 UserInfo Endpoint -The following example shows how to enable the https://openid.net/specs/openid-connect-core-1_0.html#UserInfo[OpenID Connect 1.0 UserInfo endpoint]: +`OidcUserInfoEndpointConfigurer` provides the ability to customize the https://openid.net/specs/openid-connect-core-1_0.html#UserInfo[OpenID Connect 1.0 UserInfo endpoint]. +It defines extension points that let you customize the https://openid.net/specs/openid-connect-core-1_0.html#UserInfoResponse[UserInfo response]. + +`OidcUserInfoEndpointConfigurer` provides the following configuration option: + +[source,java] +---- +@Bean +public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception { + OAuth2AuthorizationServerConfigurer authorizationServerConfigurer = + new OAuth2AuthorizationServerConfigurer<>(); + http.apply(authorizationServerConfigurer); + + authorizationServerConfigurer + .oidc(oidc -> + oidc + .userInfoEndpoint(userInfoEndpoint -> + userInfoEndpoint.userInfoMapper(userInfoMapper) <1> + ) + ); + + return http.build(); +} +---- +<1> `userInfoMapper()`: The `Function` used to extract claims from `OidcUserInfoAuthenticationContext` to an instance of `OidcUserInfo`. + +`OidcUserInfoEndpointConfigurer` configures the `OidcUserInfoEndpointFilter` and registers it with the OAuth2 authorization server `SecurityFilterChain` `@Bean`. +`OidcUserInfoEndpointFilter` is the `Filter` that processes https://openid.net/specs/openid-connect-core-1_0.html#UserInfoRequest[UserInfo requests] and returns the https://openid.net/specs/openid-connect-core-1_0.html#UserInfoResponse[OidcUserInfo response]. + +`OidcUserInfoEndpointFilter` is configured with the following defaults: + +* `*AuthenticationManager*` -- An `AuthenticationManager` composed of `OidcUserInfoAuthenticationProvider`, which is associated with an internal implementation of `userInfoMapper` that extracts https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims[standard claims] from the https://openid.net/specs/openid-connect-core-1_0.html#IDToken[ID Token] based on the https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims[scopes requested] during authorization. + +[TIP] +You can customize the ID Token by providing an xref:core-model-components.adoc#oauth2-token-customizer[`OAuth2TokenCustomizer`] `@Bean`. + +The OpenID Connect 1.0 UserInfo endpoint is an OAuth2 protected resource, which *REQUIRES* an access token to be sent as a bearer token in the https://openid.net/specs/openid-connect-core-1_0.html#UserInfoRequest[UserInfo request]. +The following example shows how to enable the OAuth2 resource server configuration: [source,java] ---- @Bean public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception { - OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(http); - http.oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt); - return http.build(); + OAuth2AuthorizationServerConfigurer authorizationServerConfigurer = + new OAuth2AuthorizationServerConfigurer<>(); + http.apply(authorizationServerConfigurer); + + ... + + http.oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt); + + return http.build(); } @Bean public JwtDecoder jwtDecoder(JWKSource jwkSource) { - return OAuth2AuthorizationServerConfiguration.jwtDecoder(jwkSource); + return OAuth2AuthorizationServerConfiguration.jwtDecoder(jwkSource); } ---- [NOTE] -A `JwtDecoder` is *REQUIRED* for the OpenID Connect 1.0 UserInfo endpoint. See xref:configuration-model.adoc#default-configuration[Default configuration] for more information. +A `JwtDecoder` `@Bean` is *REQUIRED* for the OpenID Connect 1.0 UserInfo endpoint. -`OidcUserInfoEndpointConfigurer` provides the ability to customize the UserInfo endpoint. -It defines extension points that let you customize the https://openid.net/specs/openid-connect-core-1_0.html#UserInfoResponse[UserInfo response]. +[[oidc-client-registration-endpoint]] +== OpenID Connect 1.0 Client Registration Endpoint -`OidcUserInfoEndpointConfigurer` provides the following configuration option: +`OidcClientRegistrationEndpointConfigurer` configures the https://openid.net/specs/openid-connect-registration-1_0.html#ClientRegistration[OpenID Connect 1.0 Client Registration endpoint]. +The following example shows how to enable (disabled by default) the OpenID Connect 1.0 Client Registration endpoint: [source,java] ---- @@ -242,31 +286,34 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h http.apply(authorizationServerConfigurer); authorizationServerConfigurer - .oidc(oidc -> oidc - .userInfoEndpoint(userInfoEndpoint -> - userInfoEndpoint.userInfoMapper(userInfoMapper) // <1> - ) + .oidc(oidc -> + oidc + .clientRegistrationEndpoint(Customizer.withDefaults()) ); return http.build(); } ---- -<1> `userInfoMapper()`: The `Function` used to extract claims from `OidcUserInfoAuthenticationContext` to an instance of `OidcUserInfo`. -`OidcUserInfoEndpointConfigurer` configures the `OidcUserInfoEndpointFilter` and registers it with the OAuth2 authorization server `SecurityFilterChain` `@Bean`. -`OidcUserInfoEndpointFilter` is the `Filter` that processes https://openid.net/specs/openid-connect-core-1_0.html#UserInfoRequest[UserInfo requests] and returns the `OidcUserInfo`. +`OidcClientRegistrationEndpointConfigurer` configures the `OidcClientRegistrationEndpointFilter` and registers it with the OAuth2 authorization server `SecurityFilterChain` `@Bean`. +`OidcClientRegistrationEndpointFilter` is the `Filter` that processes https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationRequest[Client Registration requests] and returns the https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationResponse[OidcClientRegistration response]. -`OidcUserInfoEndpointFilter` is configured with the following defaults: +[TIP] +`OidcClientRegistrationEndpointFilter` also processes https://openid.net/specs/openid-connect-registration-1_0.html#ReadRequest[Client Read requests] and returns the https://openid.net/specs/openid-connect-registration-1_0.html#ReadResponse[OidcClientRegistration response]. -* `*userInfoMapper()*` -- An internal implementation that extracts https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims[standard claims] from the https://openid.net/specs/openid-connect-core-1_0.html#IDToken[ID Token] based on the https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims[scopes requested] during authorization. +`OidcClientRegistrationEndpointFilter` is configured with the following defaults: -[TIP] -You can customize the ID Token by providing an xref:core-model-components.adoc#oauth2-token-customizer[`OAuth2TokenCustomizer`] declared with a generic type of `JwtEncodingContext`. +* `*AuthenticationManager*` -- An `AuthenticationManager` composed of `OidcClientRegistrationAuthenticationProvider`. -[[oidc-client-registration-endpoint]] -== OpenID Connect 1.0 Client Registration Endpoint +The OpenID Connect 1.0 Client Registration endpoint is an https://openid.net/specs/openid-connect-registration-1_0.html#ClientRegistration[OAuth2 protected resource], which *REQUIRES* an access token to be sent as a bearer token in the Client Registration (or Client Read) request. + +[IMPORTANT] +The access token in a Client Registration request *REQUIRES* the OAuth2 scope `client.create`. + +[IMPORTANT] +The access token in a Client Read request *REQUIRES* the OAuth2 scope `client.read`. -The following example shows how to enable the https://openid.net/specs/openid-connect-registration-1_0.html#ClientRegistration[OpenID Connect 1.0 Client Registration Endpoint]: +The following example shows how to enable the OAuth2 resource server configuration: [source,java] ---- @@ -275,24 +322,19 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h OAuth2AuthorizationServerConfigurer authorizationServerConfigurer = new OAuth2AuthorizationServerConfigurer<>(); http.apply(authorizationServerConfigurer); - http.oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt); - authorizationServerConfigurer - .oidc(oidc -> oidc - .clientRegistrationEndpoint(Customizer.withDefaults()) - ); + ... + + http.oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt); return http.build(); } @Bean public JwtDecoder jwtDecoder(JWKSource jwkSource) { - return OAuth2AuthorizationServerConfiguration.jwtDecoder(jwkSource); + return OAuth2AuthorizationServerConfiguration.jwtDecoder(jwkSource); } ---- [NOTE] -A `JwtDecoder` is *REQUIRED* for the OpenID Connect 1.0 Client Registration Endpoint. See xref:configuration-model.adoc#default-configuration[Default configuration] for more information. - -`OidcClientRegistrationEndpointConfigurer` configures the `OidcClientRegistrationEndpointFilter` and registers it with the OAuth2 authorization server `SecurityFilterChain` `@Bean`. -`OidcClientRegistrationEndpointFilter` is the `Filter` that processes https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationRequest[Client Registration requests] and returns the https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationResponse[`OidcClientRegistration`]. +A `JwtDecoder` `@Bean` is *REQUIRED* for the OpenID Connect 1.0 Client Registration endpoint.