diff --git a/docs/manual/src/docs/asciidoc/index.adoc b/docs/manual/src/docs/asciidoc/index.adoc index 553bd45501..02620b7b03 100644 --- a/docs/manual/src/docs/asciidoc/index.adoc +++ b/docs/manual/src/docs/asciidoc/index.adoc @@ -342,17 +342,17 @@ 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` +===== 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` +===== 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` +===== 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: * JSON Web Token (JWT) @@ -869,8 +869,9 @@ From here you can easily make the changes to the defaults. [[jc-oauth2login]] === OAuth 2.0 Login -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). +The OAuth 2.0 Login feature 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). +OAuth 2.0 Login implements the use cases: "Login with Google" or "Login with GitHub". 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]. @@ -882,10 +883,10 @@ Spring Boot 2.0 brings full auto-configuration capabilities for OAuth 2.0 Login. 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]] @@ -952,7 +953,7 @@ The Consent screen asks you to either allow or deny access to the OAuth Client y Click *Allow* to authorize the OAuth Client to access your email address and basic profile information. 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. +from the http://openid.net/specs/openid-connect-core-1_0.html#UserInfo[UserInfo Endpoint] and establishes an authenticated session. [[jc-oauth2login-client-registration]] ==== ClientRegistration @@ -960,7 +961,7 @@ from the http://openid.net/specs/openid-connect-core-1_0.html#UserInfo[UserInfo `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, and other details. +authorization grant type, redirect URI, scope(s), authorization URI, token URI, and other details. `ClientRegistration` and its properties are defined as follows: @@ -994,7 +995,7 @@ 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`: tThe method used to authenticate the Client with the Provider. The supported values are *basic* and *post*. +<4> `clientAuthenticationMethod`: The 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 @@ -1067,7 +1068,7 @@ Client registration information is ultimately stored and owned by the associated 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 binds each of the properties under spring.security.oauth2.client.registration._[registrationId]_ +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] @@ -1143,7 +1144,7 @@ spring: client-secret: google-client-secret ---- <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()`. +<2> The `provider` property is set to `google`, which will leverage the auto-defaulting of client properties set in `CommonOAuth2Provider.GOOGLE.getBuilder()`. [[jc-oauth2login-custom-provider-properties]] ==== Configuring Custom Provider Properties @@ -1152,7 +1153,7 @@ There are some OAuth 2.0 Providers that support multi-tenancy, which results in 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 following base property for configuring custom provider properties: `spring.security.oauth2.client.provider.providerId`. +For these cases, Spring Boot 2.0 provides the following base property for configuring custom provider properties: `spring.security.oauth2.client.provider._[providerId]_`. The following listing shows an example: @@ -1189,9 +1190,9 @@ It performs the following tasks: 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]] @@ -1252,7 +1253,7 @@ public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter { [[jc-oauth2login-completely-override-autoconfiguration]] -Completely Override the Auto-configuration +===== 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. @@ -6578,9 +6579,8 @@ By default, a failed result will cause a standard Spring Security `BadCredential [[oauth2login-advanced]] == OAuth 2.0 Login -- Advanced Configuration -`HttpSecurity.oauth2Login()` (`OAuth2LoginConfigurer`) provides a number of configuration options for customizing OAuth 2.0 Login. +`HttpSecurity.oauth2Login()` provides a number of configuration options for customizing OAuth 2.0 Login. 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_. @@ -6610,22 +6610,22 @@ 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 OAuth 2.0 Authorization Framework defines the https://tools.ietf.org/html/rfc6749#section-3[Protocol Endpoints]. +The OAuth 2.0 Authorization Framework defines the https://tools.ietf.org/html/rfc6749#section-3[Protocol Endpoints] as follows: -The authorization process uses two authorization server endpoints (HTTP resources): +The authorization process utilizes two authorization server endpoints (HTTP resources): -* Authorization Endpoint: Used by the client to obtain authorization from the resource owner through user-agent redirection. +* 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. -It also uses one client endpoint: +As well as one client endpoint: * Redirection Endpoint: Used by the authorization server to return responses -containing authorization credentials to the client through the resource owner user-agent. +containing authorization credentials to the client via 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 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 +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. @@ -6731,9 +6731,6 @@ The following line shows an 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` @@ -6783,7 +6780,7 @@ OAuth 2.0 Login leverages the Authorization Code Grant. Therefore, the authoriza 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`, configure it as shown in the following example: +If you would like to customize the Authorization Response `baseUri`, configure it as shown in the following example: [source,java] ---- @@ -6820,15 +6817,12 @@ 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. +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. @@ -6837,7 +6831,7 @@ which exchanges an authorization code for an access token at the Token Endpoint. `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, +that uses Spring Framework 5 reactive `WebClient` for initiating requests to the Token Endpoint, configure it as shown in the following example: [source,java] @@ -6861,9 +6855,9 @@ 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: +The UserInfo Endpoint includes a number of configuration options, as described in the following sub-sections: * <> * <> @@ -6934,8 +6928,8 @@ public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter { `CustomUserTypesOAuth2UserService` is an implementation of an `OAuth2UserService` that provides support for custom `OAuth2User` types. -If the default implementation (`DefaultOAuth2User`) may not suit your needs, you may need -to define your own implementation of `OAuth2User`. +If the default implementation (`DefaultOAuth2User`) does not suit your needs, +you can define your own implementation of `OAuth2User`. The following code demonstrates how you would register a custom `OAuth2User` type for GitHub: @@ -7022,23 +7016,23 @@ 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 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 instances. +that supports standard OAuth 2.0 Provider's. [NOTE] `OAuth2UserService` obtains the user attributes -of the end-user (the resource owner) from the `UserInfo` endpoint (by using the +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`. -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. +If the default implementation does not suit your needs, you can define your own implementation of `OAuth2UserService` +for standard OAuth 2.0 Provider's. The following configuration demonstrates how to configure a custom `OAuth2UserService`: @@ -7070,7 +7064,7 @@ that supports OpenID Connect 1.0 Provider's. [NOTE] `OAuth2UserService` is responsible for obtaining the user attributes -of the end user (the resource owner) from the `UserInfo` endpoint (byusing the +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 return an `AuthenticatedPrincipal` in the form of an `OidcUser`.