diff --git a/docs/src/docs/asciidoc/configuration-model.adoc b/docs/src/docs/asciidoc/configuration-model.adoc index ddc26cbf..39285462 100644 --- a/docs/src/docs/asciidoc/configuration-model.adoc +++ b/docs/src/docs/asciidoc/configuration-model.adoc @@ -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 <> 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` `@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 registrations = ... + return new InMemoryRegisteredClientRepository(registrations); + } + + @Bean + public JWKSource 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)` 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 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 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 <> to use. +<5> `tokenGenerator()`: The xref:core-model-components.adoc#oauth2-token-generator[`OAuth2TokenGenerator`] to use. +<6> `clientAuthentication()`: The configurer for <>. +<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] +<> 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 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. diff --git a/docs/src/docs/asciidoc/core-model-components.adoc b/docs/src/docs/asciidoc/core-model-components.adoc index a72e946d..f794fe95 100644 --- a/docs/src/docs/asciidoc/core-model-components.adoc +++ b/docs/src/docs/asciidoc/core-model-components.adoc @@ -117,7 +117,7 @@ public RegisteredClientRepository registeredClientRepository() { } ---- -Alternatively, you can configure the `RegisteredClientRepository` through the xref:configuration-model.adoc#oauth2-authorization-server-configurer[`OAuth2AuthorizationServerConfigurer`]: +Alternatively, you can configure the `RegisteredClientRepository` through the xref:configuration-model.adoc#customizing-the-configuration[`OAuth2AuthorizationServerConfigurer`]: [source,java] ---- @@ -207,7 +207,7 @@ public OAuth2AuthorizationService authorizationService() { } ---- -Alternatively, you can configure the `OAuth2AuthorizationService` through the xref:configuration-model.adoc#oauth2-authorization-server-configurer[`OAuth2AuthorizationServerConfigurer`]: +Alternatively, you can configure the `OAuth2AuthorizationService` through the xref:configuration-model.adoc#customizing-the-configuration[`OAuth2AuthorizationServerConfigurer`]: [source,java] ---- @@ -276,7 +276,7 @@ public OAuth2AuthorizationConsentService authorizationConsentService() { } ---- -Alternatively, you can configure the `OAuth2AuthorizationConsentService` through the xref:configuration-model.adoc#oauth2-authorization-server-configurer[`OAuth2AuthorizationServerConfigurer`]: +Alternatively, you can configure the `OAuth2AuthorizationConsentService` through the xref:configuration-model.adoc#customizing-the-configuration[`OAuth2AuthorizationServerConfigurer`]: [source,java] ---- @@ -329,7 +329,7 @@ public interface OAuth2TokenContext extends Context { ---- <1> `getRegisteredClient()`: The <> associated with the authorization grant. <2> `getPrincipal()`: The `Authentication` instance of the resource owner (or client). -<3> `getProviderContext()`: The xref:configuration-model.adoc#provider-context[`ProviderContext`] object that holds information related to the provider. +<3> `getProviderContext()`: The xref:configuration-model.adoc#configuring-provider-settings[`ProviderContext`] object that holds information related to the provider. <4> `getAuthorization()`: The <> associated with the authorization grant. <5> `getAuthorizedScopes()`: The scope(s) authorized for the client. <6> `getTokenType()`: The `OAuth2TokenType` to generate. The supported values are `code`, `access_token`, `refresh_token`, and `id_token`. @@ -382,7 +382,7 @@ public OAuth2TokenGenerator tokenGenerator() { } ---- -Alternatively, you can configure the `OAuth2TokenGenerator` through the xref:configuration-model.adoc#oauth2-authorization-server-configurer[`OAuth2AuthorizationServerConfigurer`]: +Alternatively, you can configure the `OAuth2TokenGenerator` through the xref:configuration-model.adoc#customizing-the-configuration[`OAuth2AuthorizationServerConfigurer`]: [source,java] ---- diff --git a/docs/src/docs/asciidoc/index.adoc b/docs/src/docs/asciidoc/index.adoc index 3e9cde54..64a4f2fc 100644 --- a/docs/src/docs/asciidoc/index.adoc +++ b/docs/src/docs/asciidoc/index.adoc @@ -7,7 +7,7 @@ v{spring-authorization-server-version} xref:overview.adoc[Overview] :: Introduction and list of supported features xref:getting-help.adoc[Getting Help] :: Links to samples, questions and issues xref:getting-started.adoc[Getting Started] :: System requirements, dependencies and developing your first application -xref:configuration-model.adoc[Configuration Model] :: Configuration and provider settings +xref:configuration-model.adoc[Configuration Model] :: Default configuration and customizing the configuration xref:core-model-components.adoc[Core Model / Components] :: Core domain model and component interfaces xref:protocol-endpoints.adoc[Protocol Endpoints] :: Specifications and endpoints xref:how-to.adoc["How-to" Guides] :: Guides to get the most from Spring Authorization Server diff --git a/docs/src/docs/asciidoc/protocol-endpoints.adoc b/docs/src/docs/asciidoc/protocol-endpoints.adoc index a1d4452e..eee40ba6 100644 --- a/docs/src/docs/asciidoc/protocol-endpoints.adoc +++ b/docs/src/docs/asciidoc/protocol-endpoints.adoc @@ -6,27 +6,27 @@ This page is under construction. [[oauth2-authorization-endpoint]] -== OAuth 2.0 Authorization Endpoint +== OAuth2 Authorization Endpoint This section is under construction. [[oauth2-token-endpoint]] -== OAuth 2.0 Token Endpoint +== OAuth2 Token Endpoint This section is under construction. [[oauth2-token-introspection-endpoint]] -== OAuth 2.0 Token Introspection Endpoint +== OAuth2 Token Introspection Endpoint This section is under construction. [[oauth2-token-revocation-endpoint]] -== OAuth 2.0 Token Revocation Endpoint +== OAuth2 Token Revocation Endpoint This section is under construction. [[oauth2-authorization-server-metadata-endpoint]] -== OAuth 2.0 Authorization Server Metadata Endpoint +== OAuth2 Authorization Server Metadata Endpoint This section is under construction. @@ -35,17 +35,17 @@ This section is under construction. This section is under construction. -[[openid-connect-provider-configuration-endpoint]] +[[oidc-provider-configuration-endpoint]] == OpenID Connect 1.0 Provider Configuration Endpoint This section is under construction. -[[openid-connect-user-info-endpoint]] +[[oidc-user-info-endpoint]] == OpenID Connect 1.0 UserInfo Endpoint This section is under construction. -[[openid-connect-client-registration-endpoint]] +[[oidc-client-registration-endpoint]] == OpenID Connect 1.0 Client Registration Endpoint This section is under construction.