Cwikius-Spring/spring-security
1
0
Fork 0
mirror of https://github.com/spring-projects/spring-security.git synced 2025-06-26 05:42:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update reactive OAuth2 docs

Browse Source 
Issue gh-15938
This commit is contained in:
Steve Riesenberg 2024-10-28 12:29:11 -05:00
parent 9d2ca3da6a
commit d5cb41156c
No known key found for this signature in database
GPG Key ID: 3D0169B18AB8F0A9
6 changed files with 499 additions and 215 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

316
docs/modules/ROOT/pages/reactive/oauth2/client/authorization-grants.adoc
View File

@ -1,20 +1,21 @@
[[oauth2Client-auth-grant-support]] [[oauth2-client-authorization-grants]]
= Authorization Grant Support = [[oauth2Client-auth-grant-support]]Authorization Grant Support
This section describes Spring Security's support for authorization grants.
[[oauth2Client-auth-code-grant]] [[oauth2-client-authorization-code]]
== Authorization Code == [[oauth2Client-auth-code-grant]]Authorization Code
[NOTE] [NOTE]
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. 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.
[[oauth2-client-authorization-code-authorization]]
=== Obtaining Authorization === Obtaining Authorization
[NOTE] [NOTE]
Please refer to the https://tools.ietf.org/html/rfc6749#section-4.1.1[Authorization Request/Response] protocol flow for the Authorization Code grant. Please refer to the https://tools.ietf.org/html/rfc6749#section-4.1.1[Authorization Request/Response] protocol flow for the Authorization Code grant.
[[oauth2-client-authorization-code-authorization-request]]
=== Initiating the Authorization Request === Initiating the Authorization Request
The `OAuth2AuthorizationRequestRedirectWebFilter` uses a `ServerOAuth2AuthorizationRequestResolver` 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. The `OAuth2AuthorizationRequestRedirectWebFilter` uses a `ServerOAuth2AuthorizationRequestResolver` 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.
@ -63,7 +64,7 @@ spring:
client-authentication-method: none client-authentication-method: none
authorization-grant-type: authorization_code authorization-grant-type: authorization_code
redirect-uri: "{baseUrl}/authorized/okta" redirect-uri: "{baseUrl}/authorized/okta"
... # ...
---- ----
Public Clients are supported using https://tools.ietf.org/html/rfc7636[Proof Key for Code Exchange] (PKCE). Public Clients are supported using https://tools.ietf.org/html/rfc7636[Proof Key for Code Exchange] (PKCE).
@ -75,8 +76,8 @@ If the client is running in an untrusted environment (eg. native application or
[TIP] [TIP]
If the OAuth 2.0 Provider supports PKCE for https://tools.ietf.org/html/rfc6749#section-2.1[Confidential Clients], you may (optionally) configure it using `DefaultServerOAuth2AuthorizationRequestResolver.setAuthorizationRequestCustomizer(OAuth2AuthorizationRequestCustomizers.withPkce())`. If the OAuth 2.0 Provider supports PKCE for https://tools.ietf.org/html/rfc6749#section-2.1[Confidential Clients], you may (optionally) configure it using `DefaultServerOAuth2AuthorizationRequestResolver.setAuthorizationRequestCustomizer(OAuth2AuthorizationRequestCustomizers.withPkce())`.
[[oauth2Client-auth-code-redirect-uri]] [[oauth2-client-authorization-code-redirect-uri]]
The `DefaultServerOAuth2AuthorizationRequestResolver` also supports `URI` template variables for the `redirect-uri` using `UriComponentsBuilder`. [[oauth2Client-auth-code-redirect-uri]]The `DefaultServerOAuth2AuthorizationRequestResolver` also supports `URI` template variables for the `redirect-uri` using `UriComponentsBuilder`.
The following configuration uses all the supported `URI` template variables: The following configuration uses all the supported `URI` template variables:
@ -88,9 +89,9 @@ spring:
client: client:
registration: registration:
okta: okta:
... # ...
redirect-uri: "{baseScheme}://{baseHost}{basePort}{basePath}/authorized/{registrationId}" redirect-uri: "{baseScheme}://{baseHost}{basePort}{basePath}/authorized/{registrationId}"
... # ...
---- ----
[NOTE] [NOTE]
@ -99,6 +100,7 @@ spring:
Configuring the `redirect-uri` with `URI` template variables is especially useful when the OAuth 2.0 Client is running behind a xref:features/exploits/http.adoc#http-proxy-server[Proxy Server]. Configuring the `redirect-uri` with `URI` template variables is especially useful when the OAuth 2.0 Client is running behind a xref:features/exploits/http.adoc#http-proxy-server[Proxy Server].
This ensures that the `X-Forwarded-*` headers are used when expanding the `redirect-uri`. This ensures that the `X-Forwarded-*` headers are used when expanding the `redirect-uri`.
[[oauth2-client-authorization-code-authorization-request-resolver]]
=== Customizing the Authorization Request === Customizing the Authorization Request
One of the primary use cases a `ServerOAuth2AuthorizationRequestResolver` 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. One of the primary use cases a `ServerOAuth2AuthorizationRequestResolver` 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.
@ -255,7 +257,7 @@ private fun authorizationRequestCustomizer(): Consumer<OAuth2AuthorizationReques
---- ----
====== ======
[[oauth2-client-authorization-code-authorization-request-repository]]
=== Storing the Authorization Request === Storing the Authorization Request
The `ServerAuthorizationRequestRepository` 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). The `ServerAuthorizationRequestRepository` 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).
@ -283,7 +285,7 @@ public class OAuth2ClientSecurityConfig {
http http
.oauth2Client(oauth2 -> oauth2 .oauth2Client(oauth2 -> oauth2
.authorizationRequestRepository(this.authorizationRequestRepository()) .authorizationRequestRepository(this.authorizationRequestRepository())
... // ...
); );
return http.build(); return http.build();
} }
@ -312,6 +314,7 @@ class OAuth2ClientSecurityConfig {
---- ----
====== ======
[[oauth2-client-authorization-code-access-token]]
=== Requesting an Access Token === Requesting an Access Token
[NOTE] [NOTE]
@ -319,33 +322,21 @@ Please refer to the https://tools.ietf.org/html/rfc6749#section-4.1.3[Access Tok
The default implementation of `ReactiveOAuth2AccessTokenResponseClient` for the Authorization Code grant is `WebClientReactiveAuthorizationCodeTokenResponseClient`, which uses a `WebClient` for exchanging an authorization code for an access token at the Authorization Server’s Token Endpoint. The default implementation of `ReactiveOAuth2AccessTokenResponseClient` for the Authorization Code grant is `WebClientReactiveAuthorizationCodeTokenResponseClient`, which uses a `WebClient` for exchanging an authorization code for an access token at the Authorization Server’s Token Endpoint.
The `WebClientReactiveAuthorizationCodeTokenResponseClient` is quite flexible as it allows you to customize the pre-processing of the Token Request and/or post-handling of the Token Response. :section-id: authorization-code
:grant-type: Authorization Code
:class-name: WebClientReactiveAuthorizationCodeTokenResponseClient
:grant-request: OAuth2AuthorizationCodeGrantRequest
:leveloffset: +1
include::partial$reactive/oauth2/client/web-client-access-token-response-client.adoc[]
:leveloffset: -1
=== Customizing the Access Token Request [[oauth2-client-authorization-code-access-token-response-client-dsl]]
=== Customize using the DSL
If you need to customize the pre-processing of the Token Request, you can provide `WebClientReactiveAuthorizationCodeTokenResponseClient.setParametersConverter()` with a custom `Converter<OAuth2AuthorizationCodeGrantRequest, MultiValueMap<String, String>>`. Whether you customize `{class-name}` or provide your own implementation of `ReactiveOAuth2AccessTokenResponseClient`, you can configure it using the DSL (as an alternative to <<oauth2-client-authorization-code-access-token-response-client-bean,publishing a bean>>) as shown in the following example:
The default implementation builds a `MultiValueMap<String, String>` containing only the `grant_type` parameter of a standard https://tools.ietf.org/html/rfc6749#section-4.1.3[OAuth 2.0 Access Token Request] which is used to construct the request. Other parameters required by the Authorization Code grant are added directly to the body of the request by the `WebClientReactiveAuthorizationCodeTokenResponseClient`.
However, providing a custom `Converter`, would allow you to extend the standard Token Request and add custom parameter(s).
[TIP] .Access Token Response Configuration via DSL
If you prefer to only add additional parameters, you can instead provide `WebClientReactiveAuthorizationCodeTokenResponseClient.addParametersConverter()` with a custom `Converter<OAuth2AuthorizationCodeGrantRequest, MultiValueMap<String, String>>` which constructs an aggregate `Converter`.
IMPORTANT: The custom `Converter` must return valid parameters of an OAuth 2.0 Access Token Request that is understood by the intended OAuth 2.0 Provider.
=== Customizing the Access Token Response
On the other end, if you need to customize the post-handling of the Token Response, you will need to provide `WebClientReactiveAuthorizationCodeTokenResponseClient.setBodyExtractor()` with a custom configured `BodyExtractor<Mono<OAuth2AccessTokenResponse>, ReactiveHttpInputMessage>` that is used for converting the OAuth 2.0 Access Token Response to an `OAuth2AccessTokenResponse`.
The default implementation provided by `OAuth2BodyExtractors.oauth2AccessTokenResponse()` parses the response and handles errors accordingly.
=== Customizing the `WebClient`
Alternatively, if your requirements are more advanced, you can take full control of the request/response by simply providing `WebClientReactiveAuthorizationCodeTokenResponseClient.setWebClient()` with a custom configured `WebClient`.
Whether you customize `WebClientReactiveAuthorizationCodeTokenResponseClient` or provide your own implementation of `ReactiveOAuth2AccessTokenResponseClient`, you’ll need to configure it as shown in the following example:
.Access Token Response Configuration
[tabs] [tabs]
====== ======
Java:: Java::
@ -361,7 +352,7 @@ public class OAuth2ClientSecurityConfig {
http http
.oauth2Client(oauth2 -> oauth2 .oauth2Client(oauth2 -> oauth2
.authenticationManager(this.authorizationCodeAuthenticationManager()) .authenticationManager(this.authorizationCodeAuthenticationManager())
... // ...
); );
return http.build(); return http.build();
} }
@ -369,7 +360,7 @@ public class OAuth2ClientSecurityConfig {
private ReactiveAuthenticationManager authorizationCodeAuthenticationManager() { private ReactiveAuthenticationManager authorizationCodeAuthenticationManager() {
WebClientReactiveAuthorizationCodeTokenResponseClient accessTokenResponseClient = WebClientReactiveAuthorizationCodeTokenResponseClient accessTokenResponseClient =
new WebClientReactiveAuthorizationCodeTokenResponseClient(); new WebClientReactiveAuthorizationCodeTokenResponseClient();
... // ...
return new OAuth2AuthorizationCodeReactiveAuthenticationManager(accessTokenResponseClient); return new OAuth2AuthorizationCodeReactiveAuthenticationManager(accessTokenResponseClient);
} }
@ -397,7 +388,7 @@ class OAuth2ClientSecurityConfig {
private fun authorizationCodeAuthenticationManager(): ReactiveAuthenticationManager { private fun authorizationCodeAuthenticationManager(): ReactiveAuthenticationManager {
val accessTokenResponseClient = WebClientReactiveAuthorizationCodeTokenResponseClient() val accessTokenResponseClient = WebClientReactiveAuthorizationCodeTokenResponseClient()
... // ...
return OAuth2AuthorizationCodeReactiveAuthenticationManager(accessTokenResponseClient) return OAuth2AuthorizationCodeReactiveAuthenticationManager(accessTokenResponseClient)
} }
@ -405,14 +396,13 @@ class OAuth2ClientSecurityConfig {
---- ----
====== ======
[[oauth2-client-refresh-token]]
[[oauth2Client-refresh-token-grant]] == [[oauth2Client-refresh-token-grant]]Refresh Token
== Refresh Token
[NOTE] [NOTE]
Please refer to the OAuth 2.0 Authorization Framework for further details on the https://tools.ietf.org/html/rfc6749#section-1.5[Refresh Token]. Please refer to the OAuth 2.0 Authorization Framework for further details on the https://tools.ietf.org/html/rfc6749#section-1.5[Refresh Token].
[[oauth2-client-refresh-token-access-token]]
=== Refreshing an Access Token === Refreshing an Access Token
[NOTE] [NOTE]
@ -420,33 +410,21 @@ Please refer to the https://tools.ietf.org/html/rfc6749#section-6[Access Token R
The default implementation of `ReactiveOAuth2AccessTokenResponseClient` for the Refresh Token grant is `WebClientReactiveRefreshTokenTokenResponseClient`, which uses a `WebClient` when refreshing an access token at the Authorization Server’s Token Endpoint. The default implementation of `ReactiveOAuth2AccessTokenResponseClient` for the Refresh Token grant is `WebClientReactiveRefreshTokenTokenResponseClient`, which uses a `WebClient` when refreshing an access token at the Authorization Server’s Token Endpoint.
The `WebClientReactiveRefreshTokenTokenResponseClient` is quite flexible as it allows you to customize the pre-processing of the Token Request and/or post-handling of the Token Response. :section-id: refresh-token
:grant-type: Refresh Token
:class-name: WebClientReactiveRefreshTokenTokenResponseClient
:grant-request: OAuth2RefreshTokenGrantRequest
:leveloffset: +1
include::partial$reactive/oauth2/client/web-client-access-token-response-client.adoc[]
:leveloffset: -1
=== Customizing the Access Token Request [[oauth2-client-refresh-token-authorized-client-provider-builder]]
=== Customize using the Builder
If you need to customize the pre-processing of the Token Request, you can provide `WebClientReactiveRefreshTokenTokenResponseClient.setParametersConverter()` with a custom `Converter<OAuth2RefreshTokenGrantRequest, MultiValueMap<String, String>>`. Whether you customize `WebClientReactiveRefreshTokenTokenResponseClient` or provide your own implementation of `ReactiveOAuth2AccessTokenResponseClient`, you can configure it using the `ReactiveOAuth2AuthorizedClientProviderBuilder` (as an alternative to <<oauth2-client-refresh-token-access-token-response-client-bean,publishing a bean>>) as follows:
The default implementation builds a `MultiValueMap<String, String>` containing only the `grant_type` parameter of a standard https://tools.ietf.org/html/rfc6749#section-6[OAuth 2.0 Access Token Request] which is used to construct the request. Other parameters required by the Refresh Token grant are added directly to the body of the request by the `WebClientReactiveRefreshTokenTokenResponseClient`.
However, providing a custom `Converter`, would allow you to extend the standard Token Request and add custom parameter(s).
[TIP] .Access Token Response Configuration via Builder
If you prefer to only add additional parameters, you can instead provide `WebClientReactiveRefreshTokenTokenResponseClient.addParametersConverter()` with a custom `Converter<OAuth2RefreshTokenGrantRequest, MultiValueMap<String, String>>` which constructs an aggregate `Converter`.
IMPORTANT: The custom `Converter` must return valid parameters of an OAuth 2.0 Access Token Request that is understood by the intended OAuth 2.0 Provider.
=== Customizing the Access Token Response
On the other end, if you need to customize the post-handling of the Token Response, you will need to provide `WebClientReactiveRefreshTokenTokenResponseClient.setBodyExtractor()` with a custom configured `BodyExtractor<Mono<OAuth2AccessTokenResponse>, ReactiveHttpInputMessage>` that is used for converting the OAuth 2.0 Access Token Response to an `OAuth2AccessTokenResponse`.
The default implementation provided by `OAuth2BodyExtractors.oauth2AccessTokenResponse()` parses the response and handles errors accordingly.
=== Customizing the `WebClient`
Alternatively, if your requirements are more advanced, you can take full control of the request/response by simply providing `WebClientReactiveRefreshTokenTokenResponseClient.setWebClient()` with a custom configured `WebClient`.
Whether you customize `WebClientReactiveRefreshTokenTokenResponseClient` or provide your own implementation of `ReactiveOAuth2AccessTokenResponseClient`, you’ll need to configure it as shown in the following example:
.Access Token Response Configuration
[tabs] [tabs]
====== ======
Java:: Java::
@ -462,7 +440,7 @@ ReactiveOAuth2AuthorizedClientProvider authorizedClientProvider =
.refreshToken(configurer -> configurer.accessTokenResponseClient(refreshTokenTokenResponseClient)) .refreshToken(configurer -> configurer.accessTokenResponseClient(refreshTokenTokenResponseClient))
.build(); .build();
... // ...
authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider); authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);
---- ----
@ -479,7 +457,7 @@ val authorizedClientProvider: ReactiveOAuth2AuthorizedClientProvider = ReactiveO
.refreshToken { it.accessTokenResponseClient(refreshTokenTokenResponseClient) } .refreshToken { it.accessTokenResponseClient(refreshTokenTokenResponseClient) }
.build() .build()
... // ...
authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider) authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
---- ----
@ -492,14 +470,13 @@ which is an implementation of a `ReactiveOAuth2AuthorizedClientProvider` for the
The `OAuth2RefreshToken` may optionally be returned in the Access Token Response for the `authorization_code` and `password` grant types. The `OAuth2RefreshToken` may optionally be returned in the Access Token Response for the `authorization_code` and `password` grant types.
If the `OAuth2AuthorizedClient.getRefreshToken()` is available and the `OAuth2AuthorizedClient.getAccessToken()` is expired, it will automatically be refreshed by the `RefreshTokenReactiveOAuth2AuthorizedClientProvider`. If the `OAuth2AuthorizedClient.getRefreshToken()` is available and the `OAuth2AuthorizedClient.getAccessToken()` is expired, it will automatically be refreshed by the `RefreshTokenReactiveOAuth2AuthorizedClientProvider`.
[[oauth2-client-client-credentials]]
[[oauth2Client-client-creds-grant]] == [[oauth2Client-client-creds-grant]]Client Credentials
== Client Credentials
[NOTE] [NOTE]
Please refer to the OAuth 2.0 Authorization Framework for further details on the https://tools.ietf.org/html/rfc6749#section-1.3.4[Client Credentials] grant. Please refer to the OAuth 2.0 Authorization Framework for further details on the https://tools.ietf.org/html/rfc6749#section-1.3.4[Client Credentials] grant.
[[oauth2-client-client-credentials-access-token]]
=== Requesting an Access Token === Requesting an Access Token
[NOTE] [NOTE]
@ -507,32 +484,21 @@ Please refer to the https://tools.ietf.org/html/rfc6749#section-4.4.2[Access Tok
The default implementation of `ReactiveOAuth2AccessTokenResponseClient` for the Client Credentials grant is `WebClientReactiveClientCredentialsTokenResponseClient`, which uses a `WebClient` when requesting an access token at the Authorization Server’s Token Endpoint. The default implementation of `ReactiveOAuth2AccessTokenResponseClient` for the Client Credentials grant is `WebClientReactiveClientCredentialsTokenResponseClient`, which uses a `WebClient` when requesting an access token at the Authorization Server’s Token Endpoint.
The `WebClientReactiveClientCredentialsTokenResponseClient` is quite flexible as it allows you to customize the pre-processing of the Token Request and/or post-handling of the Token Response. :section-id: client-credentials
:grant-type: Client Credentials
:class-name: WebClientReactiveClientCredentialsTokenResponseClient
:grant-request: OAuth2ClientCredentialsGrantRequest
:leveloffset: +1
include::partial$reactive/oauth2/client/web-client-access-token-response-client.adoc[]
:leveloffset: -1
=== Customizing the Access Token Request [[oauth2-client-client-credentials-authorized-client-provider-builder]]
=== Customize using the Builder
If you need to customize the pre-processing of the Token Request, you can provide `WebClientReactiveClientCredentialsTokenResponseClient.setParametersConverter()` with a custom `Converter<OAuth2ClientCredentialsGrantRequest, MultiValueMap<String, String>>`. Whether you customize `WebClientReactiveClientCredentialsTokenResponseClient` or provide your own implementation of `ReactiveOAuth2AccessTokenResponseClient`, you can configure it using the `ReactiveOAuth2AuthorizedClientProviderBuilder` (as an alternative to <<oauth2-client-client-credentials-access-token-response-client-bean,publishing a bean>>) as follows:
The default implementation builds a `MultiValueMap<String, String>` containing only the `grant_type` parameter of a standard https://tools.ietf.org/html/rfc6749#section-4.4.2[OAuth 2.0 Access Token Request] which is used to construct the request. Other parameters required by the Client Credentials grant are added directly to the body of the request by the `WebClientReactiveClientCredentialsTokenResponseClient`.
However, providing a custom `Converter`, would allow you to extend the standard Token Request and add custom parameter(s).
[TIP]
If you prefer to only add additional parameters, you can instead provide `WebClientReactiveClientCredentialsTokenResponseClient.addParametersConverter()` with a custom `Converter<OAuth2ClientCredentialsGrantRequest, MultiValueMap<String, String>>` which constructs an aggregate `Converter`.
IMPORTANT: The custom `Converter` must return valid parameters of an OAuth 2.0 Access Token Request that is understood by the intended OAuth 2.0 Provider.
=== Customizing the Access Token Response
On the other end, if you need to customize the post-handling of the Token Response, you will need to provide `WebClientReactiveClientCredentialsTokenResponseClient.setBodyExtractor()` with a custom configured `BodyExtractor<Mono<OAuth2AccessTokenResponse>, ReactiveHttpInputMessage>` that is used for converting the OAuth 2.0 Access Token Response to an `OAuth2AccessTokenResponse`.
The default implementation provided by `OAuth2BodyExtractors.oauth2AccessTokenResponse()` parses the response and handles errors accordingly.
=== Customizing the `WebClient`
Alternatively, if your requirements are more advanced, you can take full control of the request/response by simply providing `WebClientReactiveClientCredentialsTokenResponseClient.setWebClient()` with a custom configured `WebClient`.
Whether you customize `WebClientReactiveClientCredentialsTokenResponseClient` or provide your own implementation of `ReactiveOAuth2AccessTokenResponseClient`, you'll need to configure it as shown in the following example:
.Access Token Response Configuration via Builder
[tabs] [tabs]
====== ======
Java:: Java::
@ -547,7 +513,7 @@ ReactiveOAuth2AuthorizedClientProvider authorizedClientProvider =
.clientCredentials(configurer -> configurer.accessTokenResponseClient(clientCredentialsTokenResponseClient)) .clientCredentials(configurer -> configurer.accessTokenResponseClient(clientCredentialsTokenResponseClient))
.build(); .build();
... // ...
authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider); authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);
---- ----
@ -563,7 +529,7 @@ val authorizedClientProvider: ReactiveOAuth2AuthorizedClientProvider = ReactiveO
.clientCredentials { it.accessTokenResponseClient(clientCredentialsTokenResponseClient) } .clientCredentials { it.accessTokenResponseClient(clientCredentialsTokenResponseClient) }
.build() .build()
... // ...
authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider) authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
---- ----
@ -573,6 +539,7 @@ authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
`ReactiveOAuth2AuthorizedClientProviderBuilder.builder().clientCredentials()` configures a `ClientCredentialsReactiveOAuth2AuthorizedClientProvider`, `ReactiveOAuth2AuthorizedClientProviderBuilder.builder().clientCredentials()` configures a `ClientCredentialsReactiveOAuth2AuthorizedClientProvider`,
which is an implementation of a `ReactiveOAuth2AuthorizedClientProvider` for the Client Credentials grant. which is an implementation of a `ReactiveOAuth2AuthorizedClientProvider` for the Client Credentials grant.
[[oauth2-client-client-credentials-authorized-client-manager]]
=== Using the Access Token === Using the Access Token
Given the following Spring Boot properties for an OAuth 2.0 Client registration: Given the following Spring Boot properties for an OAuth 2.0 Client registration:
@ -663,7 +630,7 @@ public class OAuth2ClientController {
return this.authorizedClientManager.authorize(authorizeRequest) return this.authorizedClientManager.authorize(authorizeRequest)
.map(OAuth2AuthorizedClient::getAccessToken) .map(OAuth2AuthorizedClient::getAccessToken)
... // ...
.thenReturn("index"); .thenReturn("index");
} }
} }
@ -687,7 +654,7 @@ class OAuth2ClientController {
return authorizedClientManager.authorize(authorizeRequest) return authorizedClientManager.authorize(authorizeRequest)
.map { it.accessToken } .map { it.accessToken }
... // ...
.thenReturn("index") .thenReturn("index")
} }
} }
@ -698,14 +665,13 @@ class OAuth2ClientController {
`ServerWebExchange` is an OPTIONAL attribute. `ServerWebExchange` is an OPTIONAL attribute.
If not provided, it will be obtained from the https://projectreactor.io/docs/core/release/reference/#context[Reactor's Context] via the key `ServerWebExchange.class`. If not provided, it will be obtained from the https://projectreactor.io/docs/core/release/reference/#context[Reactor's Context] via the key `ServerWebExchange.class`.
[[oauth2-client-password]]
[[oauth2Client-password-grant]] == [[oauth2Client-password-grant]]Resource Owner Password Credentials
== Resource Owner Password Credentials
[NOTE] [NOTE]
Please refer to the OAuth 2.0 Authorization Framework for further details on the https://tools.ietf.org/html/rfc6749#section-1.3.3[Resource Owner Password Credentials] grant. Please refer to the OAuth 2.0 Authorization Framework for further details on the https://tools.ietf.org/html/rfc6749#section-1.3.3[Resource Owner Password Credentials] grant.
[[oauth2-client-password-access-token]]
=== Requesting an Access Token === Requesting an Access Token
[NOTE] [NOTE]
@ -713,32 +679,27 @@ Please refer to the https://tools.ietf.org/html/rfc6749#section-4.3.2[Access Tok
The default implementation of `ReactiveOAuth2AccessTokenResponseClient` for the Resource Owner Password Credentials grant is `WebClientReactivePasswordTokenResponseClient`, which uses a `WebClient` when requesting an access token at the Authorization Server’s Token Endpoint. The default implementation of `ReactiveOAuth2AccessTokenResponseClient` for the Resource Owner Password Credentials grant is `WebClientReactivePasswordTokenResponseClient`, which uses a `WebClient` when requesting an access token at the Authorization Server’s Token Endpoint.
The `WebClientReactivePasswordTokenResponseClient` is quite flexible as it allows you to customize the pre-processing of the Token Request and/or post-handling of the Token Response. [CAUTION]
====
The `WebClientReactivePasswordTokenResponseClient` class and support for the Resource Owner Password Credentials grant are deprecated.
This section will be removed in Spring Security 7.
====
:section-id: password
:grant-type: Password
:class-name: WebClientReactivePasswordTokenResponseClient
:grant-request: OAuth2PasswordGrantRequest
:leveloffset: +1
include::partial$reactive/oauth2/client/web-client-access-token-response-client.adoc[]
=== Customizing the Access Token Request :leveloffset: -1
If you need to customize the pre-processing of the Token Request, you can provide `WebClientReactivePasswordTokenResponseClient.setParametersConverter()` with a custom `Converter<OAuth2PasswordGrantRequest, MultiValueMap<String, String>>`. [[oauth2-client-password-authorized-client-provider-builder]]
The default implementation builds a `MultiValueMap<String, String>` containing only the `grant_type` parameter of a standard https://tools.ietf.org/html/rfc6749#section-4.4.2[OAuth 2.0 Access Token Request] which is used to construct the request. Other parameters required by the Resource Owner Password Credentials grant are added directly to the body of the request by the `WebClientReactivePasswordTokenResponseClient`. === Customize using the Builder
However, providing a custom `Converter`, would allow you to extend the standard Token Request and add custom parameter(s).
[TIP] Whether you customize `WebClientReactivePasswordTokenResponseClient` or provide your own implementation of `ReactiveOAuth2AccessTokenResponseClient`, you can configure it using the `ReactiveOAuth2AuthorizedClientProviderBuilder` (as an alternative to <<oauth2-client-password-access-token-response-client-bean,publishing a bean>>) as follows:
If you prefer to only add additional parameters, you can instead provide `WebClientReactivePasswordTokenResponseClient.addParametersConverter()` with a custom `Converter<OAuth2PasswordGrantRequest, MultiValueMap<String, String>>` which constructs an aggregate `Converter`.
IMPORTANT: The custom `Converter` must return valid parameters of an OAuth 2.0 Access Token Request that is understood by the intended OAuth 2.0 Provider.
=== Customizing the Access Token Response
On the other end, if you need to customize the post-handling of the Token Response, you will need to provide `WebClientReactivePasswordTokenResponseClient.setBodyExtractor()` with a custom configured `BodyExtractor<Mono<OAuth2AccessTokenResponse>, ReactiveHttpInputMessage>` that is used for converting the OAuth 2.0 Access Token Response to an `OAuth2AccessTokenResponse`.
The default implementation provided by `OAuth2BodyExtractors.oauth2AccessTokenResponse()` parses the response and handles errors accordingly.
=== Customizing the `WebClient`
Alternatively, if your requirements are more advanced, you can take full control of the request/response by simply providing `WebClientReactivePasswordTokenResponseClient.setWebClient()` with a custom configured `WebClient`.
Whether you customize `WebClientReactivePasswordTokenResponseClient` or provide your own implementation of `ReactiveOAuth2AccessTokenResponseClient`, you'll need to configure it as shown in the following example:
.Access Token Response Configuration via Builder
[tabs] [tabs]
====== ======
Java:: Java::
@ -754,7 +715,7 @@ ReactiveOAuth2AuthorizedClientProvider authorizedClientProvider =
.refreshToken() .refreshToken()
.build(); .build();
... // ...
authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider); authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);
---- ----
@ -770,7 +731,7 @@ val authorizedClientProvider = ReactiveOAuth2AuthorizedClientProviderBuilder.bui
.refreshToken() .refreshToken()
.build() .build()
... // ...
authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider) authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
---- ----
@ -780,6 +741,7 @@ authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
`ReactiveOAuth2AuthorizedClientProviderBuilder.builder().password()` configures a `PasswordReactiveOAuth2AuthorizedClientProvider`, `ReactiveOAuth2AuthorizedClientProviderBuilder.builder().password()` configures a `PasswordReactiveOAuth2AuthorizedClientProvider`,
which is an implementation of a `ReactiveOAuth2AuthorizedClientProvider` for the Resource Owner Password Credentials grant. which is an implementation of a `ReactiveOAuth2AuthorizedClientProvider` for the Resource Owner Password Credentials grant.
[[oauth2-client-password-authorized-client-manager]]
=== Using the Access Token === Using the Access Token
Given the following Spring Boot properties for an OAuth 2.0 Client registration: Given the following Spring Boot properties for an OAuth 2.0 Client registration:
@ -916,7 +878,7 @@ public class OAuth2ClientController {
return this.authorizedClientManager.authorize(authorizeRequest) return this.authorizedClientManager.authorize(authorizeRequest)
.map(OAuth2AuthorizedClient::getAccessToken) .map(OAuth2AuthorizedClient::getAccessToken)
... // ...
.thenReturn("index"); .thenReturn("index");
} }
} }
@ -940,7 +902,7 @@ class OAuth2ClientController {
return authorizedClientManager.authorize(authorizeRequest) return authorizedClientManager.authorize(authorizeRequest)
.map { it.accessToken } .map { it.accessToken }
... // ...
.thenReturn("index") .thenReturn("index")
} }
} }
@ -951,14 +913,13 @@ class OAuth2ClientController {
`ServerWebExchange` is an OPTIONAL attribute. `ServerWebExchange` is an OPTIONAL attribute.
If not provided, it will be obtained from the https://projectreactor.io/docs/core/release/reference/#context[Reactor's Context] via the key `ServerWebExchange.class`. If not provided, it will be obtained from the https://projectreactor.io/docs/core/release/reference/#context[Reactor's Context] via the key `ServerWebExchange.class`.
[[oauth2-client-jwt-bearer]]
[[oauth2Client-jwt-bearer-grant]] == [[oauth2Client-jwt-bearer-grant]]JWT Bearer
== JWT Bearer
[NOTE] [NOTE]
Please refer to JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants for further details on the https://datatracker.ietf.org/doc/html/rfc7523[JWT Bearer] grant. Please refer to JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants for further details on the https://datatracker.ietf.org/doc/html/rfc7523[JWT Bearer] grant.
[[oauth2-client-jwt-bearer-access-token]]
=== Requesting an Access Token === Requesting an Access Token
[NOTE] [NOTE]
@ -966,31 +927,21 @@ Please refer to the https://datatracker.ietf.org/doc/html/rfc7523#section-2.1[Ac
The default implementation of `ReactiveOAuth2AccessTokenResponseClient` for the JWT Bearer grant is `WebClientReactiveJwtBearerTokenResponseClient`, which uses a `WebClient` when requesting an access token at the Authorization Server’s Token Endpoint. The default implementation of `ReactiveOAuth2AccessTokenResponseClient` for the JWT Bearer grant is `WebClientReactiveJwtBearerTokenResponseClient`, which uses a `WebClient` when requesting an access token at the Authorization Server’s Token Endpoint.
The `WebClientReactiveJwtBearerTokenResponseClient` is quite flexible as it allows you to customize the pre-processing of the Token Request and/or post-handling of the Token Response. :section-id: jwt-bearer
:grant-type: JWT Bearer
:class-name: WebClientReactiveJwtBearerTokenResponseClient
:grant-request: JwtBearerGrantRequest
:leveloffset: +1
include::partial$reactive/oauth2/client/web-client-access-token-response-client.adoc[]
:leveloffset: -1
=== Customizing the Access Token Request [[oauth2-client-jwt-bearer-authorized-client-provider-builder]]
=== Customize using the Builder
If you need to customize the pre-processing of the Token Request, you can provide `WebClientReactiveJwtBearerTokenResponseClient.setParametersConverter()` with a custom `Converter<JwtBearerGrantRequest, MultiValueMap<String, String>>`. Whether you customize `WebClientReactiveJwtBearerTokenResponseClient` or provide your own implementation of `ReactiveOAuth2AccessTokenResponseClient`, you can configure it using the `ReactiveOAuth2AuthorizedClientProviderBuilder` (as an alternative to <<oauth2-client-jwt-bearer-access-token-response-client-bean,publishing a bean>>) as follows:
The default implementation builds a `MultiValueMap<String, String>` containing only the `grant_type` parameter of a standard https://tools.ietf.org/html/rfc6749#section-4.4.2[OAuth 2.0 Access Token Request] which is used to construct the request. Other parameters required by the JWT Bearer grant are added directly to the body of the request by the `WebClientReactiveJwtBearerTokenResponseClient`.
However, providing a custom `Converter`, would allow you to extend the standard Token Request and add custom parameter(s).
[TIP]
If you prefer to only add additional parameters, you can instead provide `WebClientReactiveJwtBearerTokenResponseClient.addParametersConverter()` with a custom `Converter<JwtBearerGrantRequest, MultiValueMap<String, String>>` which constructs an aggregate `Converter`.
IMPORTANT: The custom `Converter` must return valid parameters of an OAuth 2.0 Access Token Request that is understood by the intended OAuth 2.0 Provider.
=== Customizing the Access Token Response
On the other end, if you need to customize the post-handling of the Token Response, you will need to provide `WebClientReactiveJwtBearerTokenResponseClient.setBodyExtractor()` with a custom configured `BodyExtractor<Mono<OAuth2AccessTokenResponse>, ReactiveHttpInputMessage>` that is used for converting the OAuth 2.0 Access Token Response to an `OAuth2AccessTokenResponse`.
The default implementation provided by `OAuth2BodyExtractors.oauth2AccessTokenResponse()` parses the response and handles errors accordingly.
=== Customizing the `WebClient`
Alternatively, if your requirements are more advanced, you can take full control of the request/response by simply providing `WebClientReactiveJwtBearerTokenResponseClient.setWebClient()` with a custom configured `WebClient`.
Whether you customize `WebClientReactiveJwtBearerTokenResponseClient` or provide your own implementation of `ReactiveOAuth2AccessTokenResponseClient`, you'll need to configure it as shown in the following example:
.Access Token Response Configuration via Builder
[tabs] [tabs]
====== ======
Java:: Java::
@ -1008,7 +959,7 @@ ReactiveOAuth2AuthorizedClientProvider authorizedClientProvider =
.provider(jwtBearerAuthorizedClientProvider) .provider(jwtBearerAuthorizedClientProvider)
.build(); .build();
... // ...
authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider); authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);
---- ----
@ -1027,12 +978,13 @@ val authorizedClientProvider = ReactiveOAuth2AuthorizedClientProviderBuilder.bui
.provider(jwtBearerAuthorizedClientProvider) .provider(jwtBearerAuthorizedClientProvider)
.build() .build()
... // ...
authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider) authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
---- ----
====== ======
[[oauth2-client-jwt-bearer-authorized-client-manager]]
=== Using the Access Token === Using the Access Token
Given the following Spring Boot properties for an OAuth 2.0 Client registration: Given the following Spring Boot properties for an OAuth 2.0 Client registration:
@ -1126,7 +1078,8 @@ public class OAuth2ResourceServerController {
return this.authorizedClientManager.authorize(authorizeRequest) return this.authorizedClientManager.authorize(authorizeRequest)
.map(OAuth2AuthorizedClient::getAccessToken) .map(OAuth2AuthorizedClient::getAccessToken)
... // ...
.thenReturn("index");
} }
} }
---- ----
@ -1147,7 +1100,8 @@ class OAuth2ResourceServerController {
.build() .build()
return authorizedClientManager.authorize(authorizeRequest) return authorizedClientManager.authorize(authorizeRequest)
.map { it.accessToken } .map { it.accessToken }
... // ...
.thenReturn("index")
} }
} }
---- ----
@ -1159,13 +1113,13 @@ class OAuth2ResourceServerController {
[TIP] [TIP]
If you need to resolve the `Jwt` assertion from a different source, you can provide `JwtBearerReactiveOAuth2AuthorizedClientProvider.setJwtAssertionResolver()` with a custom `Function<OAuth2AuthorizationContext, Mono<Jwt>>`. If you need to resolve the `Jwt` assertion from a different source, you can provide `JwtBearerReactiveOAuth2AuthorizedClientProvider.setJwtAssertionResolver()` with a custom `Function<OAuth2AuthorizationContext, Mono<Jwt>>`.
[[oauth2Client-token-exchange-grant]] [[oauth2-client-token-exchange]]
== Token Exchange == [[oauth2Client-token-exchange-grant]]Token Exchange
[NOTE] [NOTE]
Please refer to OAuth 2.0 Token Exchange for further details on the https://datatracker.ietf.org/doc/html/rfc8693[Token Exchange] grant. Please refer to OAuth 2.0 Token Exchange for further details on the https://datatracker.ietf.org/doc/html/rfc8693[Token Exchange] grant.
[[oauth2-client-token-exchange-access-token]]
=== Requesting an Access Token === Requesting an Access Token
[NOTE] [NOTE]
@ -1173,32 +1127,21 @@ Please refer to the https://datatracker.ietf.org/doc/html/rfc8693#section-2[Toke
The default implementation of `ReactiveOAuth2AccessTokenResponseClient` for the Token Exchange grant is `WebClientReactiveTokenExchangeTokenResponseClient`, which uses a `WebClient` when requesting an access token at the Authorization Server’s Token Endpoint. The default implementation of `ReactiveOAuth2AccessTokenResponseClient` for the Token Exchange grant is `WebClientReactiveTokenExchangeTokenResponseClient`, which uses a `WebClient` when requesting an access token at the Authorization Server’s Token Endpoint.
The `WebClientReactiveTokenExchangeTokenResponseClient` is quite flexible as it allows you to customize the pre-processing of the Token Request and/or post-handling of the Token Response. :section-id: token-exchange
:grant-type: Token Exchange
:class-name: WebClientReactiveTokenExchangeTokenResponseClient
:grant-request: TokenExchangeGrantRequest
:leveloffset: +1
include::partial$reactive/oauth2/client/web-client-access-token-response-client.adoc[]
:leveloffset: -1
=== Customizing the Access Token Request [[oauth2-client-token-exchange-authorized-client-provider-builder]]
=== Customize using the Builder
If you need to customize the pre-processing of the Token Request, you can provide `WebClientReactiveTokenExchangeTokenResponseClient.setParametersConverter()` with a custom `Converter<TokenExchangeGrantRequest, MultiValueMap<String, String>>`. Whether you customize `WebClientReactiveTokenExchangeTokenResponseClient` or provide your own implementation of `ReactiveOAuth2AccessTokenResponseClient`, you can configure it using the `ReactiveOAuth2AuthorizedClientProviderBuilder` (as an alternative to <<oauth2-client-token-exchange-access-token-response-client-bean,publishing a bean>>) as follows:
The default implementation builds a `MultiValueMap<String, String>` containing only the `grant_type` parameter of a standard https://tools.ietf.org/html/rfc6749#section-4.4.2[OAuth 2.0 Access Token Request] which is used to construct the request.
Other parameters required by the Token Exchange grant are added directly to the body of the request by the `WebClientReactiveTokenExchangeTokenResponseClient`.
However, providing a custom `Converter`, would allow you to extend the standard Token Request and add custom parameter(s).
[TIP]
If you prefer to only add additional parameters, you can instead provide `WebClientReactiveTokenExchangeTokenResponseClient.addParametersConverter()` with a custom `Converter<TokenExchangeGrantRequest, MultiValueMap<String, String>>` which constructs an aggregate `Converter`.
IMPORTANT: The custom `Converter` must return valid parameters of an OAuth 2.0 Access Token Request that is understood by the intended OAuth 2.0 Provider.
=== Customizing the Access Token Response
On the other end, if you need to customize the post-handling of the Token Response, you will need to provide `WebClientReactiveTokenExchangeTokenResponseClient.setBodyExtractor()` with a custom configured `BodyExtractor<Mono<OAuth2AccessTokenResponse>, ReactiveHttpInputMessage>` that is used for converting the OAuth 2.0 Access Token Response to an `OAuth2AccessTokenResponse`.
The default implementation provided by `OAuth2BodyExtractors.oauth2AccessTokenResponse()` parses the response and handles errors accordingly.
=== Customizing the `WebClient`
Alternatively, if your requirements are more advanced, you can take full control of the request/response by simply providing `WebClientReactiveTokenExchangeTokenResponseClient.setWebClient()` with a custom configured `WebClient`.
Whether you customize `WebClientReactiveTokenExchangeTokenResponseClient` or provide your own implementation of `ReactiveOAuth2AccessTokenResponseClient`, you'll need to configure it as shown in the following example:
.Access Token Response Configuration via Builder
[tabs] [tabs]
====== ======
Java:: Java::
@ -1216,7 +1159,7 @@ ReactiveOAuth2AuthorizedClientProvider authorizedClientProvider =
.provider(tokenExchangeAuthorizedClientProvider) .provider(tokenExchangeAuthorizedClientProvider)
.build(); .build();
... // ...
authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider); authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider);
---- ----
@ -1235,12 +1178,13 @@ val authorizedClientProvider = ReactiveOAuth2AuthorizedClientProviderBuilder.bui
.provider(tokenExchangeAuthorizedClientProvider) .provider(tokenExchangeAuthorizedClientProvider)
.build() .build()
... // ...
authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider) authorizedClientManager.setAuthorizedClientProvider(authorizedClientProvider)
---- ----
====== ======
[[oauth2-client-token-exchange-authorized-client-manager]]
=== Using the Access Token === Using the Access Token
Given the following Spring Boot properties for an OAuth 2.0 Client registration: Given the following Spring Boot properties for an OAuth 2.0 Client registration:
@ -1334,7 +1278,8 @@ public class OAuth2ResourceServerController {
return this.authorizedClientManager.authorize(authorizeRequest) return this.authorizedClientManager.authorize(authorizeRequest)
.map(OAuth2AuthorizedClient::getAccessToken) .map(OAuth2AuthorizedClient::getAccessToken)
... // ...
.thenReturn("index");
} }
} }
---- ----
@ -1355,7 +1300,8 @@ class OAuth2ResourceServerController {
.build() .build()
return authorizedClientManager.authorize(authorizeRequest) return authorizedClientManager.authorize(authorizeRequest)
.map { it.accessToken } .map { it.accessToken }
... // ...
.thenReturn("index")
} }
} }
---- ----

21
docs/modules/ROOT/pages/reactive/oauth2/client/authorized-clients.adoc
View File

@ -1,9 +1,10 @@
[[oauth2Client-additional-features]] [[oauth2-client-additional-features]]
= Authorized Clients = [[oauth2Client-additional-features]]Authorized Client Features
This section covers additional features provided by Spring Security for OAuth2 Client.
[[oauth2Client-registered-authorized-client]] [[oauth2-client-registered-authorized-client]]
== Resolving an Authorized Client == [[oauth2Client-registered-authorized-client]]Resolving an Authorized Client
The `@RegisteredOAuth2AuthorizedClient` annotation provides the capability of resolving a method parameter to an argument value of type `OAuth2AuthorizedClient`. The `@RegisteredOAuth2AuthorizedClient` annotation provides the capability of resolving a method parameter to an argument value of type `OAuth2AuthorizedClient`.
This is a convenient alternative compared to accessing the `OAuth2AuthorizedClient` using the `ReactiveOAuth2AuthorizedClientManager` or `ReactiveOAuth2AuthorizedClientService`. This is a convenient alternative compared to accessing the `OAuth2AuthorizedClient` using the `ReactiveOAuth2AuthorizedClientManager` or `ReactiveOAuth2AuthorizedClientService`.
@ -42,16 +43,15 @@ class OAuth2ClientController {
---- ----
====== ======
The `@RegisteredOAuth2AuthorizedClient` annotation is handled by `OAuth2AuthorizedClientArgumentResolver`, which directly uses a <<oauth2Client-authorized-manager-provider, ReactiveOAuth2AuthorizedClientManager>> and therefore inherits it's capabilities. The `@RegisteredOAuth2AuthorizedClient` annotation is handled by `OAuth2AuthorizedClientArgumentResolver`, which directly uses a xref:reactive/oauth2/client/core.adoc#oauth2Client-authorized-manager-provider[ReactiveOAuth2AuthorizedClientManager] and therefore inherits it's capabilities.
[[oauth2-client-web-client]]
[[oauth2Client-webclient-webflux]] == [[oauth2Client-webclient-webflux]]WebClient integration for Reactive Environments
== WebClient integration for Reactive Environments
The OAuth 2.0 Client support integrates with `WebClient` using an `ExchangeFilterFunction`. The OAuth 2.0 Client support integrates with `WebClient` using an `ExchangeFilterFunction`.
The `ServerOAuth2AuthorizedClientExchangeFilterFunction` provides a simple mechanism for requesting protected resources by using an `OAuth2AuthorizedClient` and including the associated `OAuth2AccessToken` as a Bearer Token. The `ServerOAuth2AuthorizedClientExchangeFilterFunction` provides a simple mechanism for requesting protected resources by using an `OAuth2AuthorizedClient` and including the associated `OAuth2AccessToken` as a Bearer Token.
It directly uses an <<oauth2Client-authorized-manager-provider, ReactiveOAuth2AuthorizedClientManager>> and therefore inherits the following capabilities: It directly uses an xref:reactive/oauth2/client/core.adoc#oauth2Client-authorized-manager-provider[ReactiveOAuth2AuthorizedClientManager] and therefore inherits the following capabilities:
* An `OAuth2AccessToken` will be requested if the client has not yet been authorized. * An `OAuth2AccessToken` will be requested if the client has not yet been authorized.
** `authorization_code` - triggers the Authorization Request redirect to initiate the flow ** `authorization_code` - triggers the Authorization Request redirect to initiate the flow
@ -91,6 +91,7 @@ fun webClient(authorizedClientManager: ReactiveOAuth2AuthorizedClientManager): W
---- ----
====== ======
[[oauth2-client-web-client-authorized-client]]
=== Providing the Authorized Client === Providing the Authorized Client
The `ServerOAuth2AuthorizedClientExchangeFilterFunction` determines the client to use (for a request) by resolving the `OAuth2AuthorizedClient` from the `ClientRequest.attributes()` (request attributes). The `ServerOAuth2AuthorizedClientExchangeFilterFunction` determines the client to use (for a request) by resolving the `OAuth2AuthorizedClient` from the `ClientRequest.attributes()` (request attributes).
@ -184,7 +185,7 @@ fun index(): Mono<String> {
====== ======
<1> `clientRegistrationId()` is a `static` method in `ServerOAuth2AuthorizedClientExchangeFilterFunction`. <1> `clientRegistrationId()` is a `static` method in `ServerOAuth2AuthorizedClientExchangeFilterFunction`.
[[oauth2-client-web-client-default-authorized-client]]
=== Defaulting the Authorized Client === Defaulting the Authorized Client
If neither `OAuth2AuthorizedClient` or `ClientRegistration.getRegistrationId()` is provided as a request attribute, the `ServerOAuth2AuthorizedClientExchangeFilterFunction` can determine the _default_ client to use depending on it's configuration. If neither `OAuth2AuthorizedClient` or `ClientRegistration.getRegistrationId()` is provided as a request attribute, the `ServerOAuth2AuthorizedClientExchangeFilterFunction` can determine the _default_ client to use depending on it's configuration.

23
docs/modules/ROOT/pages/reactive/oauth2/client/client-authentication.adoc
View File

@ -1,9 +1,10 @@
[[oauth2Client-client-auth-support]] [[oauth2-client-authentication]]
= Client Authentication Support = [[oauth2Client-client-auth-support]]Client Authentication Support
[[oauth2Client-client-credentials-auth]] [[oauth2-client-authentication-client-credentials]]
== Client Credentials == [[oauth2Client-client-credentials-auth]]Client Credentials
[[oauth2-client-authentication-client-credentials-client-secret-basic]]
=== Authenticate using `client_secret_basic` === Authenticate using `client_secret_basic`
Client Authentication with HTTP Basic is supported out of the box and no customization is necessary to enable it. Client Authentication with HTTP Basic is supported out of the box and no customization is necessary to enable it.
@ -55,6 +56,7 @@ tokenResponseClient.setHeadersConverter(headersConverter)
---- ----
====== ======
[[oauth2-client-authentication-client-credentials-client-secret-post]]
=== Authenticate using `client_secret_post` === Authenticate using `client_secret_post`
Client Authentication with client credentials included in the request-body is supported out of the box and no customization is necessary to enable it. Client Authentication with client credentials included in the request-body is supported out of the box and no customization is necessary to enable it.
@ -76,8 +78,8 @@ spring:
... ...
---- ----
[[oauth2Client-jwt-bearer-auth]] [[oauth2-client-authentication-jwt-bearer]]
== JWT Bearer == [[oauth2Client-jwt-bearer-auth]]JWT Bearer
[NOTE] [NOTE]
Please refer to JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants for further details on https://datatracker.ietf.org/doc/html/rfc7523#section-2.2[JWT Bearer] Client Authentication. Please refer to JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants for further details on https://datatracker.ietf.org/doc/html/rfc7523#section-2.2[JWT Bearer] Client Authentication.
@ -89,7 +91,7 @@ a signed JSON Web Token (JWS) in the `client_assertion` parameter.
The `java.security.PrivateKey` or `javax.crypto.SecretKey` used for signing the JWS The `java.security.PrivateKey` or `javax.crypto.SecretKey` used for signing the JWS
is supplied by the `com.nimbusds.jose.jwk.JWK` resolver associated with `NimbusJwtClientAuthenticationParametersConverter`. is supplied by the `com.nimbusds.jose.jwk.JWK` resolver associated with `NimbusJwtClientAuthenticationParametersConverter`.
[[oauth2-client-authentication-jwt-bearer-private-key-jwt]]
=== Authenticate using `private_key_jwt` === Authenticate using `private_key_jwt`
Given the following Spring Boot properties for an OAuth 2.0 Client registration: Given the following Spring Boot properties for an OAuth 2.0 Client registration:
@ -160,7 +162,7 @@ tokenResponseClient.addParametersConverter(
---- ----
====== ======
[[oauth2-client-authentication-jwt-bearer-client-secret-jwt]]
=== Authenticate using `client_secret_jwt` === Authenticate using `client_secret_jwt`
Given the following Spring Boot properties for an OAuth 2.0 Client registration: Given the following Spring Boot properties for an OAuth 2.0 Client registration:
@ -230,6 +232,7 @@ tokenResponseClient.addParametersConverter(
---- ----
====== ======
[[oauth2-client-authentication-jwt-bearer-assertion]]
=== Customizing the JWT assertion === Customizing the JWT assertion
The JWT produced by `NimbusJwtClientAuthenticationParametersConverter` contains the `iss`, `sub`, `aud`, `jti`, `iat` and `exp` claims by default. You can customize the headers and/or claims by providing a `Consumer<NimbusJwtClientAuthenticationParametersConverter.JwtClientAuthenticationContext<T>>` to `setJwtClientAssertionCustomizer()`. The following example shows how to customize claims of the JWT: The JWT produced by `NimbusJwtClientAuthenticationParametersConverter` contains the `iss`, `sub`, `aud`, `jti`, `iat` and `exp` claims by default. You can customize the headers and/or claims by providing a `Consumer<NimbusJwtClientAuthenticationParametersConverter.JwtClientAuthenticationContext<T>>` to `setJwtClientAssertionCustomizer()`. The following example shows how to customize claims of the JWT:
@ -265,8 +268,8 @@ converter.setJwtClientAssertionCustomizer { context ->
---- ----
====== ======
[[oauth2Client-public-auth]] [[oauth2-client-authentication-public]]
== Public Authentication == [[oauth2Client-public-auth]]Public Authentication
Public Client Authentication is supported out of the box and no customization is necessary to enable it. Public Client Authentication is supported out of the box and no customization is necessary to enable it.

16
docs/modules/ROOT/pages/reactive/oauth2/client/index.adoc
View File

@ -7,18 +7,18 @@ The OAuth 2.0 Client features provide support for the Client role as defined in
At a high-level, the core features available are: At a high-level, the core features available are:
.Authorization Grant support .Authorization Grant support
* https://tools.ietf.org/html/rfc6749#section-1.3.1[Authorization Code] * xref:reactive/oauth2/client/authorization-grants.adoc#oauth2-client-authorization-code[Authorization Code]
* https://tools.ietf.org/html/rfc6749#section-6[Refresh Token] * xref:reactive/oauth2/client/authorization-grants.adoc#oauth2-client-refresh-token[Refresh Token]
* https://tools.ietf.org/html/rfc6749#section-1.3.4[Client Credentials] * xref:reactive/oauth2/client/authorization-grants.adoc#oauth2-client-client-credentials[Client Credentials]
* https://tools.ietf.org/html/rfc6749#section-1.3.3[Resource Owner Password Credentials] * xref:reactive/oauth2/client/authorization-grants.adoc#oauth2-client-password[Resource Owner Password Credentials]
* https://datatracker.ietf.org/doc/html/rfc7523#section-2.1[JWT Bearer] * xref:reactive/oauth2/client/authorization-grants.adoc#oauth2-client-jwt-bearer[JWT Bearer]
* https://datatracker.ietf.org/doc/html/rfc8693#section-2.1[Token Exchange] * xref:reactive/oauth2/client/authorization-grants.adoc#oauth2-client-token-exchange[Token Exchange]
.Client Authentication support .Client Authentication support
* https://datatracker.ietf.org/doc/html/rfc7523#section-2.2[JWT Bearer] * xref:reactive/oauth2/client/client-authentication.adoc#oauth2-client-authentication-jwt-bearer[JWT Bearer]
.HTTP Client support .HTTP Client support
* xref:reactive/oauth2/client/authorized-clients.adoc#oauth2Client-webclient-webflux[`WebClient` integration for Reactive Environments] (for requesting protected resources) * xref:reactive/oauth2/client/authorized-clients.adoc#oauth2-client-web-client[`WebClient` integration for Reactive Environments] (for requesting protected resources)
The `ServerHttpSecurity.oauth2Client()` DSL provides a number of configuration options for customizing the core components used by OAuth 2.0 Client. The `ServerHttpSecurity.oauth2Client()` DSL provides a number of configuration options for customizing the core components used by OAuth 2.0 Client.

4
docs/modules/ROOT/pages/reactive/oauth2/index.adoc
View File

@ -166,7 +166,7 @@ class SecurityConfig {
[[oauth2-resource-server-access-token-opaque]] [[oauth2-resource-server-access-token-opaque]]
==== Opaque Token Support ==== Opaque Token Support
The following example configures an `OpaqueTokenIntrospector` bean using Spring Boot configuration properties: The following example configures an `ReactiveOpaqueTokenIntrospector` bean using Spring Boot configuration properties:
[source,yaml] [source,yaml]
---- ----
@ -1608,7 +1608,7 @@ class SecurityConfig {
[[further-reading]] [[further-reading]]
== Further Reading == Further Reading
This preceding sections introduced Spring Security's support for OAuth2 with examples for common scenarios. The preceding sections introduced Spring Security's support for OAuth2 with examples for common scenarios.
You can read more about OAuth2 Client and Resource Server in the following sections of the reference documentation: You can read more about OAuth2 Client and Resource Server in the following sections of the reference documentation:
* xref:reactive/oauth2/login/index.adoc[] * xref:reactive/oauth2/login/index.adoc[]

334
docs/modules/ROOT/partials/reactive/oauth2/client/web-client-access-token-response-client.adoc Normal file
View File

@ -0,0 +1,334 @@
To customize `{class-name}`, simply provide a bean as in the following example and it will be picked up by the default `ReactiveOAuth2AuthorizedClientManager` automatically:
[#oauth2-client-{section-id}-access-token-response-client-bean]
.Access Token Response Configuration
[tabs]
======
Java::
+
[source,java,role="primary",subs="+attributes"]
----
@Bean
public ReactiveOAuth2AccessTokenResponseClient<{grant-request}> accessTokenResponseClient() {
{class-name} accessTokenResponseClient =
new {class-name}();
// ...
return accessTokenResponseClient;
}
----
Kotlin::
+
[source,kotlin,role="secondary",subs="+attributes"]
----
@Bean
fun accessTokenResponseClient(): ReactiveOAuth2AccessTokenResponseClient<{grant-type}> {
val accessTokenResponseClient = {class-name}()
// ...
return accessTokenResponseClient
}
----
======
`{class-name}` is very flexible and provides several options for customizing the OAuth 2.0 Access Token request and response for the {grant-type} grant.
Choose from the following use cases to learn more:
* I want to <<oauth2-client-{section-id}-access-token-request-headers,customize headers of the Access Token request>>
* I want to <<oauth2-client-{section-id}-access-token-request-parameters,customize parameters of the Access Token request>>
* I want to <<oauth2-client-{section-id}-access-token-response-parameters,customize parameters of the Access Token response>>
* I want to <<oauth2-client-{section-id}-access-token-response-web-client,customize the instance of `WebClient` that is used>>
[#oauth2-client-{section-id}-access-token-request]
== Customizing the Access Token Request
`{class-name}` provides hooks for customizing HTTP headers and request parameters of the Token Request.
[#oauth2-client-{section-id}-access-token-request-headers]
=== Customizing Request Headers
There are two options for customizing HTTP headers:
* Add additional headers by calling `addHeadersConverter()`
* Fully customize headers by calling `setHeadersConverter()`
You can include additional headers without affecting the default headers added to every request using `addHeadersConverter()`.
The following example adds a `User-Agent` header to the request when the `registrationId` is `spring`:
.Include Additional HTTP Headers
[tabs]
======
Java::
+
[source,java,role="primary",subs="+attributes"]
----
{class-name} accessTokenResponseClient =
new {class-name}();
accessTokenResponseClient.addHeadersConverter(grantRequest -> {
ClientRegistration clientRegistration = grantRequest.getClientRegistration();
HttpHeaders headers = new HttpHeaders();
if (clientRegistration.getRegistrationId().equals("spring")) {
headers.set(HttpHeaders.USER_AGENT, "my-user-agent");
}
return headers;
});
----
Kotlin::
+
[source,kotlin,role="secondary",subs="+attributes"]
----
val accessTokenResponseClient = {class-name}()
accessTokenResponseClient.addHeadersConverter { grantRequest ->
val clientRegistration = grantRequest.getClientRegistration()
val headers = HttpHeaders()
if (clientRegistration.getRegistrationId() == "spring") {
headers[HttpHeaders.USER_AGENT] = "my-user-agent"
}
headers
}
----
======
You can fully customize headers by re-using `DefaultOAuth2TokenRequestHeadersConverter` or providing a custom implementation using `setHeadersConverter()`.
The following example re-uses `DefaultOAuth2TokenRequestHeadersConverter` and disables `encodeClientCredentials` so that HTTP Basic credentials are no longer encoded with `application/x-www-form-urlencoded`:
.Customize HTTP Headers
[tabs]
======
Java::
+
[source,java,role="primary",subs="+attributes"]
----
DefaultOAuth2TokenRequestHeadersConverter headersConverter =
new DefaultOAuth2TokenRequestHeadersConverter();
headersConverter.setEncodeClientCredentials(false);
{class-name} accessTokenResponseClient =
new {class-name}();
accessTokenResponseClient.setHeadersConverter(headersConverter);
----
Kotlin::
+
[source,kotlin,role="secondary",subs="+attributes"]
----
val headersConverter = DefaultOAuth2TokenRequestHeadersConverter()
headersConverter.setEncodeClientCredentials(false)
val accessTokenResponseClient = {class-name}()
accessTokenResponseClient.setHeadersConverter(headersConverter)
----
======
[#oauth2-client-{section-id}-access-token-request-parameters]
=== Customizing Request Parameters
There are three options for customizing request parameters:
* Add additional parameters by calling `addParametersConverter()`
* Override parameters by calling `setParametersConverter()`
* Fully customize parameters by calling `setParametersCustomizer()`
[NOTE]
====
Using `setParametersConverter()` does not fully customize parameters because it would require the user to provide all default parameters themselves.
Default parameters are always provided, but can be fully customized or omitted by calling `setParametersCustomizer()`.
====
You can include additional parameters without affecting the default parameters added to every request using `addParametersConverter()`.
The following example adds an `audience` parameter to the request when the `registrationId` is `keycloak`:
.Include Additional Request Parameters
[tabs]
======
Java::
+
[source,java,role="primary",subs="+attributes"]
----
{class-name} accessTokenResponseClient =
new {class-name}();
accessTokenResponseClient.addParametersConverter(grantRequest -> {
ClientRegistration clientRegistration = grantRequest.getClientRegistration();
MultiValueMap<String, String> parameters = new LinkedMultiValueMap<String, String>();
if (clientRegistration.getRegistrationId().equals("keycloak")) {
parameters.set(OAuth2ParameterNames.AUDIENCE, "my-audience");
}
return parameters;
});
----
Kotlin::
+
[source,kotlin,role="secondary",subs="+attributes"]
----
val accessTokenResponseClient = {class-name}()
accessTokenResponseClient.addParametersConverter { grantRequest ->
val clientRegistration = grantRequest.getClientRegistration()
val parameters = LinkedMultiValueMap<String, String>()
if (clientRegistration.getRegistrationId() == "keycloak") {
parameters[OAuth2ParameterNames.AUDIENCE] = "my-audience"
}
parameters
}
----
======
You can override default parameters using `setParametersConverter()`.
The following example overrides the `client_id` parameter when the `registrationId` is `okta`:
.Override Request Parameters
[tabs]
======
Java::
+
[source,java,role="primary",subs="+attributes"]
----
{class-name} accessTokenResponseClient =
new {class-name}();
accessTokenResponseClient.setParametersConverter(grantRequest -> {
ClientRegistration clientRegistration = grantRequest.getClientRegistration();
LinkedMultiValueMap<String, String> parameters = new LinkedMultiValueMap<>();
if (clientRegistration.getRegistrationId().equals("okta")) {
parameters.set(OAuth2ParameterNames.CLIENT_ID, "my-client");
}
return parameters;
});
----
Kotlin::
+
[source,kotlin,role="secondary",subs="+attributes"]
----
val accessTokenResponseClient = {class-name}()
accessTokenResponseClient.setParametersConverter { grantRequest ->
val clientRegistration = grantRequest.getClientRegistration()
val parameters = LinkedMultiValueMap<String, String>()
if (clientRegistration.getRegistrationId() == "okta") {
parameters[OAuth2ParameterNames.CLIENT_ID] = "my-client"
}
parameters
}
----
======
You can fully customize parameters (including omitting default parameters) using `setParametersCustomizer()`.
The following example omits the `client_id` parameter when the `client_assertion` parameter is present in the request:
.Omit Request Parameters
[tabs]
======
Java::
+
[source,java,role="primary",subs="+attributes"]
----
{class-name} accessTokenResponseClient =
new {class-name}();
accessTokenResponseClient.setParametersCustomizer(parameters -> {
if (parameters.containsKey(OAuth2ParameterNames.CLIENT_ASSERTION)) {
parameters.remove(OAuth2ParameterNames.CLIENT_ID);
}
});
----
Kotlin::
+
[source,kotlin,role="secondary",subs="+attributes"]
----
val accessTokenResponseClient = {class-name}()
accessTokenResponseClient.setParametersCustomizer { parameters ->
if (parameters.containsKey(OAuth2ParameterNames.CLIENT_ASSERTION)) {
parameters.remove(OAuth2ParameterNames.CLIENT_ID)
}
}
----
======
[#oauth2-client-{section-id}-access-token-response]
== Customizing the Access Token Response
`{class-name}` provides hooks for customizing the OAuth 2.0 Access Token Response.
[#oauth2-client-{section-id}-access-token-response-parameters]
=== Customizing Response Parameters
You can customize the conversion of Token Response parameters to an `OAuth2AccessTokenResponse` by calling `setBodyExtractor()`.
The default implementation provided by `OAuth2BodyExtractors.oauth2AccessTokenResponse()` parses the response and handles errors accordingly.
The following example provides a starting point for customizing the conversion of Token Response parameters to an `OAuth2AccessTokenResponse`:
.Customize Body Extractor
[tabs]
======
Java::
+
[source,java,role="primary",subs="+attributes"]
----
{class-name} accessTokenResponseClient =
new {class-name}();
BodyExtractor<Mono<Map<String, Object>>, ReactiveHttpInputMessage> bodyExtractor =
BodyExtractors.toMono(new ParameterizedTypeReference<>() {});
accessTokenResponseClient.setBodyExtractor((inputMessage, context) ->
bodyExtractor.extract(inputMessage, context)
.map(parameters -> OAuth2AccessTokenResponse.withToken("custom-token")
// ...
.build()
)
);
----
Kotlin::
+
[source,kotlin,role="secondary",subs="+attributes"]
----
val accessTokenResponseClient = {class-name}()
val bodyExtractor = BodyExtractors.toMono(object : ParameterizedTypeReference<Map<String, Any>>() {})
accessTokenResponseClient.setBodyExtractor { inputMessage, context ->
bodyExtractor.extract(inputMessage, context).map { parameters ->
OAuth2AccessTokenResponse.withToken("custom-token")
// ...
.build()
}
}
----
======
[CAUTION]
====
When providing a custom `BodyExtractor`, you are responsible for detecting and converting an OAuth 2.0 Error Response to a `Mono.error()` with `OAuth2Error` based on parameters of the response.
====
[#oauth2-client-{section-id}-access-token-response-web-client]
=== Customizing the `WebClient`
Alternatively, if your requirements are more advanced, you can take full control of the request and/or response by providing a pre-configured `WebClient` to `setWebClient()` as the following example shows:
.Customize `WebClient`
[tabs]
======
Java::
+
[source,java,role="primary",subs="+attributes"]
----
WebClient webClient = WebClient.builder()
// ...
.build();
{class-name} accessTokenResponseClient =
new {class-name}();
accessTokenResponseClient.setWebClient(webClient);
----
Kotlin::
+
[source,kotlin,role="secondary",subs="+attributes"]
----
val webClient = WebClient.builder()
// ...
.build()
val accessTokenResponseClient = {class-name}()
accessTokenResponseClient.setWebClient(webClient)
----
======