Editing pass for OAuth 2.0 Login ref doc

Fixes gh-4850

docs/manual/src/docs/asciidoc/index.adoc

@@ -1,5 +1,5 @@
 = Spring Security Reference
-Ben Alex; Luke Taylor; Rob Winch; Gunnar Hillert; Joe Grandja
+Ben Alex; Luke Taylor; Rob Winch; Gunnar Hillert; Joe Grandja; Jay Bryant
 :include-dir: _includes
 :security-api-url: http://docs.spring.io/spring-security/site/docs/current/apidocs/
 
@@ -342,21 +342,27 @@ LDAP authentication and provisioning code. Required if you need to use LDAP auth
 
 
 [[spring-security-oauth2-core]]
-===== OAuth 2.0 Core - spring-security-oauth2-core.jar
-Contains core classes and interfaces providing support for the _OAuth 2.0 Authorization Framework_ and _OpenID Connect Core 1.0_. Required by applications leveraging _OAuth 2.0_ and/or _OpenID Connect Core 1.0_, e.g. Client, Resource Server and Authorization Server. The top-level package is `org.springframework.security.oauth2.core`.
+===== OAuth 2.0 Core -- `spring-security-oauth2-core.jar`
+`spring-security-oauth2-core.jar` contains core classes and interfaces that provide support for the _OAuth 2.0 Authorization Framework_ and for _OpenID Connect Core 1.0_. It is required by applications that use _OAuth 2.0_ or _OpenID Connect Core 1.0_, such as Client, Resource Server, and Authorization Server. The top-level package is `org.springframework.security.oauth2.core`.
 
 
 [[spring-security-oauth2-client]]
-===== OAuth 2.0 Client - spring-security-oauth2-client.jar
-Spring Security's client support for _OAuth 2.0 Authorization Framework_ and _OpenID Connect Core 1.0_. Required by applications leveraging *OAuth 2.0 Login* and/or OAuth Client support. The top-level package is `org.springframework.security.oauth2.client`.
+===== OAuth 2.0 Client -- `spring-security-oauth2-client.jar`
+`spring-security-oauth2-client.jar` is Spring Security's client support for _OAuth 2.0 Authorization Framework_ and _OpenID Connect Core 1.0_. Required by applications leveraging *OAuth 2.0 Login* and/or OAuth Client support. The top-level package is `org.springframework.security.oauth2.client`.
 
 
 [[spring-security-oauth2-jose]]
-===== OAuth 2.0 JOSE - spring-security-oauth2-jose.jar
-Spring Security's support for the _JOSE_ framework (Javascript Object Signing and Encryption). The _JOSE_ framework is intended to provide a method to securely transfer claims between parties. It's comprised from a collection of specifications, specifically, JSON Web Token (JWT), JSON Web Signature (JWS), JSON Web Encryption (JWE) and JSON Web Key (JWK). Contains the top-level packages:
+===== OAuth 2.0 JOSE -- `spring-security-oauth2-jose.jar`
+`spring-security-oauth2-jose.jar` contains Spring Security's support for the _JOSE_ (Javascript Object Signing and Encryption) framework. The _JOSE_ framework is intended to provide a method to securely transfer claims between parties. It is built from a collection of specifications:
 
-* `org.springframework.security.oauth2.jwt`
+* JSON Web Token (JWT)
+* JSON Web Signature (JWS)
+* JSON Web Encryption (JWE)
+* JSON Web Key (JWK)
+
+It contains the top-level packages:
 
+* `org.springframework.security.oauth2.jwt`
 * `org.springframework.security.oauth2.jose`
 
 
@@ -863,10 +869,10 @@ From here you can easily make the changes to the defaults.
 [[jc-oauth2login]]
 === OAuth 2.0 Login
 
-The OAuth 2.0 Login feature essentially realizes the use case _"Login with Google"_ or _"Login with GitHub"_. It ultimately provides an application
-the capability to have users login to the application using their existing account at an OAuth 2.0 Provider (e.g. GitHub) or OpenID Connect 1.0 Provider (e.g. Google).
+The OAuth 2.0 Login feature implements the following use case: "Login with Google" or "Login with GitHub". It provides an application with
+the capability to have users log in to the application by using their existing account at an OAuth 2.0 Provider (e.g. GitHub) or OpenID Connect 1.0 Provider (such as Google).
 
-NOTE: OAuth 2.0 Login is realized using the *Authorization Code Grant*, as specified in the https://tools.ietf.org/html/rfc6749#section-4.1[OAuth 2.0 Authorization Framework]
+NOTE: OAuth 2.0 Login is implemented by using the *Authorization Code Grant*, as specified in the https://tools.ietf.org/html/rfc6749#section-4.1[OAuth 2.0 Authorization Framework]
 and http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[OpenID Connect Core 1.0].
 
 [[jc-oauth2login-sample-boot]]
@@ -874,38 +880,44 @@ and http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[OpenID Con
 
 Spring Boot 2.0 brings full auto-configuration capabilities for OAuth 2.0 Login.
 
-Let's jump right in and configure the {gh-samples-url}/boot/oauth2login[*OAuth 2.0 Login sample*] using _Google_ as the _Authentication Provider_.
+This section shows how to configure the {gh-samples-url}/boot/oauth2login[*OAuth 2.0 Login sample*] using _Google_ as the _Authentication Provider_ and covers the following topics:
+
+* <<jc-oauth2login-sample-initial-setup>>
+* <<jc-oauth2login-sample-redirect-uri>>
+* <<jc-oauth2login-sample-application-config>>
+* <<jc-oauth2login-sample-boot-application>>
+
 
 [[jc-oauth2login-sample-initial-setup]]
 ===== Initial setup
 
-In order to use Google's OAuth 2.0 authentication system for login, you must first set up a project in the *Google API Console* to obtain OAuth 2.0 credentials.
+To use Google's OAuth 2.0 authentication system for login, you must set up a project in the Google API Console to obtain OAuth 2.0 credentials.
 
 NOTE: https://developers.google.com/identity/protocols/OpenIDConnect[Google's OAuth 2.0 implementation] for authentication conforms to the
  http://openid.net/connect/[OpenID Connect 1.0] specification and is http://openid.net/certification/[OpenID Certified].
 
-Follow the instructions on the https://developers.google.com/identity/protocols/OpenIDConnect[OpenID Connect] page starting in the section *_"Setting up OAuth 2.0"_*.
+Follow the instructions on the https://developers.google.com/identity/protocols/OpenIDConnect[OpenID Connect] page, starting in the section, "Setting up OAuth 2.0".
 
-After completing the sub-section, *_"Obtain OAuth 2.0 credentials"_*, you should have created a new *OAuth Client* with credentials consisting of a *Client ID* and *Client Secret*.
+After completing the "Obtain OAuth 2.0 credentials" instructions, you should have a new OAuth Client with credentials consisting of a Client ID and a Client Secret.
 
 [[jc-oauth2login-sample-redirect-uri]]
 ===== Setting the redirect URI
 
 The redirect URI is the path in the application that the end-user's user-agent is redirected back to after they have authenticated with Google
-and have granted access to the OAuth Client _(<<jc-oauth2login-sample-initial-setup,created in previous step>>)_ on the *Consent screen* page.
+and have granted access to the OAuth Client _(<<jc-oauth2login-sample-initial-setup,created in the previous step>>)_ on the Consent page.
 
-For the sub-section, *_"Set a redirect URI"_*, ensure the *Authorized redirect URIs* is set to *_"http://localhost:8080/login/oauth2/code/google"_*.
+In the "Set a redirect URI" sub-section, ensure that the *Authorized redirect URIs* field is set to `http://localhost:8080/login/oauth2/code/google`.
 
-TIP: The default redirect URI template is *_{baseUrl}/login/oauth2/code/{registrationId}_*.
+TIP: The default redirect URI template is `{baseUrl}/login/oauth2/code/{registrationId}`.
  The *_registrationId_* is a unique identifier for the <<jc-oauth2login-client-registration,ClientRegistration>>.
 
 [[jc-oauth2login-sample-application-config]]
-===== Configure application.yml
-
-Now that you have created a new OAuth Client with Google, you need to configure the application to use the OAuth Client for the _authentication flow_.
+===== Configure `application.yml`
 
-Go to *application.yml* and set the following configuration:
+Now that you have a new OAuth Client with Google, you need to configure the application to use the OAuth Client for the _authentication flow_. To do so:
 
+. Go to `application.yml` and set the following configuration:
++
 [source,yaml]
 ----
 spring:
@@ -917,40 +929,40 @@ spring:
             client-id: google-client-id
             client-secret: google-client-secret
 ----
-
-Replace the values in the *client-id* and *client-secret* property with the OAuth 2.0 credentials created previously.
-
-[TIP]
++
 .OAuth Client properties
 ====
-<1> *_spring.security.oauth2.client.registration_* is the *base property prefix* for OAuth Client properties.
-<2> Following the *base property prefix* is the *_Id_* for the <<jc-oauth2login-client-registration,ClientRegistration>>, e.g. google.
+<1> `spring.security.oauth2.client.registration` is the base property prefix for OAuth Client properties.
+<2> Following the base property prefix is the ID for the <<jc-oauth2login-client-registration,ClientRegistration>>, such as google.
 ====
 
+. Replace the values in the `client-id` and `client-secret` property with the OAuth 2.0 credentials you created earlier.
+
+
 [[jc-oauth2login-sample-boot-application]]
 ===== Boot up the application
 
-Launch the Spring Boot 2.0 sample and go to *_"http://localhost:8080"_*.
-You'll then be redirected to the default _auto-generated_ login page displaying a link for Google.
+Launch the Spring Boot 2.0 sample and go to `http://localhost:8080`.
+You are then redirected to the default _auto-generated_ login page, which displays a link for Google.
 
-Click on the Google link and you'll then be redirected to Google for authentication.
+Click on the Google link, and you are then redirected to Google for authentication.
 
-After authenticating using your Google account credentials, the next page presented to you will be the *Consent screen*.
-The Consent screen will ask you to either *_Allow_* or *_Deny_* access to the OAuth Client you created previously.
-Click *_Allow_* to authorize the OAuth Client to access your _email address_ and _basic profile_ information.
+After authenticating with your Google account credentials, the next page presented to you is the Consent screen.
+The Consent screen asks you to either allow or deny access to the OAuth Client you created earlier.
+Click *Allow* to authorize the OAuth Client to access your email address and basic profile information.
 
-At this point, the OAuth Client will retrieve your _email address_ and _basic profile_ information
-from the http://openid.net/specs/openid-connect-core-1_0.html#UserInfo[*UserInfo Endpoint*] and establish an *_authenticated session_*.
+At this point, the OAuth Client retrieves your email address and basic profile information
+from the http://openid.net/specs/openid-connect-core-1_0.html#UserInfo[UserInfo Endpoint] and establish an authenticated session.
 
 [[jc-oauth2login-client-registration]]
 ==== ClientRegistration
 
 `ClientRegistration` is a representation of a client registered with an OAuth 2.0 or OpenID Connect 1.0 Provider.
 
-A client registration holds information such as _client id_, _client secret_,
-_authorization grant type_, _redirect uri_, _scope(s)_, _authorization uri_, _token uri_, etc.
+A client registration holds information, such as client id, client secret,
+authorization grant type, redirect URI, scope(s), authorization URI, _token URI, and other details.
 
-`ClientRegistration` and it's properties are defined as follows:
+`ClientRegistration` and its properties are defined as follows:
 
 [source,java]
 ----
@@ -979,92 +991,92 @@ public final class ClientRegistration {
 	}
 }
 ----
-<1> *registrationId* - the _Id_ that uniquely identifies the `ClientRegistration`.
-<2> *clientId* - the client identifier.
-<3> *clientSecret* - the client secret.
-<4> *clientAuthenticationMethod* - the method used to authenticate the Client with the Provider. Supported values are *basic* and *post*.
-<5> *authorizationGrantType* - the OAuth 2.0 Authorization Framework defines 4 https://tools.ietf.org/html/rfc6749#section-1.3[Authorization Grant] types.
- Supported values are *authorization_code* and *implicit*.
-<6> *redirectUriTemplate* - the client's _registered_ redirect URI that the _Authorization Server_ redirects the end-user's user-agent
+<1> `registrationId`: The ID that uniquely identifies the `ClientRegistration`.
+<2> `clientId`: The client identifier.
+<3> `clientSecret`: The client secret.
+<4> `clientAuthenticationMethod`: tThe method used to authenticate the Client with the Provider. The supported values are *basic* and *post*.
+<5> `authorizationGrantType`: The OAuth 2.0 Authorization Framework defines four https://tools.ietf.org/html/rfc6749#section-1.3[Authorization Grant] types.
+ The supported values are authorization_code and implicit.
+<6> `redirectUriTemplate`: The client's registered redirect URI that the _Authorization Server_ redirects the end-user's user-agent
  to after the end-user has authenticated and authorized access to the client.
- The default redirect URI template is *_{baseUrl}/login/oauth2/code/{registrationId}_*, which supports _URI template variables_.
-<7> *scopes* - the scope(s) requested by the client during the _Authorization Request_ flow, for example, openid, email, profile.
-<8> *clientName* - a descriptive name used for the client. The name may be used in certain scenarios, for example, when displaying the name of the client in the _auto-generated_ login page.
-<9> *authorizationUri* - the _Authorization Endpoint_ URI for the Authorization Server.
-<10> *tokenUri* - the _Token Endpoint_ URI for the Authorization Server.
-<11> *jwkSetUri* - the URI used to retrieve the https://tools.ietf.org/html/rfc7517[JSON Web Key (JWK)] Set from the Authorization Server,
- which contains the cryptographic key(s) used to verify the https://tools.ietf.org/html/rfc7515[JSON Web Signature (JWS)] of the *ID Token* and optionally the *UserInfo Response*.
-<12> *(userInfoEndpoint)uri* - the _UserInfo Endpoint_ URI used to access the claims/attributes of the authenticated end-user.
-<13> *userNameAttributeName* - the name of the attribute returned in the *UserInfo Response* that references the _Name_ or _Identifier_ of the end-user.
+ The default redirect URI template is `{baseUrl}/login/oauth2/code/{registrationId}`, which supports URI template variables.
+<7> `scopes`: The scope(s) requested by the client during the Authorization Request flow, such as openid, email, or profile.
+<8> `clientName`: A descriptive name used for the client. The name may be used in certain scenarios, such as when displaying the name of the client in the auto-generated login page.
+<9> `authorizationUri`: The Authorization Endpoint URI for the Authorization Server.
+<10> `tokenUri`: The Token Endpoint URI for the Authorization Server.
+<11> `jwkSetUri`: The URI used to retrieve the https://tools.ietf.org/html/rfc7517[JSON Web Key (JWK)] Set from the Authorization Server,
+ which contains the cryptographic key(s) used to verify the https://tools.ietf.org/html/rfc7515[JSON Web Signature (JWS)] of the ID Token and optionally the UserInfo Response.
+<12> `(userInfoEndpoint)uri`: The UserInfo Endpoint URI used to access the claims/attributes of the authenticated end-user.
+<13> `userNameAttributeName`: The name of the attribute returned in the UserInfo Response that references the Name or Identifier of the end-user.
 
 [[jc-oauth2login-boot-property-mappings]]
 ==== Spring Boot 2.0 Property Mappings
 
-The following table outlines the mapping of the Spring Boot 2.0 _OAuth Client_ properties to the `ClientRegistration` properties.
+The following table outlines the mapping of the Spring Boot 2.0 OAuth Client properties to the `ClientRegistration` properties.
 
 |===
 |Spring Boot 2.0 |ClientRegistration
 
-|spring.security.oauth2.client.registration._[registrationId]_
-|registrationId
+|`spring.security.oauth2.client.registration._[registrationId]_`
+|`registrationId`
 
-|spring.security.oauth2.client.registration._[registrationId]_.client-id
-|clientId
+|`spring.security.oauth2.client.registration._[registrationId]_.client-id`
+|`clientId`
 
-|spring.security.oauth2.client.registration._[registrationId]_.client-secret
-|clientSecret
+|`spring.security.oauth2.client.registration._[registrationId]_.client-secret`
+|`clientSecret`
 
-|spring.security.oauth2.client.registration._[registrationId]_.client-authentication-method
-|clientAuthenticationMethod
+|`spring.security.oauth2.client.registration._[registrationId]_.client-authentication-method`
+|`clientAuthenticationMethod`
 
-|spring.security.oauth2.client.registration._[registrationId]_.authorization-grant-type
-|authorizationGrantType
+|`spring.security.oauth2.client.registration._[registrationId]_.authorization-grant-type`
+|`authorizationGrantType`
 
-|spring.security.oauth2.client.registration._[registrationId]_.redirect-uri-template
-|redirectUriTemplate
+|`spring.security.oauth2.client.registration._[registrationId]_.redirect-uri-template`
+|`redirectUriTemplate`
 
-|spring.security.oauth2.client.registration._[registrationId]_.scope
-|scopes
+|`spring.security.oauth2.client.registration._[registrationId]_.scope`
+|`scopes`
 
-|spring.security.oauth2.client.registration._[registrationId]_.client-name
-|clientName
+|`spring.security.oauth2.client.registration._[registrationId]_.client-name`
+|`clientName`
 
-|spring.security.oauth2.client.provider._[providerId]_.authorization-uri
-|providerDetails.authorizationUri
+|`spring.security.oauth2.client.provider._[providerId]_.authorization-uri`
+|`providerDetails.authorizationUri`
 
-|spring.security.oauth2.client.provider._[providerId]_.token-uri
-|providerDetails.tokenUri
+|`spring.security.oauth2.client.provider._[providerId]_.token-uri`
+|`providerDetails.tokenUri`
 
-|spring.security.oauth2.client.provider._[providerId]_.jwk-set-uri
-|providerDetails.jwkSetUri
+|`spring.security.oauth2.client.provider._[providerId]_.jwk-set-uri`
+|`providerDetails.jwkSetUri`
 
-|spring.security.oauth2.client.provider._[providerId]_.user-info-uri
-|providerDetails.userInfoEndpoint.uri
+|`spring.security.oauth2.client.provider._[providerId]_.user-info-uri`
+|`providerDetails.userInfoEndpoint.uri`
 
-|spring.security.oauth2.client.provider._[providerId]_.userNameAttribute
-|providerDetails.userInfoEndpoint.userNameAttributeName
+|`spring.security.oauth2.client.provider._[providerId]_.userNameAttribute`
+|`providerDetails.userInfoEndpoint.userNameAttributeName`
 |===
 
 [[jc-oauth2login-client-registration-repo]]
 ==== ClientRegistrationRepository
 
-The `ClientRegistrationRepository` serves as a _repository_ for OAuth 2.0 / OpenID Connect 1.0 `ClientRegistration`(s).
+The `ClientRegistrationRepository` serves as a repository for OAuth 2.0 / OpenID Connect 1.0 `ClientRegistration`(s).
 
 [NOTE]
 Client registration information is ultimately stored and owned by the associated Authorization Server.
-This repository provides the capability to retrieve a _sub-set_ of the _primary_ client registration information
+This repository provides the ability to retrieve a sub-set of the primary client registration information,
 which is stored with the Authorization Server.
 
-Spring Boot 2.0 auto-configuration will _bind_ each of the properties based under *spring.security.oauth2.client.registration._[registrationId]_*
-to an instance of `ClientRegistration` and then compose each of the `ClientRegistration` instance(s) within a `ClientRegistrationRepository`.
+Spring Boot 2.0 auto-configuration binds each of the properties under spring.security.oauth2.client.registration._[registrationId]_
+to an instance of `ClientRegistration` and then composes each of the `ClientRegistration` instance(s) within a `ClientRegistrationRepository`.
 
 [NOTE]
 The default implementation of `ClientRegistrationRepository` is `InMemoryClientRegistrationRepository`.
 
-The auto-configuration will also register the `ClientRegistrationRepository` as a `@Bean` in the `ApplicationContext`
-so that it's available for dependency-injection, if needed by the application.
+The auto-configuration also registers the `ClientRegistrationRepository` as a `@Bean` in the `ApplicationContext`
+so that it is available for dependency-injection, if needed by the application.
 
-For example:
+The following listing shows an example:
 
 [source,java]
 ----
@@ -1089,14 +1101,14 @@ public class MainController {
 [[jc-oauth2login-common-oauth2-provider]]
 ==== CommonOAuth2Provider
 
-`CommonOAuth2Provider` pre-defines a set of default client properties for a number of _well-known_ Providers, specifically, Google, GitHub, Facebook and Okta.
+`CommonOAuth2Provider` pre-defines a set of default client properties for a number of well known providers: Google, GitHub, Facebook, and Okta.
 
-For example, the _authorization-uri_, _token-uri_ and _user-info-uri_ does not change often for a Provider and therefore it makes sense to
-provide default values in order to reduce the configuration required.
+For example, the `authorization-uri`, `token-uri`, and `user-info-uri` do not change often for a Provider. Therefore, it makes sense to
+provide default values in order to reduce the required configuration.
 
-As demonstrated previously, when we <<jc-oauth2login-sample-application-config,configured a Google client>>, only the *client-id* and *client-secret* properties were required.
+As demonstrated previously, when we <<jc-oauth2login-sample-application-config,configured a Google client>>, only the `client-id` and `client-secret` properties are required.
 
-For example:
+The following listing shows an example:
 
 [source,yaml]
 ----
@@ -1111,12 +1123,12 @@ spring:
 ----
 
 [TIP]
-The _auto-defaulting_ of client properties seamlessly works here because the *registrationId* (google) matches the `GOOGLE` `enum` (case-insensitive) in `CommonOAuth2Provider`.
+The auto-defaulting of client properties works seamlessly here because the `registrationId` (`google`) matches the `GOOGLE` `enum` (case-insensitive) in `CommonOAuth2Provider`.
 
-For cases where you may want to specify a different *registrationId*, for example, *google-login*,
-you can still leverage _auto-defaulting_ of client properties by configuring the *provider* property.
+For cases where you may want to specify a different `registrationId`, such as `google-login`,
+you can still leverage auto-defaulting of client properties by configuring the `provider` property.
 
-For example:
+The following listing shows an example:
 
 [source,yaml]
 ----
@@ -1130,19 +1142,19 @@ spring:
             client-id: google-client-id
             client-secret: google-client-secret
 ----
-<1> The *registrationId* is set to *google-login*.
-<2> The *provider* property is set to *google*, which will leverage the _auto-defaulting_ of client properties set in `CommonOAuth2Provider.GOOGLE.getBuilder()`.
+<1> The `registrationId` is set to `google-login`.
+<2> The `provider` property is set to `google`, which relies on the auto-defaulting of client properties set in `CommonOAuth2Provider.GOOGLE.getBuilder()`.
 
 [[jc-oauth2login-custom-provider-properties]]
 ==== Configuring Custom Provider Properties
 
-There are some OAuth 2.0 Providers that support _multi-tenancy_, which results in different _Protocol Endpoints_ for each tenant (or sub-domain).
+There are some OAuth 2.0 Providers that support multi-tenancy, which results in different protocol endpoints for each tenant (or sub-domain).
 
-For example, an OAuth Client registered with Okta is assigned to a specific _sub-domain_ and have their own _Protocol Endpoints_.
+For example, an OAuth Client registered with Okta is assigned to a specific sub-domain and have their own protocol endpoints.
 
-For these cases, Spring Boot 2.0 provides the base property *spring.security.oauth2.client.provider._[providerId]_* for configuring custom Provider properties.
+For these cases, Spring Boot 2.0 provides the following base property for configuring custom provider properties: `spring.security.oauth2.client.provider.providerId`.
 
-For example:
+The following listing shows an example:
 
 [source,yaml]
 ----
@@ -1163,7 +1175,7 @@ spring:
             jwk-set-uri: https://your-subdomain.oktapreview.com/oauth2/v1/keys
 ----
 
-<1> The base property *spring.security.oauth2.client.provider.okta* allows for custom configuration of _Protocol Endpoint_ locations.
+<1> The base property (`spring.security.oauth2.client.provider.okta`) allows for custom configuration of protocol endpoint locations.
 
 [[jc-oauth2login-override-boot-autoconfig]]
 ==== Overriding Spring Boot 2.0 Auto-configuration
@@ -1172,12 +1184,20 @@ The Spring Boot 2.0 Auto-configuration class for OAuth Client support is `OAuth2
 
 It performs the following tasks:
 
-. Registers a `ClientRegistrationRepository` `@Bean` composed of `ClientRegistration`(s) from the configured OAuth Client properties.
-. Provides a `WebSecurityConfigurerAdapter` `@Configuration` and enables OAuth 2.0 Login via `httpSecurity.oauth2Login()`.
+* Registers a `ClientRegistrationRepository` `@Bean` composed of `ClientRegistration`(s) from the configured OAuth Client properties.
+* Provides a `WebSecurityConfigurerAdapter` `@Configuration` and enables OAuth 2.0 Login through `httpSecurity.oauth2Login()`.
+
+If you need to override the auto-configuration based on your specific requirements, you may do so in the following ways:
+
+* <<jc-oauth2login-register-clientregistrationrepository-bean>>
+* <<jc-oauth2login-provide-websecurityconfigureradapter>>
+* <<jc-oauth2login-completely-override-autoconfiguration>>
 
-If you need to override the Auto-configuration based on your specific requirements, you may do so in the following ways.
 
-- Register a `ClientRegistrationRepository` `@Bean`.
+[[jc-oauth2login-register-clientregistrationrepository-bean]]
+===== Register a `ClientRegistrationRepository` `@Bean`
+
+The following example shows how to register a `ClientRegistrationRepository` `@Bean`:
 
 [source,java]
 ----
@@ -1208,7 +1228,11 @@ public class OAuth2LoginConfig {
 }
 ----
 
-- Provide a `WebSecurityConfigurerAdapter` with `@EnableWebSecurity` and enable OAuth 2.0 Login via `httpSecurity.oauth2Login()`.
+
+[[jc-oauth2login-provide-websecurityconfigureradapter]]
+===== Provide a `WebSecurityConfigurerAdapter`
+
+The following example shows how to provide a `WebSecurityConfigurerAdapter` with `@EnableWebSecurity` and enable OAuth 2.0 login through `httpSecurity.oauth2Login()`:
 
 [source,java]
 ----
@@ -1226,7 +1250,11 @@ public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
 }
 ----
 
-- Completely override the Auto-configuration by doing both, as per above.
+
+[[jc-oauth2login-completely-override-autoconfiguration]]
+Completely Override the Auto-configuration
+
+The following example shows how to completely override the auto-configuration by both registering a `ClientRegistrationRepository` `@Bean` and providing a `WebSecurityConfigurerAdapter`, both of which were described in the two preceding sections.
 
 [source,java]
 ----
@@ -1273,8 +1301,8 @@ public class OAuth2LoginConfig {
 [[jc-oauth2login-javaconfig-wo-boot]]
 ==== Java Configuration without Spring Boot 2.0
 
-If you are not able to use Spring Boot 2.0 and would like to configure one of the _pre-defined_ Providers in `CommonOAuth2Provider`,
-for example Google, the following configuration can be applied:
+If you are not able to use Spring Boot 2.0 and would like to configure one of the pre-defined providers in `CommonOAuth2Provider`
+(for example, Google), apply the following configuration:
 
 [source,java]
 ----
@@ -1316,23 +1344,23 @@ public class OAuth2LoginConfig {
 [[jc-oauth2login-authorized-client]]
 ==== OAuth2AuthorizedClient / OAuth2AuthorizedClientService
 
-`OAuth2AuthorizedClient` is a representation of an *_Authorized Client_*.
-A client is considered _authorized_ when the end-user _(Resource Owner)_ has granted authorization to the client to access it's protected resources.
+`OAuth2AuthorizedClient` is a representation of an Authorized Client.
+A client is considered to be authorized when the end-user (Resource Owner) has granted authorization to the client to access its protected resources.
 
-`OAuth2AuthorizedClient` serves the purpose of associating an `OAuth2AccessToken` to a `ClientRegistration` _(Client)_ and _Resource Owner_,
+`OAuth2AuthorizedClient` serves the purpose of associating an `OAuth2AccessToken` to a `ClientRegistration` (client) and resource owner,
 who is the `Principal` end-user that granted the authorization.
 
 The primary role of the `OAuth2AuthorizedClientService` is to manage `OAuth2AuthorizedClient` instances.
-From a developer perspective, it provides the capability to lookup an `OAuth2AccessToken` associated to a _Client_
-so that it may be used to initiate a request to a _Resource Server_.
+From a developer perspective, it provides the capability to lookup an `OAuth2AccessToken` associated with a client
+so that it may be used to initiate a request to a resource server.
 
 [NOTE]
 Spring Boot 2.0 Auto-configuration registers an `OAuth2AuthorizedClientService` `@Bean` in the `ApplicationContext`.
 
 The developer may also register an `OAuth2AuthorizedClientService` `@Bean` in the `ApplicationContext` (overriding Spring Boot 2.0 Auto-configuration)
-in order to have the ability to lookup an `OAuth2AccessToken` associated to a specific `ClientRegistration` _(Client)_.
+in order to have the ability to lookup an `OAuth2AccessToken` associated with a specific `ClientRegistration` (client).
 
-For example:
+The following listing shows an example:
 
 [source,java]
 ----
@@ -1360,17 +1388,19 @@ public class MainController {
 }
 ----
 
+
 [[jc-oauth2login-resources]]
 ==== Additional Resources
 
-===== Advanced Configuration
+The following additional resources describe advanced configuration options:
+
 * <<oauth2login-advanced-login-page, OAuth 2.0 Login Page>>
-* Authorization Endpoint
+* Authorization Endpoint:
 ** <<oauth2login-advanced-authorization-request-repository, AuthorizationRequestRepository>>
 * <<oauth2login-advanced-redirection-endpoint, Redirection Endpoint>>
-* Token Endpoint
+* Token Endpoint:
 ** <<oauth2login-advanced-token-client, OAuth2AccessTokenResponseClient>>
-* UserInfo Endpoint
+* UserInfo Endpoint:
 ** <<oauth2login-advanced-map-authorities, Mapping User Authorities>>
 ** <<oauth2login-advanced-custom-user, Configuring a Custom OAuth2User>>
 ** <<oauth2login-advanced-oauth2-user-service, OAuth 2.0 UserService>>
@@ -6546,14 +6576,17 @@ By default, the user authorities are obtained from the `memberOf` attribute valu
 By default, a failed result will cause a standard Spring Security `BadCredentialsException`. If you set the property `convertSubErrorCodesToExceptions` to `true`, the exception messages will be parsed to attempt to extract the Active Directory-specific error code and raise a more specific exception. Check the class Javadoc for more information.
 
 [[oauth2login-advanced]]
-== OAuth 2.0 Login - Advanced Configuration
+== OAuth 2.0 Login -- Advanced Configuration
 
 `HttpSecurity.oauth2Login()` (`OAuth2LoginConfigurer`) provides a number of configuration options for customizing OAuth 2.0 Login.
-The main configuration options are grouped into their _Protocol Endpoint_ counterparts.
+The main configuration options are grouped into their protocol endpoint counterparts.
+//TODO What is the relationship of `HttpSecurity.oauth2Login` to `OAuth2LoginConfigurer`?
 
 For example, `oauth2Login().authorizationEndpoint()` allows configuring the _Authorization Endpoint_,
 whereas `oauth2Login().tokenEndpoint()` allows configuring the _Token Endpoint_.
 
+The following code shows an example:
+
 [source,java]
 ----
 @EnableWebSecurity
@@ -6575,28 +6608,28 @@ public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
 }
 ----
 
-The main goal of the `oauth2Login()` DSL was to closely align with the naming as defined in the specifications.
+The main goal of the `oauth2Login()` DSL was to closely align with the naming, as defined in the specifications.
 
-The *OAuth 2.0 Authorization Framework* defines the https://tools.ietf.org/html/rfc6749#section-3[Protocol Endpoints] as follows:
+The OAuth 2.0 Authorization Framework defines the https://tools.ietf.org/html/rfc6749#section-3[Protocol Endpoints].
 
-The authorization process utilizes two authorization server endpoints (HTTP resources):
+The authorization process uses two authorization server endpoints (HTTP resources):
 
-- *Authorization Endpoint* - used by the client to obtain authorization from the resource owner via user-agent redirection.
-- *Token Endpoint* - used by the client to exchange an authorization grant for an access token, typically with client authentication.
+* Authorization Endpoint: Used by the client to obtain authorization from the resource owner through user-agent redirection.
+* Token Endpoint: Used by the client to exchange an authorization grant for an access token, typically with client authentication.
 
-As well as one client endpoint:
+It also uses one client endpoint:
 
-- *Redirection Endpoint* - used by the authorization server to return responses
-containing authorization credentials to the client via the resource owner user-agent.
+* Redirection Endpoint: Used by the authorization server to return responses
+containing authorization credentials to the client through the resource owner user-agent.
 
-The *OpenID Connect Core 1.0* specification defines the http://openid.net/specs/openid-connect-core-1_0.html#UserInfo[UserInfo Endpoint] as follows:
+The OpenID Connect Core 1.0 specification defines the http://openid.net/specs/openid-connect-core-1_0.html#UserInfo[UserInfo Endpoint] as follows:
 
-The *UserInfo Endpoint* is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User.
-To obtain the requested Claims about the End-User, the Client makes a request to the UserInfo Endpoint
-using an Access Token obtained through OpenID Connect Authentication.
-These Claims are normally represented by a JSON object that contains a collection of name and value pairs for the Claims.
+The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns claims about the authenticated end-user.
+To obtain the requested claims about the end-user, the client makes a request to the `UserInfo` endpoint
+by using an access token obtained through OpenID Connect Authentication.
+These claims are normally represented by a JSON object that contains a collection of name-value pairs for the claims.
 
-The complete configuration options available for the `oauth2Login()` DSL is as follows:
+The following code shows the complete configuration options available for the `oauth2Login()` DSL:
 
 [source,java]
 ----
@@ -6629,30 +6662,37 @@ public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
 }
 ----
 
-The sections to follow will go more into detail on each of the configuration options available.
+The sections to follow go into more detail on each of the configuration options available:
+
+* <<oauth2login-advanced-login-page>>
+* <<oauth2login-advanced-authorization-endpoint>>
+* <<oauth2login-advanced-redirection-endpoint>>
+* <<oauth2login-advanced-token-endpoint>>
+* <<oauth2login-advanced-userinfo-endpoint>>
+
 
 [[oauth2login-advanced-login-page]]
 === OAuth 2.0 Login Page
 
-By default, the OAuth 2.0 Login Page will be _auto-generated_ by the `DefaultLoginPageGeneratingFilter`.
-The default login page will display each configured OAuth Client with it's `ClientRegistration.clientName`
-as a link, that is capable of initiating the _Authorization Request_ (or OAuth 2.0 Login).
+By default, the OAuth 2.0 Login Page is auto-generated by the `DefaultLoginPageGeneratingFilter`.
+The default login page shows each configured OAuth Client with its `ClientRegistration.clientName`
+as a link, which is capable of initiating the Authorization Request (or OAuth 2.0 Login).
 
 The link's destination for each OAuth Client defaults to the following:
 
 `OAuth2AuthorizationRequestRedirectFilter.DEFAULT_AUTHORIZATION_REQUEST_BASE_URI` + "/{registrationId}"
 
-For example:
+The following line shows an example:
 
 [source,html]
 ----
 <a href="/oauth2/authorization/google">Google</a>
 ----
 
-If you would like to override the default login page,
-you need to configure `oauth2Login().loginPage()` and optionally `oauth2Login().authorizationEndpoint().baseUri()`.
+To override the default login page,
+configure `oauth2Login().loginPage()` and (optionally) `oauth2Login().authorizationEndpoint().baseUri()`.
 
-For example:
+The following listing shows an example:
 
 [source,java]
 ----
@@ -6673,14 +6713,14 @@ public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
 ----
 
 [IMPORTANT]
-You will need to provide a `@Controller` with a `@RequestMapping("/login/oauth2")` that is capable of rendering the custom login page.
+You need to provide a `@Controller` with a `@RequestMapping("/login/oauth2")` that is capable of rendering the custom login page.
 
 [TIP]
 ====
-As noted, configuring `oauth2Login().authorizationEndpoint().baseUri()` is optional.
+As noted earlier, configuring `oauth2Login().authorizationEndpoint().baseUri()` is optional.
 However, if you choose to customize it, ensure the link to each OAuth Client matches the `authorizationEndpoint().baseUri()`.
 
-For example:
+The following line shows an example:
 
 [source,html]
 ----
@@ -6691,22 +6731,26 @@ For example:
 [[oauth2login-advanced-authorization-endpoint]]
 === Authorization Endpoint
 
+The authorization endpoint works through the `AuthorizationRequestRepository`, as described in the next sub-section.
+//TODO Is there more to the Authorization Endpoint than the repository? If so, those details should be added to this section.
+
+
 [[oauth2login-advanced-authorization-request-repository]]
-==== AuthorizationRequestRepository
+==== `AuthorizationRequestRepository`
 
 `AuthorizationRequestRepository` is responsible for the persistence of the `OAuth2AuthorizationRequest`
-from the time the _Authorization Request_ is initiated to the time the _Authorization Response_
-is received (_the callback_).
+from the time the Authorization Request is initiated to the time the Authorization Response
+is received (the callback).
 
 [TIP]
-The `OAuth2AuthorizationRequest` is used to correlate and validate the _Authorization Response_.
+The `OAuth2AuthorizationRequest` is used to correlate and validate the Authorization Response.
 
 The default implementation of `AuthorizationRequestRepository` is `HttpSessionOAuth2AuthorizationRequestRepository`,
 which stores the `OAuth2AuthorizationRequest` in the `HttpSession`.
 
 If you would like to provide a custom implementation of `AuthorizationRequestRepository`
 that stores the attributes of `OAuth2AuthorizationRequest` in a `Cookie`,
-you may configure it as follows:
+configure it as shown in the following example:
 
 [source,java]
 ----
@@ -6731,15 +6775,15 @@ public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
 [[oauth2login-advanced-redirection-endpoint]]
 === Redirection Endpoint
 
-The Redirection Endpoint is used by the Authorization Server for returning the _Authorization Response_
+The Redirection Endpoint is used by the Authorization Server for returning the Authorization Response
 (which contains the authorization credentials) to the client via the Resource Owner user-agent.
 
 [TIP]
-OAuth 2.0 Login leverages the *Authorization Code Grant*, therefore the authorization credential is the _authorization code_.
+OAuth 2.0 Login leverages the Authorization Code Grant. Therefore, the authorization credential is the authorization code.
 
-The default _Authorization Response_ `baseUri` (Redirection Endpoint) is */login/oauth2/code/**, which is defined in `OAuth2LoginAuthenticationFilter.DEFAULT_FILTER_PROCESSES_URI`.
+The default Authorization Response `baseUri` (redirection endpoint) is `*/login/oauth2/code/**`, which is defined in `OAuth2LoginAuthenticationFilter.DEFAULT_FILTER_PROCESSES_URI`.
 
-If you would like to customize the _Authorization Response_ `baseUri`, you may configure it as follows:
+If you would like to customize the _Authorization Response_ `baseUri`, configure it as shown in the following example:
 
 [source,java]
 ----
@@ -6759,9 +6803,9 @@ public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
 
 [IMPORTANT]
 ====
-You will also need to ensure the `ClientRegistration.redirectUriTemplate` matches this custom _Authorization Response_ `baseUri`.
+You also need to ensure the `ClientRegistration.redirectUriTemplate` matches the custom Authorization Response `baseUri`.
 
-For example:
+The following listing shows an example:
 
 [source,java]
 ----
@@ -6776,21 +6820,25 @@ return CommonOAuth2Provider.GOOGLE.getBuilder("google")
 [[oauth2login-advanced-token-endpoint]]
 === Token Endpoint
 
+The token endpoint works through the `OAuth2AccessTokenResponseClient`, as described in the next sub-section.
+//TODO Is there more to the token Endpoint than the response client? If so, those details should be added to this section.
+
+
 [[oauth2login-advanced-token-client]]
 ==== OAuth2AccessTokenResponseClient
 
-`OAuth2AccessTokenResponseClient` is responsible for *_exchanging_* an *Authorization Grant* credential
-for an *Access Token* credential at the Authorization Server's _Token Endpoint_.
+`OAuth2AccessTokenResponseClient` is responsible for exchanging an authorization grant credential
+for an access token credential at the Authorization Server's token endpoint.
 
 The default implementation of `OAuth2AccessTokenResponseClient` is `NimbusAuthorizationCodeTokenResponseClient`,
-which *_exchanges_* an *Authorization Code* for an *Access Token* at the _Token Endpoint_.
+which exchanges an authorization code for an access token at the Token Endpoint.
 
 [NOTE]
-`NimbusAuthorizationCodeTokenResponseClient` leverages the https://connect2id.com/products/nimbus-oauth-openid-connect-sdk[Nimbus OAuth 2.0 SDK] internally.
+`NimbusAuthorizationCodeTokenResponseClient` uses the https://connect2id.com/products/nimbus-oauth-openid-connect-sdk[Nimbus OAuth 2.0 SDK] internally.
 
 If you would like to provide a custom implementation of `OAuth2AccessTokenResponseClient`
-that uses _Spring Framework 5_ reactive `WebClient` for initiating requests to the _Token Endpoint_,
-you may configure it as follows:
+that uses Spring Framework 5 reactive `WebClient` for initiating requests to the token endpoint,
+configure it as shown in the following example:
 
 [source,java]
 ----
@@ -6813,19 +6861,27 @@ public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
 ----
 
 [[oauth2login-advanced-userinfo-endpoint]]
-=== UserInfo Endpoint
+=== `UserInfo` Endpoint
+
+The `UserInfo` endpoint includes a number of configuration options, as described in the following sub-sections:
+
+* <<oauth2login-advanced-map-authorities>>
+* <<oauth2login-advanced-custom-user>>
+* <<oauth2login-advanced-oauth2-user-service>>
+* <<oauth2login-advanced-oidc-user-service>>
+
 
 [[oauth2login-advanced-map-authorities]]
 ==== Mapping User Authorities
 
 After the user successfully authenticates with the OAuth 2.0 Provider,
-the `OAuth2User.getAuthorities()` may be mapped to a new set of `GrantedAuthority`(s), which will then be supplied to `OAuth2AuthenticationToken`.
+the `OAuth2User.getAuthorities()` may be mapped to a new set of `GrantedAuthority` instances, which are then supplied to `OAuth2AuthenticationToken`.
 
 [TIP]
-`OAuth2AuthenticationToken.getAuthorities()` is used for authorizing requests, for example, `hasRole('USER')` or `hasRole('ADMIN')`.
+`OAuth2AuthenticationToken.getAuthorities()` is used for authorizing requests, such as in `hasRole('USER')` or `hasRole('ADMIN')`.
 
 In order to map user authorities, you need to provide an implementation of `GrantedAuthoritiesMapper`
-and configure it as follows:
+and configure it as shown in the following example:
 
 [source,java]
 ----
@@ -6876,12 +6932,12 @@ public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
 ==== Configuring a Custom OAuth2User
 
 `CustomUserTypesOAuth2UserService` is an implementation of an `OAuth2UserService`
-which provides support for custom `OAuth2User` types.
+that provides support for custom `OAuth2User` types.
 
-There may be a use case where you would like to define your own implementation of `OAuth2User`
-as the default implementation (`DefaultOAuth2User`) may not suit your needs.
+If the default implementation (`DefaultOAuth2User`) may not suit your needs, you may need
+to define your own implementation of `OAuth2User`.
 
-The following code demonstrates how you would register a custom `OAuth2User` type for *GitHub*.
+The following code demonstrates how you would register a custom `OAuth2User` type for GitHub:
 
 [source,java]
 ----
@@ -6899,7 +6955,7 @@ public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
 }
 ----
 
-The custom `OAuth2User` type for GitHub is defined as follows:
+The following code shows an example of a custom `OAuth2User` type for GitHub:
 
 [source,java]
 ----
@@ -6965,26 +7021,26 @@ public class GitHubOAuth2User implements OAuth2User {
 ----
 
 [TIP]
-_id_, _name_, _login_ and _email_ are attributes returned in GitHub's *UserInfo Response*.
-For detailed information returned from the *UserInfo Endpoint* see the API documentation
-for https://developer.github.com/v3/users/#get-the-authenticated-user[Get the authenticated user].
+`id`, `name`, `login`, and `email` are attributes returned in GitHub's UserInfo Response.
+For detailed information returned from the `UserInfo` endpoint, see the API documentation
+for https://developer.github.com/v3/users/#get-the-authenticated-user["Get the authenticated user"].
 
 [[oauth2login-advanced-oauth2-user-service]]
 ==== OAuth 2.0 UserService
 
 `DefaultOAuth2UserService` is an implementation of an `OAuth2UserService`
-that supports standard OAuth 2.0 Provider's.
+that supports standard OAuth 2.0 Provider instances.
 
 [NOTE]
-`OAuth2UserService` is responsible for obtaining the user attributes
-of the end-user (_Resource Owner_) from the UserInfo Endpoint (using the
-_Access Token_ granted to the client during the _Authorization Flow_)
-and return an `AuthenticatedPrincipal` in the form of an `OAuth2User`.
+`OAuth2UserService` obtains the user attributes
+of the end-user (the resource owner) from the `UserInfo` endpoint (by using the
+access token granted to the client during the authorization flow)
+and returns an `AuthenticatedPrincipal` in the form of an `OAuth2User`.
 
-There may be a use case where you need to define your own implementation of `OAuth2UserService`
-for standard OAuth 2.0 Provider's if the default implementation does not suit your needs.
+If the default implementation does not suit your needs, you may need to define your own implementation of `OAuth2UserService`
+for standard OAuth 2.0 Provider instances.
 
-The following configuration demonstrates how to configure a custom `OAuth2UserService`.
+The following configuration demonstrates how to configure a custom `OAuth2UserService`:
 
 [source,java]
 ----
@@ -7014,14 +7070,14 @@ that supports OpenID Connect 1.0 Provider's.
 
 [NOTE]
 `OAuth2UserService` is responsible for obtaining the user attributes
-of the end-user (_Resource Owner_) from the UserInfo Endpoint (using the
-_Access Token_ granted to the client during the _Authorization Flow_)
+of the end user (the resource owner) from the `UserInfo` endpoint (byusing the
+access token granted to the client during the authorization flow)
 and return an `AuthenticatedPrincipal` in the form of an `OidcUser`.
 
-There may be a use case where you need to define your own implementation of `OAuth2UserService`
-for OpenID Connect 1.0 Provider's if the default implementation does not suit your needs.
+If the default implementation does not suit your needs, you can define your own implementation of `OAuth2UserService`
+for OpenID Connect 1.0 Provider's.
 
-The following configuration demonstrates how to configure a custom OpenID Connect 1.0 `OAuth2UserService`.
+The following configuration demonstrates how to configure a custom OpenID Connect 1.0 `OAuth2UserService`:
 
 [source,java]
 ----