Jay Bryant
Joe Grandja
parent
70be0f3619
commit
3eb66f37e0
|
|
@ -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>>
|
||||
* <<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
|
||||
===== 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 <<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.
|
||||
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>>
|
||||
* <<jc-oauth2login-provide-websecurityconfigureradapter>>
|
||||
* <<jc-oauth2login-completely-override-autoconfiguration>>
|
||||
|
||||
|
||||
[[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]
|
||||
----
|
||||
|
|
|
|||
Loading…
Reference in New Issue