Skip to content

Commit 33837d2

Browse files
jgrandjajgrandja
committed
Polish oauth2-client ref doc
1 parent cb5f985 commit 33837d2

File tree

1 file changed

+112
-64
lines changed

1 file changed

+112
-64
lines changed

‎docs/manual/src/docs/asciidoc/_includes/servlet/preface/oauth2-client.adoc

Lines changed: 112 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,21 @@
33

44
The OAuth 2.0 Client features provide support for the Client role as defined in the https://tools.ietf.org/html/rfc6749#section-1.1[OAuth 2.0 Authorization Framework].
55

6-
The following main features are available:
6+
At a high-level, the core features available are:
77

8-
* https://tools.ietf.org/html/rfc6749#section-1.3.1[Authorization Code Grant]
9-
* https://tools.ietf.org/html/rfc6749#section-1.3.4[Client Credentials Grant]
10-
* <<servlet-webclient, `WebClient` extension for Servlet Environments>> (for making protected resource requests)
8+
.Authorization Grant support
9+
* https://tools.ietf.org/html/rfc6749#section-1.3.1[Authorization Code]
10+
* https://tools.ietf.org/html/rfc6749#section-6[Refresh Token]
11+
* https://tools.ietf.org/html/rfc6749#section-1.3.4[Client Credentials]
12+
* https://tools.ietf.org/html/rfc6749#section-1.3.3[Resource Owner Password Credentials]
1113

12-
`HttpSecurity.oauth2Client()` provides a number of configuration options for customizing OAuth 2.0 Client.
13-
The following code shows the complete configuration options available for the `oauth2Client()` DSL:
14+
.HTTP Client support
15+
* <<servlet-webclient, `WebClient` integration for Servlet Environments>> (for requesting protected resources)
16+
17+
The `HttpSecurity.oauth2Client()` DSL provides a number of configuration options for customizing the core components used by OAuth 2.0 Client.
18+
In addition, `HttpSecurity.oauth2Client().authorizationCodeGrant()` enables the customization of the Authorization Code grant.
19+
20+
The following code shows the complete configuration options provided by the `HttpSecurity.oauth2Client()` DSL:
1421

1522
[source,java]
1623
----
@@ -36,14 +43,46 @@ public class OAuth2ClientSecurityConfig extends WebSecurityConfigurerAdapter {
3643
}
3744
----
3845

39-
The following sections go into more detail on each of the configuration options available:
46+
The `OAuth2AuthorizedClientManager` is responsible for managing the authorization (or re-authorization) of an OAuth 2.0 Client, in collaboration with one or more `OAuth2AuthorizedClientProvider`(s).
47+
48+
The following code shows an example of how to register an `OAuth2AuthorizedClientManager` `@Bean` and associate it with an `OAuth2AuthorizedClientProvider` composite that provides support for the `authorization_code`, `refresh_token`, `client_credentials` and `password` authorization grant types:
49+
50+
[source,java]
51+
----
52+
@Bean
53+
public OAuth2AuthorizedClientManager authorizedClientManager(
54+
ClientRegistrationRepository clientRegistrationRepository,
55+
OAuth2AuthorizedClientRepository authorizedClientRepository) {
56+
57+
OAuth2AuthorizedClientProvider authorizedClientProvider =
58+
OAuth2AuthorizedClientProviderBuilder.builder()
59+
.authorizationCode()
60+
.refreshToken()
61+
.clientCredentials()
62+
.password()
63+
.build();
64+
65+
DefaultOAuth2AuthorizedClientManager authorizedClientManager =
66+
new DefaultOAuth2AuthorizedClientManager(
67+
clientRegistrationRepository, authorizedClientRepository);
68+
authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);
69+
70+
return authorizedClientManager;
71+
}
72+
----
73+
74+
The following sections will go into more detail on the core components used by OAuth 2.0 Client and the configuration options available:
4075

41-
* <<oauth2Client-client-registration>>
42-
* <<oauth2Client-client-registration-repo>>
43-
* <<oauth2Client-authorized-client>>
44-
* <<oauth2Client-authorized-repo-service>>
45-
* <<oauth2Client-authorized-manager-provider>>
46-
* <<oauth2Client-registered-authorized-client>>
76+
* <<oauth2Client-core-interface-class>>
77+
** <<oauth2Client-client-registration, ClientRegistration>>
78+
** <<oauth2Client-client-registration-repo, ClientRegistrationRepository>>
79+
** <<oauth2Client-authorized-client, OAuth2AuthorizedClient>>
80+
** <<oauth2Client-authorized-repo-service, OAuth2AuthorizedClientRepository / OAuth2AuthorizedClientService>>
81+
** <<oauth2Client-authorized-manager-provider, OAuth2AuthorizedClientManager / OAuth2AuthorizedClientProvider>>
82+
* <<oauth2Client-auth-grant-support>>
83+
** <<oauth2Client-auth-code-grant, Authorization Code>>
84+
* <<oauth2Client-additional-features>>
85+
** <<oauth2Client-registered-authorized-client, Resolving an Authorized Client>>
4786

4887

4988
[[oauth2Client-core-interface-class]]
@@ -92,9 +131,9 @@ public final class ClientRegistration {
92131
<2> `clientId`: The client identifier.
93132
<3> `clientSecret`: The client secret.
94133
<4> `clientAuthenticationMethod`: The method used to authenticate the Client with the Provider.
95-
The supported values are *basic* and *post*.
134+
The supported values are *basic*, *post* and *none* https://tools.ietf.org/html/rfc6749#section-2.1[(public clients)].
96135
<5> `authorizationGrantType`: The OAuth 2.0 Authorization Framework defines four https://tools.ietf.org/html/rfc6749#section-1.3[Authorization Grant] types.
97-
The supported values are authorization_code, implicit, and client_credentials.
136+
The supported values are `authorization_code`, `client_credentials`, `password` and `implicit`.
98137
<6> `redirectUriTemplate`: The client's registered redirect URI that the _Authorization Server_ redirects the end-user's user-agent
99138
to after the end-user has authenticated and authorized access to the client.
100139
<7> `scopes`: The scope(s) requested by the client during the Authorization Request flow, such as openid, email, or profile.
@@ -170,8 +209,7 @@ From a developer perspective, the `OAuth2AuthorizedClientRepository` or `OAuth2A
170209

171210
[NOTE]
172211
Spring Boot 2.x auto-configuration registers an `OAuth2AuthorizedClientRepository` and/or `OAuth2AuthorizedClientService` `@Bean` in the `ApplicationContext`.
173-
174-
The developer may also register an `OAuth2AuthorizedClientRepository` or `OAuth2AuthorizedClientService` `@Bean` in the `ApplicationContext` (overriding Spring Boot 2.x auto-configuration) in order to have the ability to lookup an `OAuth2AccessToken` associated with a specific `ClientRegistration` (client).
212+
However, the application may choose to override and register a custom `OAuth2AuthorizedClientRepository` or `OAuth2AuthorizedClientService` `@Bean`.
175213

176214
The following listing shows an example:
177215

@@ -256,53 +294,26 @@ However, the application may choose to override and register a custom `OAuth2Aut
256294
[[oauth2Client-auth-code-grant]]
257295
==== Authorization Code
258296

259-
[.lead]
297+
[NOTE]
260298
Please refer to the OAuth 2.0 Authorization Framework for further details on the https://tools.ietf.org/html/rfc6749#section-1.3.1[Authorization Code] grant.
261299

262300

263301
===== Obtaining Authorization
264302

265-
`AuthorizationRequestRepository`
266-
267-
`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).
268-
269-
[TIP]
270-
The `OAuth2AuthorizationRequest` is used to correlate and validate the Authorization Response.
271-
272-
The default implementation of `AuthorizationRequestRepository` is `HttpSessionOAuth2AuthorizationRequestRepository`, which stores the `OAuth2AuthorizationRequest` in the `HttpSession`.
273-
274-
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 shown in the following example:
275-
276-
[source,java]
277-
----
278-
@EnableWebSecurity
279-
public class OAuth2ClientSecurityConfig extends WebSecurityConfigurerAdapter {
280-
281-
@Override
282-
protected void configure(HttpSecurity http) throws Exception {
283-
http
284-
.oauth2Client(oauth2Client ->
285-
oauth2Client
286-
.authorizationCodeGrant(authorizationCodeGrant ->
287-
authorizationCodeGrant
288-
.authorizationRequestRepository(this.cookieAuthorizationRequestRepository())
289-
...
290-
)
291-
);
292-
}
303+
[NOTE]
304+
Please refer to the https://tools.ietf.org/html/rfc6749#section-4.1.1[Authorization Request/Response] protocol flow for the Authorization Code grant.
293305

294-
private AuthorizationRequestRepository<OAuth2AuthorizationRequest> cookieAuthorizationRequestRepository() {
295-
return new HttpCookieOAuth2AuthorizationRequestRepository();
296-
}
297-
}
298-
----
299306

307+
===== Initiating the Authorization Request
300308

301-
`OAuth2AuthorizationRequestResolver`
309+
The `OAuth2AuthorizationRequestRedirectFilter` uses an `OAuth2AuthorizationRequestResolver` to resolve an `OAuth2AuthorizationRequest` and initiate the Authorization Code grant flow by redirecting the end-user's user-agent to the Authorization Server's Authorization Endpoint.
302310

303311
The primary role of the `OAuth2AuthorizationRequestResolver` is to resolve an `OAuth2AuthorizationRequest` from the provided web request.
304312
The default implementation `DefaultOAuth2AuthorizationRequestResolver` matches on the (default) path `/oauth2/authorization/{registrationId}` extracting the `registrationId` and using it to build the `OAuth2AuthorizationRequest` for the associated `ClientRegistration`.
305313

314+
315+
===== Customizing the Authorization Request
316+
306317
One of the primary use cases an `OAuth2AuthorizationRequestResolver` can realize is the ability to customize the Authorization Request with additional parameters above the standard parameters defined in the OAuth 2.0 Authorization Framework.
307318

308319
For example, OpenID Connect defines additional OAuth 2.0 request parameters for the https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest[Authorization Code Flow] extending from the standard parameters defined in the https://tools.ietf.org/html/rfc6749#section-4.1.1[OAuth 2.0 Authorization Framework].
@@ -399,7 +410,7 @@ public class CustomAuthorizationRequestResolver implements OAuth2AuthorizationRe
399410

400411

401412
The preceding example shows the common use case of adding a custom parameter on top of the standard parameters.
402-
However, if you need to remove or change a standard parameter or your requirements are more advanced, than you can take full control in building the Authorization Request URI by simply overriding the `OAuth2AuthorizationRequest.authorizationRequestUri` property.
413+
Alternatively, if your requirements are more advanced, than you can take full control in building the Authorization Request URI by simply overriding the `OAuth2AuthorizationRequest.authorizationRequestUri` property.
403414

404415
The following example shows a variation of the `customAuthorizationRequest()` method from the preceding example, and instead overrides the `OAuth2AuthorizationRequest.authorizationRequestUri` property.
405416

@@ -421,22 +432,61 @@ private OAuth2AuthorizationRequest customAuthorizationRequest(
421432
----
422433

423434

435+
===== Storing the Authorization Request
436+
437+
The `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).
438+
439+
[TIP]
440+
The `OAuth2AuthorizationRequest` is used to correlate and validate the Authorization Response.
441+
442+
The default implementation of `AuthorizationRequestRepository` is `HttpSessionOAuth2AuthorizationRequestRepository`, which stores the `OAuth2AuthorizationRequest` in the `HttpSession`.
443+
444+
If you have a custom implementation of `AuthorizationRequestRepository`, you may configure it as shown in the following example:
445+
446+
[source,java]
447+
----
448+
@EnableWebSecurity
449+
public class OAuth2ClientSecurityConfig extends WebSecurityConfigurerAdapter {
450+
451+
@Override
452+
protected void configure(HttpSecurity http) throws Exception {
453+
http
454+
.oauth2Client(oauth2Client ->
455+
oauth2Client
456+
.authorizationCodeGrant(authorizationCodeGrant ->
457+
authorizationCodeGrant
458+
.authorizationRequestRepository(this.customAuthorizationRequestRepository())
459+
...
460+
)
461+
);
462+
}
463+
}
464+
----
465+
466+
424467
===== Requesting an Access Token
425468

426-
`OAuth2AccessTokenResponseClient`
469+
[NOTE]
470+
Please refer to the https://tools.ietf.org/html/rfc6749#section-4.1.3[Access Token Request/Response] protocol flow for the Authorization Code grant.
427471

428472
The primary role of the `OAuth2AccessTokenResponseClient` is to exchange an authorization grant credential for an access token credential at the Authorization Server's Token Endpoint.
429473

430474
The default implementation of `OAuth2AccessTokenResponseClient` for the `authorization_code` grant is `DefaultAuthorizationCodeTokenResponseClient`, which uses a `RestOperations` for exchanging an authorization code for an access token at the Token Endpoint.
431475

432476
The `DefaultAuthorizationCodeTokenResponseClient` is quite flexible as it allows you to customize the pre-processing of the Token Request and/or post-handling of the Token Response.
433477

478+
479+
===== Customizing the Access Token Request
480+
434481
If you need to customize the pre-processing of the Token Request, you can provide `DefaultAuthorizationCodeTokenResponseClient.setRequestEntityConverter()` with a custom `Converter<OAuth2AuthorizationCodeGrantRequest, RequestEntity<?>>`.
435482
The default implementation `OAuth2AuthorizationCodeGrantRequestEntityConverter` builds a `RequestEntity` representation of a standard https://tools.ietf.org/html/rfc6749#section-4.1.3[OAuth 2.0 Access Token Request].
436-
However, providing a custom `Converter`, would allow you to extend the standard Token Request and add a custom parameter for example.
483+
However, providing a custom `Converter`, would allow you to extend the standard Token Request and add custom parameter(s).
437484

438485
IMPORTANT: The custom `Converter` must return a valid `RequestEntity` representation of an OAuth 2.0 Access Token Request that is understood by the intended OAuth 2.0 Provider.
439486

487+
488+
===== Customizing the Access Token Response
489+
440490
On the other end, if you need to customize the post-handling of the Token Response, you will need to provide `DefaultAuthorizationCodeTokenResponseClient.setRestOperations()` with a custom configured `RestOperations`.
441491
The default `RestOperations` is configured as follows:
442492

@@ -454,7 +504,7 @@ TIP: Spring MVC `FormHttpMessageConverter` is required as it's used when sending
454504
`OAuth2AccessTokenResponseHttpMessageConverter` is a `HttpMessageConverter` for an OAuth 2.0 Access Token Response.
455505
You can provide `OAuth2AccessTokenResponseHttpMessageConverter.setTokenResponseConverter()` with a custom `Converter<Map<String, String>, OAuth2AccessTokenResponse>` that is used for converting the OAuth 2.0 Access Token Response parameters to an `OAuth2AccessTokenResponse`.
456506

457-
`OAuth2ErrorResponseErrorHandler` is a `ResponseErrorHandler` that can handle an OAuth 2.0 Error (400 Bad Request).
507+
`OAuth2ErrorResponseErrorHandler` is a `ResponseErrorHandler` that can handle an OAuth 2.0 Error, eg. 400 Bad Request.
458508
It uses an `OAuth2ErrorHttpMessageConverter` for converting the OAuth 2.0 Error parameters to an `OAuth2Error`.
459509

460510
Whether you customize `DefaultAuthorizationCodeTokenResponseClient` or provide your own implementation of `OAuth2AccessTokenResponseClient`, you'll need to configure it as shown in the following example:
@@ -476,10 +526,6 @@ public class OAuth2ClientSecurityConfig extends WebSecurityConfigurerAdapter {
476526
)
477527
);
478528
}
479-
480-
private OAuth2AccessTokenResponseClient<OAuth2AuthorizationCodeGrantRequest> customAccessTokenResponseClient() {
481-
...
482-
}
483529
}
484530
----
485531

@@ -489,7 +535,7 @@ public class OAuth2ClientSecurityConfig extends WebSecurityConfigurerAdapter {
489535

490536

491537
[[oauth2Client-registered-authorized-client]]
492-
==== RegisteredOAuth2AuthorizedClient
538+
==== Resolving an Authorized Client
493539

494540
The `@RegisteredOAuth2AuthorizedClient` annotation provides the capability of resolving a method parameter to an argument value of type `OAuth2AuthorizedClient`.
495541
This is a convenient alternative compared to looking up the `OAuth2AuthorizedClient` via the `OAuth2AuthorizedClientService`.
@@ -512,6 +558,8 @@ public class OAuth2LoginController {
512558

513559
The `@RegisteredOAuth2AuthorizedClient` annotation is handled by `OAuth2AuthorizedClientArgumentResolver` and provides the following capabilities:
514560

515-
* An `OAuth2AccessToken` will automatically be requested if the client has not yet been authorized.
516-
** For `authorization_code`, this involves triggering the authorization request redirect to initiate the flow
517-
** For `client_credentials`, the access token is directly obtained from the Token Endpoint using `DefaultClientCredentialsTokenResponseClient`
561+
* An `OAuth2AccessToken` will be requested if the client has not yet been authorized.
562+
** `authorization_code` - triggers the authorization request redirect to initiate the flow
563+
** `client_credentials` - the access token is obtained directly from the Token Endpoint
564+
** `password` - the access token is obtained directly from the Token Endpoint
565+
* If the `OAuth2AccessToken` is expired, it will be renewed (or refreshed) if an `OAuth2AuthorizedClientProvider` is available to perform the authorization

0 commit comments

Comments
 (0)