|
|
@@ -3,22 +3,231 @@
|
|
|
:toc: left
|
|
|
:toclevels: 1
|
|
|
|
|
|
-[[oauth2-authorization-server-configurer]]
|
|
|
-== OAuth2AuthorizationServerConfigurer
|
|
|
+[[default-configuration]]
|
|
|
+== Default configuration
|
|
|
|
|
|
-This section is under construction.
|
|
|
+`OAuth2AuthorizationServerConfiguration` is a `@Configuration` that provides the minimal default configuration for an OAuth2 authorization server.
|
|
|
|
|
|
-[[oauth2-authorization-server-configuration]]
|
|
|
-== OAuth2AuthorizationServerConfiguration
|
|
|
+`OAuth2AuthorizationServerConfiguration` uses <<customizing-the-configuration, `OAuth2AuthorizationServerConfigurer`>> to apply the default configuration and registers a `SecurityFilterChain` `@Bean` composed of all the infrastructure components supporting an OAuth2 authorization server.
|
|
|
|
|
|
-This section is under construction.
|
|
|
+[TIP]
|
|
|
+`OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(HttpSecurity)` is a convenience (`static`) utility method that applies the default OAuth2 security configuration to `HttpSecurity`.
|
|
|
|
|
|
-[[provider-settings]]
|
|
|
-== ProviderSettings
|
|
|
+The OAuth2 authorization server `SecurityFilterChain` `@Bean` is configured with the following default protocol endpoints:
|
|
|
|
|
|
-This section is under construction.
|
|
|
+* xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[OAuth2 Authorization endpoint]
|
|
|
+* xref:protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint]
|
|
|
+* xref:protocol-endpoints.adoc#oauth2-token-introspection-endpoint[OAuth2 Token Introspection endpoint]
|
|
|
+* xref:protocol-endpoints.adoc#oauth2-token-revocation-endpoint[OAuth2 Token Revocation endpoint]
|
|
|
+* xref:protocol-endpoints.adoc#oauth2-authorization-server-metadata-endpoint[OAuth2 Authorization Server Metadata endpoint]
|
|
|
+* xref:protocol-endpoints.adoc#jwk-set-endpoint[JWK Set endpoint]
|
|
|
+* xref:protocol-endpoints.adoc#oidc-provider-configuration-endpoint[OpenID Connect 1.0 Provider Configuration endpoint]
|
|
|
+* xref:protocol-endpoints.adoc#oidc-user-info-endpoint[OpenID Connect 1.0 UserInfo endpoint]
|
|
|
|
|
|
-[[provider-context]]
|
|
|
-== ProviderContext
|
|
|
+[NOTE]
|
|
|
+The JWK Set endpoint is configured *only* if a `JWKSource<SecurityContext>` `@Bean` is registered.
|
|
|
|
|
|
-This section is under construction.
|
|
|
+[NOTE]
|
|
|
+The xref:protocol-endpoints.adoc#oidc-client-registration-endpoint[OpenID Connect 1.0 Client Registration endpoint] is disabled by default.
|
|
|
+
|
|
|
+The following example shows how to use `OAuth2AuthorizationServerConfiguration` to apply the minimal default configuration:
|
|
|
+
|
|
|
+[source,java]
|
|
|
+----
|
|
|
+@Configuration
|
|
|
+@Import(OAuth2AuthorizationServerConfiguration.class)
|
|
|
+public class AuthorizationServerConfig {
|
|
|
+
|
|
|
+ @Bean
|
|
|
+ public RegisteredClientRepository registeredClientRepository() {
|
|
|
+ List<RegisteredClient> registrations = ...
|
|
|
+ return new InMemoryRegisteredClientRepository(registrations);
|
|
|
+ }
|
|
|
+
|
|
|
+ @Bean
|
|
|
+ public JWKSource<SecurityContext> jwkSource() {
|
|
|
+ RSAKey rsaKey = ...
|
|
|
+ JWKSet jwkSet = new JWKSet(rsaKey);
|
|
|
+ return (jwkSelector, securityContext) -> jwkSelector.select(jwkSet);
|
|
|
+ }
|
|
|
+
|
|
|
+}
|
|
|
+----
|
|
|
+
|
|
|
+[IMPORTANT]
|
|
|
+The https://datatracker.ietf.org/doc/html/rfc6749#section-4.1[authorization_code grant] requires the resource owner to be authenticated. Therefore, a user authentication mechanism *must* be configured in addition to the default OAuth2 security configuration.
|
|
|
+
|
|
|
+[TIP]
|
|
|
+`OAuth2AuthorizationServerConfiguration.jwtDecoder(JWKSource<SecurityContext>)` is a convenience (`static`) utility method that can be used to register a `JwtDecoder` `@Bean`, which is *REQUIRED* for the xref:protocol-endpoints.adoc#oidc-user-info-endpoint[OpenID Connect 1.0 UserInfo endpoint] and the xref:protocol-endpoints.adoc#oidc-client-registration-endpoint[OpenID Connect 1.0 Client Registration endpoint].
|
|
|
+
|
|
|
+The following example shows how to register a `JwtDecoder` `@Bean`:
|
|
|
+
|
|
|
+[source,java]
|
|
|
+----
|
|
|
+@Bean
|
|
|
+public JwtDecoder jwtDecoder(JWKSource<SecurityContext> jwkSource) {
|
|
|
+ return OAuth2AuthorizationServerConfiguration.jwtDecoder(jwkSource);
|
|
|
+}
|
|
|
+----
|
|
|
+
|
|
|
+The main intent of `OAuth2AuthorizationServerConfiguration` is to provide a convenient method to apply the minimal default configuration for an OAuth2 authorization server. However, in most cases, customizing the configuration will be required.
|
|
|
+
|
|
|
+[[customizing-the-configuration]]
|
|
|
+== Customizing the configuration
|
|
|
+
|
|
|
+`OAuth2AuthorizationServerConfigurer` provides the ability to fully customize the security configuration for an OAuth2 authorization server.
|
|
|
+It lets you specify the core components to use - for example, xref:core-model-components.adoc#registered-client-repository[`RegisteredClientRepository`], xref:core-model-components.adoc#oauth2-authorization-service[`OAuth2AuthorizationService`], xref:core-model-components.adoc#oauth2-token-generator[`OAuth2TokenGenerator`], and others.
|
|
|
+Furthermore, it lets you customize the request processing logic for the protocol endpoints – for example, xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[authorization endpoint], xref:protocol-endpoints.adoc#oauth2-token-endpoint[token endpoint], xref:protocol-endpoints.adoc#oauth2-token-introspection-endpoint[token introspection endpoint], and others.
|
|
|
+
|
|
|
+`OAuth2AuthorizationServerConfigurer` provides the following configuration options:
|
|
|
+
|
|
|
+[source,java]
|
|
|
+----
|
|
|
+@Bean
|
|
|
+public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
|
|
|
+ OAuth2AuthorizationServerConfigurer<HttpSecurity> authorizationServerConfigurer =
|
|
|
+ new OAuth2AuthorizationServerConfigurer<>();
|
|
|
+ http.apply(authorizationServerConfigurer);
|
|
|
+
|
|
|
+ authorizationServerConfigurer
|
|
|
+ .registeredClientRepository(registeredClientRepository) <1>
|
|
|
+ .authorizationService(authorizationService) <2>
|
|
|
+ .authorizationConsentService(authorizationConsentService) <3>
|
|
|
+ .providerSettings(providerSettings) <4>
|
|
|
+ .tokenGenerator(tokenGenerator) <5>
|
|
|
+ .clientAuthentication(clientAuthentication -> { }) <6>
|
|
|
+ .authorizationEndpoint(authorizationEndpoint -> { }) <7>
|
|
|
+ .tokenEndpoint(tokenEndpoint -> { }) <8>
|
|
|
+ .tokenIntrospectionEndpoint(tokenIntrospectionEndpoint -> { }) <9>
|
|
|
+ .tokenRevocationEndpoint(tokenRevocationEndpoint -> { }) <10>
|
|
|
+ .oidc(oidc -> oidc
|
|
|
+ .userInfoEndpoint(userInfoEndpoint -> { }) <11>
|
|
|
+ .clientRegistrationEndpoint(clientRegistrationEndpoint -> { }) <12>
|
|
|
+ );
|
|
|
+
|
|
|
+ return http.build();
|
|
|
+}
|
|
|
+----
|
|
|
+<1> `registeredClientRepository()`: The xref:core-model-components.adoc#registered-client-repository[`RegisteredClientRepository`] to use.
|
|
|
+<2> `authorizationService()`: The xref:core-model-components.adoc#oauth2-authorization-service[`OAuth2AuthorizationService`] to use.
|
|
|
+<3> `authorizationConsentService()`: The xref:core-model-components.adoc#oauth2-authorization-consent-service[`OAuth2AuthorizationConsentService`] to use.
|
|
|
+<4> `providerSettings()`: The <<configuring-provider-settings, `ProviderSettings`>> to use.
|
|
|
+<5> `tokenGenerator()`: The xref:core-model-components.adoc#oauth2-token-generator[`OAuth2TokenGenerator`] to use.
|
|
|
+<6> `clientAuthentication()`: The configurer for <<configuring-client-authentication, OAuth2 Client Authentication>>.
|
|
|
+<7> `authorizationEndpoint()`: The configurer for the xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[OAuth2 Authorization endpoint].
|
|
|
+<8> `tokenEndpoint()`: The configurer for the xref:protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint].
|
|
|
+<9> `tokenIntrospectionEndpoint()`: The configurer for the xref:protocol-endpoints.adoc#oauth2-token-introspection-endpoint[OAuth2 Token Introspection endpoint].
|
|
|
+<10> `tokenRevocationEndpoint()`: The configurer for the xref:protocol-endpoints.adoc#oauth2-token-revocation-endpoint[OAuth2 Token Revocation endpoint].
|
|
|
+<11> `userInfoEndpoint()`: The configurer for the xref:protocol-endpoints.adoc#oidc-user-info-endpoint[OpenID Connect 1.0 UserInfo endpoint].
|
|
|
+<12> `clientRegistrationEndpoint()`: The configurer for the xref:protocol-endpoints.adoc#oidc-client-registration-endpoint[OpenID Connect 1.0 Client Registration endpoint].
|
|
|
+
|
|
|
+[[configuring-provider-settings]]
|
|
|
+== Configuring Provider Settings
|
|
|
+
|
|
|
+`ProviderSettings` contains the configuration settings for the OAuth2 authorization server (provider).
|
|
|
+It specifies the `URI` for the protocol endpoints as well as the https://datatracker.ietf.org/doc/html/rfc8414#section-2[issuer identifier].
|
|
|
+The default `URI` for the protocol endpoints are as follows:
|
|
|
+
|
|
|
+[source,java]
|
|
|
+----
|
|
|
+public final class ProviderSettings extends AbstractSettings {
|
|
|
+
|
|
|
+ ...
|
|
|
+
|
|
|
+ public static Builder builder() {
|
|
|
+ return new Builder()
|
|
|
+ .authorizationEndpoint("/oauth2/authorize")
|
|
|
+ .tokenEndpoint("/oauth2/token")
|
|
|
+ .tokenIntrospectionEndpoint("/oauth2/introspect")
|
|
|
+ .tokenRevocationEndpoint("/oauth2/revoke")
|
|
|
+ .jwkSetEndpoint("/oauth2/jwks")
|
|
|
+ .oidcUserInfoEndpoint("/userinfo")
|
|
|
+ .oidcClientRegistrationEndpoint("/connect/register");
|
|
|
+ }
|
|
|
+
|
|
|
+ ...
|
|
|
+
|
|
|
+}
|
|
|
+----
|
|
|
+
|
|
|
+[NOTE]
|
|
|
+`ProviderSettings` is a *REQUIRED* component.
|
|
|
+
|
|
|
+[TIP]
|
|
|
+<<default-configuration, `@Import(OAuth2AuthorizationServerConfiguration.class)`>> automatically registers a `ProviderSettings` `@Bean`, if not already provided.
|
|
|
+
|
|
|
+The following example shows how to customize the configuration settings and register a `ProviderSettings` `@Bean`:
|
|
|
+
|
|
|
+[source,java]
|
|
|
+----
|
|
|
+@Bean
|
|
|
+public ProviderSettings providerSettings() {
|
|
|
+ return ProviderSettings.builder()
|
|
|
+ .issuer("https://example.com")
|
|
|
+ .authorizationEndpoint("/oauth2/v1/authorize")
|
|
|
+ .tokenEndpoint("/oauth2/v1/token")
|
|
|
+ .tokenIntrospectionEndpoint("/oauth2/v1/introspect")
|
|
|
+ .tokenRevocationEndpoint("/oauth2/v1/revoke")
|
|
|
+ .jwkSetEndpoint("/oauth2/v1/jwks")
|
|
|
+ .oidcUserInfoEndpoint("/connect/v1/userinfo")
|
|
|
+ .oidcClientRegistrationEndpoint("/connect/v1/register")
|
|
|
+ .build();
|
|
|
+}
|
|
|
+----
|
|
|
+
|
|
|
+The `ProviderContext` is a context object that holds information about the provider.
|
|
|
+It provides access to the `ProviderSettings` and the "`current`" issuer identifier.
|
|
|
+
|
|
|
+[NOTE]
|
|
|
+If the issuer identifier is not configured in `ProviderSettings.builder().issuer(String)`, it is resolved from the current request.
|
|
|
+
|
|
|
+The `ProviderContext` is accessible through the `ProviderContextHolder`, which associates it with the current request thread by using a `ThreadLocal`.
|
|
|
+
|
|
|
+[NOTE]
|
|
|
+The `ProviderContextFilter` associates the `ProviderContext` with the `ProviderContextHolder`.
|
|
|
+
|
|
|
+[[configuring-client-authentication]]
|
|
|
+== Configuring Client Authentication
|
|
|
+
|
|
|
+`OAuth2ClientAuthenticationConfigurer` provides the ability to customize https://datatracker.ietf.org/doc/html/rfc6749#section-2.3[OAuth2 client authentication].
|
|
|
+It defines extension points that let you customize the pre-processing, main processing, and post-processing logic for client authentication requests.
|
|
|
+
|
|
|
+`OAuth2ClientAuthenticationConfigurer` provides the following configuration options:
|
|
|
+
|
|
|
+[source,java]
|
|
|
+----
|
|
|
+@Bean
|
|
|
+public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
|
|
|
+ OAuth2AuthorizationServerConfigurer<HttpSecurity> authorizationServerConfigurer =
|
|
|
+ new OAuth2AuthorizationServerConfigurer<>();
|
|
|
+ http.apply(authorizationServerConfigurer);
|
|
|
+
|
|
|
+ authorizationServerConfigurer
|
|
|
+ .clientAuthentication(clientAuthentication ->
|
|
|
+ clientAuthentication
|
|
|
+ .authenticationConverter(authenticationConverter) <1>
|
|
|
+ .authenticationProvider(authenticationProvider) <2>
|
|
|
+ .authenticationSuccessHandler(authenticationSuccessHandler) <3>
|
|
|
+ .errorResponseHandler(errorResponseHandler) <4>
|
|
|
+ );
|
|
|
+
|
|
|
+ return http.build();
|
|
|
+}
|
|
|
+----
|
|
|
+<1> `authenticationConverter()`: The `AuthenticationConverter` (_pre-processor_) used when attempting to extract client credentials from `HttpServletRequest` to an instance of `OAuth2ClientAuthenticationToken`.
|
|
|
+<2> `authenticationProvider()`: The `AuthenticationProvider` (_main processor_) used for authenticating the `OAuth2ClientAuthenticationToken`. (One or more may be added to replace the defaults.)
|
|
|
+<3> `authenticationSuccessHandler()`: The `AuthenticationSuccessHandler` (_post-processor_) used for handling a successful client authentication and associating the `OAuth2ClientAuthenticationToken` to the `SecurityContext`.
|
|
|
+<4> `errorResponseHandler()`: The `AuthenticationFailureHandler` (_post-processor_) used for handling a failed client authentication and returning the https://datatracker.ietf.org/doc/html/rfc6749#section-5.2[`OAuth2Error` response].
|
|
|
+
|
|
|
+`OAuth2ClientAuthenticationConfigurer` configures the `OAuth2ClientAuthenticationFilter` and registers it with the OAuth2 authorization server `SecurityFilterChain` `@Bean`.
|
|
|
+`OAuth2ClientAuthenticationFilter` is the `Filter` that processes client authentication requests.
|
|
|
+
|
|
|
+By default, client authentication is required for the xref:protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint], the xref:protocol-endpoints.adoc#oauth2-token-introspection-endpoint[OAuth2 Token Introspection endpoint], and the xref:protocol-endpoints.adoc#oauth2-token-revocation-endpoint[OAuth2 Token Revocation endpoint].
|
|
|
+The supported client authentication methods are `client_secret_basic`, `client_secret_post`, `private_key_jwt`, `client_secret_jwt`, and `none` (public clients).
|
|
|
+
|
|
|
+`OAuth2ClientAuthenticationFilter` is configured with the following defaults:
|
|
|
+
|
|
|
+* `*AuthenticationConverter*` -- A `DelegatingAuthenticationConverter` composed of `JwtClientAssertionAuthenticationConverter`, `ClientSecretBasicAuthenticationConverter`, `ClientSecretPostAuthenticationConverter`, and `PublicClientAuthenticationConverter`.
|
|
|
+* `*AuthenticationManager*` -- An `AuthenticationManager` composed of `JwtClientAssertionAuthenticationProvider`, `ClientSecretAuthenticationProvider`, and `PublicClientAuthenticationProvider`.
|
|
|
+* `*AuthenticationSuccessHandler*` -- An internal implementation that associates the "`authenticated`" `OAuth2ClientAuthenticationToken` (current `Authentication`) to the `SecurityContext`.
|
|
|
+* `*AuthenticationFailureHandler*` -- An internal implementation that uses the `OAuth2Error` associated with the `OAuth2AuthenticationException` to return the OAuth2 error response.
|
Joe Grandja