Polish ref doc

Issue spring-projectsgh-499

Author: Steve Riesenberg

docs/spring-authorization-server-docs.gradle

@@ -5,6 +5,8 @@ plugins {
 asciidoctor {
 	attributes([
 			"spring-authorization-server-version": project.version,
+			"spring-security-reference-base-url": "https://docs.spring.io/spring-security/reference",
+			"spring-security-api-base-url": "https://docs.spring.io/spring-security/site/docs/current/api",
 			"examples-dir": "examples",
 			"docs-java": "$sourceDir/examples/src/main/java",
 			"chomp": "default headers packages",

docs/src/docs/asciidoc/configuration-model.adoc

@@ -1,7 +1,5 @@
 [[configuration-model]]
 = Configuration Model
-:toc: left
-:toclevels: 1
 
 [[default-configuration]]
 == Default configuration
@@ -28,7 +26,7 @@ The OAuth2 authorization server `SecurityFilterChain` `@Bean` is configured with
 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 xref:protocol-endpoints.adoc#oidc-client-registration-endpoint[OpenID Connect 1.0 Client Registration endpoint] is disabled by default because many deployments do not require dynamic client registration.
 
 The following example shows how to use `OAuth2AuthorizationServerConfiguration` to apply the minimal default configuration:
 
@@ -108,11 +106,11 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h
 	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.
+<1> `registeredClientRepository()`: The xref:core-model-components.adoc#registered-client-repository[`RegisteredClientRepository`] (*REQUIRED*) for managing new and existing clients.
+<2> `authorizationService()`: The xref:core-model-components.adoc#oauth2-authorization-service[`OAuth2AuthorizationService`] for managing new and existing authorizations.
+<3> `authorizationConsentService()`: The xref:core-model-components.adoc#oauth2-authorization-consent-service[`OAuth2AuthorizationConsentService`] for managing new and existing authorization consents.
+<4> `providerSettings()`: The <<configuring-provider-settings, `ProviderSettings`>> (*REQUIRED*) for customizing configuration settings for the OAuth2 authorization server.
+<5> `tokenGenerator()`: The xref:core-model-components.adoc#oauth2-token-generator[`OAuth2TokenGenerator`] for generating tokens supported by the OAuth2 authorization server.
 <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].
@@ -181,6 +179,7 @@ It provides access to the `ProviderSettings` and the "`current`" issuer identifi
 [NOTE]
 If the issuer identifier is not configured in `ProviderSettings.builder().issuer(String)`, it is resolved from the current request.
 
+[NOTE]
 The `ProviderContext` is accessible through the `ProviderContextHolder`, which associates it with the current request thread by using a `ThreadLocal`.
 
 [NOTE]

docs/src/docs/asciidoc/core-model-components.adoc

@@ -1,8 +1,5 @@
 [[core-model-components]]
 = Core Model / Components
-:toc: left
-:toclevels: 1
-:spring-security-reference-base-url: https://docs.spring.io/spring-security/reference
 
 [[registered-client]]
 == RegisteredClient
@@ -136,6 +133,9 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h
 }
 ----
 
+[NOTE]
+The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple configuration options simultaneously.
+
 [[oauth2-authorization]]
 == OAuth2Authorization
 
@@ -144,13 +144,13 @@ An `OAuth2Authorization` is a representation of an OAuth2 authorization, which h
 [TIP]
 The corresponding authorization model in Spring Security's OAuth2 Client support is {spring-security-reference-base-url}/servlet/oauth2/client/core.html#oauth2Client-authorized-client[OAuth2AuthorizedClient].
 
-After the successful completion of an authorization grant flow, an `OAuth2Authorization` is created and associates an `OAuth2AccessToken`, an (optional) `OAuth2RefreshToken`, and additional state specific to the executed authorization grant type.
+After the successful completion of an authorization grant flow, an `OAuth2Authorization` is created and associates an {spring-security-api-base-url}/org/springframework/security/oauth2/core/OAuth2AccessToken.html[`OAuth2AccessToken`], an (optional) {spring-security-api-base-url}/org/springframework/security/oauth2/core/OAuth2RefreshToken.html[`OAuth2RefreshToken`], and additional state specific to the executed authorization grant type.
 
-The `OAuth2Token` instances associated with an `OAuth2Authorization` vary, depending on the authorization grant type.
+The {spring-security-api-base-url}/org/springframework/security/oauth2/core/OAuth2Token.html[`OAuth2Token`] instances associated with an `OAuth2Authorization` vary, depending on the authorization grant type.
 
 For the OAuth2 https://datatracker.ietf.org/doc/html/rfc6749#section-4.1[authorization_code grant], an `OAuth2AuthorizationCode`, an `OAuth2AccessToken`, and an (optional) `OAuth2RefreshToken` are associated.
 
-For the OpenID Connect 1.0 https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[authorization_code grant], an `OAuth2AuthorizationCode`, an `OidcIdToken`, an `OAuth2AccessToken`, and an (optional) `OAuth2RefreshToken` are associated.
+For the OpenID Connect 1.0 https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[authorization_code grant], an `OAuth2AuthorizationCode`, an {spring-security-api-base-url}/org/springframework/security/oauth2/core/oidc/OidcIdToken.html[`OidcIdToken`], an `OAuth2AccessToken`, and an (optional) `OAuth2RefreshToken` are associated.
 
 For the OAuth2 https://datatracker.ietf.org/doc/html/rfc6749#section-4.4[client_credentials grant], only an `OAuth2AccessToken` is associated.
 
@@ -226,6 +226,9 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h
 }
 ----
 
+[NOTE]
+The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple configuration options simultaneously.
+
 [[oauth2-authorization-consent]]
 == OAuth2AuthorizationConsent
 
@@ -295,6 +298,9 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h
 }
 ----
 
+[NOTE]
+The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple configuration options simultaneously.
+
 [[oauth2-token-context]]
 == OAuth2TokenContext
 
@@ -333,7 +339,7 @@ public interface OAuth2TokenContext extends Context {
 <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`.
-<7> `getAuthorizationGrantType()`: The `AuthorizationGrantType`.
+<7> `getAuthorizationGrantType()`: The `AuthorizationGrantType` associated with the authorization grant.
 <8> `getAuthorizationGrant()`: The `Authentication` instance used by the `AuthenticationProvider` that processes the authorization grant.
 
 [[oauth2-token-generator]]
@@ -363,7 +369,9 @@ The `OAuth2AccessTokenGenerator` generates an "opaque" (`OAuth2TokenFormat.REFER
 
 [NOTE]
 The `OAuth2TokenGenerator` is an *OPTIONAL* component and defaults to a `DelegatingOAuth2TokenGenerator` composed of an `OAuth2AccessTokenGenerator` and `OAuth2RefreshTokenGenerator`.
-As well, if a `JwtEncoder` `@Bean` or `JWKSource<SecurityContext>` `@Bean` is registered, then a `JwtGenerator` is additionally composed in the `DelegatingOAuth2TokenGenerator`.
+
+[NOTE]
+If a `JwtEncoder` `@Bean` or `JWKSource<SecurityContext>` `@Bean` is registered, then a `JwtGenerator` is additionally composed in the `DelegatingOAuth2TokenGenerator`.
 
 The `OAuth2TokenGenerator` provides great flexibility, as it can support any custom token format for `access_token` and `refresh_token`.
 
@@ -401,6 +409,9 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h
 }
 ----
 
+[NOTE]
+The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple configuration options simultaneously.
+
 [[oauth2-token-customizer]]
 == OAuth2TokenCustomizer
 
@@ -435,7 +446,7 @@ public OAuth2TokenCustomizer<OAuth2TokenClaimsContext> accessTokenCustomizer() {
 }
 ----
 
-[TIP]
+[NOTE]
 If the `OAuth2TokenGenerator` is not provided as a `@Bean` or is not configured through the `OAuth2AuthorizationServerConfigurer`, an `OAuth2TokenCustomizer<OAuth2TokenClaimsContext>` `@Bean` will automatically be configured with an `OAuth2AccessTokenGenerator`.
 
 An `OAuth2TokenCustomizer<JwtEncodingContext>` declared with a generic type of `JwtEncodingContext` (`implements OAuth2TokenContext`) provides the ability to customize the headers and claims of a `Jwt`.
@@ -473,5 +484,8 @@ public OAuth2TokenCustomizer<JwtEncodingContext> jwtCustomizer() {
 }
 ----
 
-[TIP]
+[NOTE]
 If the `OAuth2TokenGenerator` is not provided as a `@Bean` or is not configured through the `OAuth2AuthorizationServerConfigurer`, an `OAuth2TokenCustomizer<JwtEncodingContext>` `@Bean` will automatically be configured with a `JwtGenerator`.
+
+[TIP]
+For an example showing how you can xref:guides/how-to-userinfo.adoc#customize-id-token[customize the ID token], see the guide xref:guides/how-to-userinfo.adoc#how-to-userinfo[How-to: Customize the OpenID Connect 1.0 UserInfo response].

docs/src/docs/asciidoc/examples/src/main/java/sample/gettingStarted/SecurityConfig.java

@@ -53,12 +53,16 @@ public class SecurityConfig {
 
 	@Bean // <1>
 	@Order(1)
-	public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
+	public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http)
+			throws Exception {
 		OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(http);
 		// @formatter:off
 		http
+			// Redirect to the login page when not authenticated from the
+			// authorization endpoint
 			.exceptionHandling((exceptions) -> exceptions
-				.authenticationEntryPoint(new LoginUrlAuthenticationEntryPoint("/login"))
+				.authenticationEntryPoint(
+					new LoginUrlAuthenticationEntryPoint("/login"))
 			);
 		// @formatter:on
 
@@ -67,12 +71,15 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h
 
 	@Bean // <2>
 	@Order(2)
-	public SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http) throws Exception {
+	public SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http)
+			throws Exception {
 		// @formatter:off
 		http
 			.authorizeHttpRequests((authorize) -> authorize
 				.anyRequest().authenticated()
 			)
+			// Form login handles the redirect to the login page from the
+			// authorization server filter chain
 			.formLogin(Customizer.withDefaults());
 		// @formatter:on
 

docs/src/docs/asciidoc/getting-started.adoc

@@ -51,7 +51,7 @@ This is a minimal configuration for getting started quickly. To understand what
 
 <1> A Spring Security filter chain for the xref:protocol-endpoints.adoc[Protocol Endpoints].
 <2> A Spring Security filter chain for https://docs.spring.io/spring-security/reference/servlet/authentication/index.html[authentication].
-<3> An instance of `UserDetailsService` for retrieving users to authenticate.
+<3> An instance of {spring-security-api-base-url}/org/springframework/security/core/userdetails/UserDetailsService.html[`UserDetailsService`] for retrieving users to authenticate.
 <4> An instance of xref:core-components.adoc#registered-client-repository[`RegisteredClientRepository`] for managing clients.
 <5> An instance of `com.nimbusds.jose.jwk.source.JWKSource` for signing access tokens.
 <6> An instance of `java.security.KeyPair` with keys generated on startup used to create the `JWKSource` above.

docs/src/docs/asciidoc/guides/how-to-jpa.adoc

@@ -4,12 +4,14 @@
 :docs-dir: ..
 :examples-dir: ../examples
 
-[[getting-started]]
-== Getting Started
-
 This guide shows how to implement the xref:{docs-dir}/core-model-components.adoc#core-model-components[core services] of xref:{docs-dir}/index.adoc#top[Spring Authorization Server] with JPA.
 The purpose of this guide is to provide a starting point for implementing these services yourself, with the intention that you can make modifications to suit your needs.
 
+* <<define-data-model>>
+* <<create-jpa-entities>>
+* <<create-spring-data-repositories>>
+* <<implement-core-services>>
+
 [[define-data-model]]
 == Define the data model
 
@@ -20,6 +22,10 @@ NOTE: Except for token, state, metadata, settings, and claims values, we use the
 In reality, the length and even type of columns you use may need to be customized.
 You are encouraged to experiment and test before deploying to production.
 
+* <<client-schema>>
+* <<authorization-schema>>
+* <<authorization-consent-schema>>
+
 [[client-schema]]
 === Client Schema
 
@@ -69,6 +75,10 @@ The preceding schema examples provide a reference for the structure of the entit
 NOTE: The following entities are minimally annotated and are just examples.
 They allow the schema to be created dynamically and therefore do not require the above sql scripts to be executed manually.
 
+* <<client-entity>>
+* <<authorization-entity>>
+* <<authorization-consent-entity>>
+
 [[client-entity]]
 === Client Entity
 
@@ -107,6 +117,10 @@ include::{examples-dir}/src/main/java/sample/jpa/AuthorizationConsent.java[tag=c
 
 By closely examining the interfaces of each core service and reviewing the `Jdbc` implementations, we can derive a minimal set of queries needed for supporting a JPA version of each interface.
 
+* <<client-repository>>
+* <<authorization-repository>>
+* <<authorization-consent-repository>>
+
 [[client-repository]]
 === Client Repository
 
@@ -150,6 +164,10 @@ By reviewing the `Jdbc` implementations, we can derive a minimal set of internal
 CAUTION: Keep in mind that writing JSON data to text columns with a fixed length has proven problematic with the `Jdbc` implementations.
 While these examples continue to do so, you may need to split these fields out into a separate table or data store that supports arbitrarily long data values.
 
+* <<registered-client-repository>>
+* <<authorization-service>>
+* <<authorization-consent-service>>
+
 [[registered-client-repository]]
 === Registered Client Repository
 

docs/src/docs/asciidoc/guides/how-to-userinfo.adoc

@@ -3,23 +3,21 @@
 :index-link: ../how-to.html
 :docs-dir: ..
 
-[[getting-started]]
-== Getting Started
-
 This guide shows how to customize the xref:{docs-dir}/protocol-endpoints.adoc#oidc-user-info-endpoint[User Info endpoint] of the xref:{docs-dir}/index.adoc#top[Spring Authorization Server].
 The purpose of this guide is to demonstrate how to enable the endpoint and use the available customization options to produce a custom response.
 
+* <<enable-user-info>>
+* <<customize-user-info>>
+
 [[enable-user-info]]
 == Enable the User Info Endpoint
 
-Before customizing the response, you need to enable the User Info endpoint.
-In https://openid.net/specs/openid-connect-core-1_0.html#UserInfoRequest[Section 5.3.1], the OpenID Connect 1.0 Core specification states:
+The xref:{docs-dir}/protocol-endpoints.adoc#oidc-user-info-endpoint[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 Access Token obtained from an OpenID Connect Authentication Request MUST be sent as a Bearer Token, per Section 2 of https://openid.net/specs/openid-connect-core-1_0.html#RFC6750[OAuth 2.0 Bearer Token Usage] [RFC6750].
 
-The User Info endpoint requires an authenticated request using the access token (which is a JWT when using the xref:{docs-dir}/getting-started.adoc#sample.gettingStarted[Getting Started config]).
-
-The following listing shows how to configure https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html[Resource Server support] and provide a `JwtDecoder` that can validate the access token to allow authenticated requests to the User Info endpoint.
+Before customizing the response, you need to enable the User Info endpoint.
+The following listing shows how to enable the {spring-security-reference-base-url}/servlet/oauth2/resource-server/jwt.html[OAuth2 resource server configuration].
 
 [[sample.userinfo]]
 include::code:EnableUserInfoSecurityConfig[]
@@ -37,14 +35,17 @@ This configuration provides the following:
 
 The following sections describe some options for customizing the user info response.
 
+* <<customize-id-token>>
+* <<customize-user-info-mapper>>
+
 [[customize-id-token]]
 === Customize the ID Token
 
 By default, the user info response is generated by using claims from the `id_token` that are returned with the xref:{docs-dir}/protocol-endpoints.adoc#oauth2-token-endpoint[token response].
 Using the default strategy, https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims[standard claims] are returned only with the user info response based on the https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims[requested scopes] during authorization.
 
 The preferred way to customize the user info response is to add standard claims to the `id_token`.
-The following listing shows how add claims to the `id_token`.
+The following listing shows how to add claims to the `id_token`.
 
 [[sample.userinfo.idtoken]]
 include::code:IdTokenCustomizerConfig[]
@@ -83,7 +84,3 @@ Similar to the <<customize-id-token,example shown earlier>> where we customize c
 include::code:JwtTokenCustomizerConfig[]
 
 Whether you customize the user info response directly or use this example and customize the access token, you can look up information in a database, perform an LDAP query, make a request to another service, or use any other means of obtaining the information you want to be presented in the user info response.
-
-== Conclusion
-
-In this guide, you have learned how to <<enable-user-info,enable>> the xref:{docs-dir}/protocol-endpoints.adoc#oidc-user-info-endpoint[User Info endpoint] and explored various ways of customizing the response, including <<customize-id-token,customizing the ID token>> while continuing to use the built-in response and <<customize-user-info-mapper,customizing the response directly>> using a custom user info mapper.

docs/src/docs/asciidoc/how-to.adoc

@@ -2,18 +2,7 @@
 = "How-to" Guides
 
 [[how-to-overview]]
-== Overview
+== List of Guides
 
 * xref:guides/how-to-userinfo.adoc[Customize the OpenID Connect 1.0 UserInfo response]
 * xref:guides/how-to-jpa.adoc[Implement core services with JPA]
-
-[[how-to-coming-soon]]
-== Coming Soon
-
-* Authenticate using social login, e.g. Google (https://github.com/spring-projects/spring-authorization-server/issues/538[#538])
-* Authenticate a user in a Single Page Application with PKCE (https://github.com/spring-projects/spring-authorization-server/issues/539[#539])
-* Deny access for a revoked JWT access token (https://github.com/spring-projects/spring-authorization-server/issues/543[#543])
-* Provide a JWK source backed by a key rotation strategy (https://github.com/spring-projects/spring-authorization-server/issues/544[#544])
-* Customize form based login (https://github.com/spring-projects/spring-authorization-server/issues/533[#533])
-* Add a custom grant type (https://github.com/spring-projects/spring-authorization-server/issues/686[#686])
-* Authenticate a user with two-factor authentication (https://github.com/spring-projects/spring-authorization-server/issues/534[#534])

docs/src/docs/asciidoc/overview.adoc

@@ -1,7 +1,5 @@
 [[overview]]
 = Overview
-:toc: left
-:toclevels: 1
 
 This site contains reference documentation and how-to guides for Spring Authorization Server.