Skip to content

Add Configuration Model in ref doc #736

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
jgrandja wants to merge 1 commit into from
Closed

Add Configuration Model in ref doc #736

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
231 changes: 220 additions & 11 deletions docs/src/docs/asciidoc/configuration-model.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,22 +3,231 @@
:toc: left
:toclevels: 1

[[oauth2-authorization-server-configurer]]
== OAuth2AuthorizationServerConfigurer
[[configure-defaults]]
== 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 <<configure-custom, `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`.

The OAuth2 authorization server `SecurityFilterChain` `@Bean` is configured with the following default protocol endpoints:

* 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]

[NOTE]
The JWK Set endpoint is configured *only* if a `JWKSource<SecurityContext>` `@Bean` is registered.

[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 xref:protocol-endpoints.adoc#oidc-user-info-endpoint[OpenID Connect 1.0 UserInfo endpoint] and 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.

[[configure-custom]]
== Customizing the configuration

`OAuth2AuthorizationServerConfigurer` provides the ability to fully customize the security configuration for an OAuth2 authorization server.
It allows you to 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 allows you to 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 <<provider-settings, `ProviderSettings`>> to use.
<5> `tokenGenerator()`: The xref:core-model-components.adoc#oauth2-token-generator[`OAuth2TokenGenerator`] to use.
<6> `clientAuthentication()`: The configurer for <<oauth2-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].

[[provider-settings]]
== ProviderSettings
== 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]
<<configure-defaults, `@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 will be resolved from the current request.

The `ProviderContext` is accessible through the `ProviderContextHolder`, which associates it with the current request thread using a `ThreadLocal`.

[NOTE]
The `ProviderContextFilter` associates the `ProviderContext` with the `ProviderContextHolder`.

[[oauth2-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 allow you to 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)
<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.

This section is under construction.
By default, client authentication is required for the xref:protocol-endpoints.adoc#oauth2-token-endpoint[OAuth2 Token endpoint], xref:protocol-endpoints.adoc#oauth2-token-introspection-endpoint[OAuth2 Token Introspection endpoint], and 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).

[[provider-context]]
== ProviderContext
`OAuth2ClientAuthenticationFilter` is configured with the following defaults:

This section is under construction.
`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.
10 changes: 5 additions & 5 deletions docs/src/docs/asciidoc/core-model-components.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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#configure-custom[`OAuth2AuthorizationServerConfigurer`]:

[source,java]
----
Expand Down Expand Up @@ -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#configure-custom[`OAuth2AuthorizationServerConfigurer`]:

[source,java]
----
Expand Down Expand Up @@ -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#configure-custom[`OAuth2AuthorizationServerConfigurer`]:

[source,java]
----
Expand Down Expand Up @@ -329,7 +329,7 @@ public interface OAuth2TokenContext extends Context {
----
<1> `getRegisteredClient()`: The <<registered-client, RegisteredClient>> 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#provider-settings[`ProviderContext`] object that holds information related to the provider.
<4> `getAuthorization()`: The <<oauth2-authorization, OAuth2Authorization>> 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`.
Expand Down Expand Up @@ -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#configure-custom[`OAuth2AuthorizationServerConfigurer`]:

[source,java]
----
Expand Down
2 changes: 1 addition & 1 deletion docs/src/docs/asciidoc/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
16 changes: 8 additions & 8 deletions docs/src/docs/asciidoc/protocol-endpoints.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.