From 3eb66f37e0e4fa75db2792797f3b23234c9b485d Mon Sep 17 00:00:00 2001 From: Jay Bryant Date: Fri, 17 Nov 2017 15:47:28 -0600 Subject: [PATCH] Editing pass for OAuth 2.0 Login ref doc Fixes gh-4850 --- docs/manual/src/docs/asciidoc/index.adoc | 442 +++++++++++++---------- 1 file changed, 249 insertions(+), 193 deletions(-) diff --git a/docs/manual/src/docs/asciidoc/index.adoc b/docs/manual/src/docs/asciidoc/index.adoc index 04cd714a27..553bd45501 100644 --- a/docs/manual/src/docs/asciidoc/index.adoc +++ b/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: + +* 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]] ===== 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 _(<>)_ on the *Consent screen* page. +and have granted access to the OAuth Client _(<>)_ 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-sample-application-config]] -===== Configure application.yml +===== 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_. - -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 <>, 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 <>, 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 <>, only the *client-id* and *client-secret* properties were required. +As demonstrated previously, when we <>, 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. +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: + * <> -* Authorization Endpoint +* Authorization Endpoint: ** <> * <> -* Token Endpoint +* Token Endpoint: ** <> -* UserInfo Endpoint +* UserInfo Endpoint: ** <> ** <> ** <> @@ -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]] === 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] ---- Google ---- -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]] ==== 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] ----