From 2dd908dff8bb5ebf376912ea02fadb885a5877fd Mon Sep 17 00:00:00 2001 From: Steve Riesenberg <5248162+sjohnr@users.noreply.github.com> Date: Mon, 29 Apr 2024 12:32:26 -0500 Subject: [PATCH] Document additional client authenticating methods Issue gh-11440 Closes gh-14982 --- .../oauth2/client/client-authentication.adoc | 99 ++++++++++++++++ .../oauth2/client/client-authentication.adoc | 106 ++++++++++++++++++ 2 files changed, 205 insertions(+) diff --git a/docs/modules/ROOT/pages/reactive/oauth2/client/client-authentication.adoc b/docs/modules/ROOT/pages/reactive/oauth2/client/client-authentication.adoc index 3bcf7c778f0..8c1a1f58503 100644 --- a/docs/modules/ROOT/pages/reactive/oauth2/client/client-authentication.adoc +++ b/docs/modules/ROOT/pages/reactive/oauth2/client/client-authentication.adoc @@ -1,6 +1,80 @@ [[oauth2Client-client-auth-support]] = Client Authentication Support +[[oauth2Client-client-credentials-auth]] +== Client Credentials + +=== Authenticate using `client_secret_basic` + +Client Authentication with HTTP Basic is supported out of the box and no customization is necessary to enable it. +The default implementation is provided by `DefaultOAuth2TokenRequestHeadersConverter`. + +Given the following Spring Boot properties for an OAuth 2.0 client registration: + +[source,yaml] +---- +spring: + security: + oauth2: + client: + registration: + okta: + client-id: client-id + client-secret: client-secret + client-authentication-method: client_secret_basic + authorization-grant-type: authorization_code + ... +---- + +The following example shows how to configure `WebClientReactiveAuthorizationCodeTokenResponseClient` to disable URL encoding of the client credentials: + +[tabs] +====== +Java:: ++ +[source,java,role="primary"] +---- +DefaultOAuth2TokenRequestHeadersConverter headersConverter = + new DefaultOAuth2TokenRequestHeadersConverter<>(); +headersConverter.setEncodeClientCredentials(false); + +WebClientReactiveAuthorizationCodeTokenResponseClient tokenResponseClient = + new WebClientReactiveAuthorizationCodeTokenResponseClient(); +tokenResponseClient.setHeadersConverter(headersConverter); +---- + +Kotlin:: ++ +[source,kotlin,role="secondary"] +---- +val headersConverter = DefaultOAuth2TokenRequestHeadersConverter() +headersConverter.setEncodeClientCredentials(false) + +val tokenResponseClient = WebClientReactiveAuthorizationCodeTokenResponseClient() +tokenResponseClient.setHeadersConverter(headersConverter) +---- +====== + +=== 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. + +The following Spring Boot properties for an OAuth 2.0 client registration demonstrate the configuration: + +[source,yaml] +---- +spring: + security: + oauth2: + client: + registration: + okta: + client-id: client-id + client-secret: client-secret + client-authentication-method: client_secret_post + authorization-grant-type: authorization_code + ... +---- [[oauth2Client-jwt-bearer-auth]] == JWT Bearer @@ -190,3 +264,28 @@ converter.setJwtClientAssertionCustomizer { context -> } ---- ====== + +[[oauth2Client-public-auth]] +== Public Authentication + +Public Client Authentication is supported out of the box and no customization is necessary to enable it. + +The following Spring Boot properties for an OAuth 2.0 client registration demonstrate the configuration: + +[source,yaml] +---- +spring: + security: + oauth2: + client: + registration: + okta: + client-id: client-id + client-authentication-method: none + authorization-grant-type: authorization_code + ... +---- + +[NOTE] +Public Clients are supported using https://tools.ietf.org/html/rfc7636[Proof Key for Code Exchange] (PKCE). +PKCE will automatically be used when `client-authentication-method` is set to "none" (`ClientAuthenticationMethod.NONE`). diff --git a/docs/modules/ROOT/pages/servlet/oauth2/client/client-authentication.adoc b/docs/modules/ROOT/pages/servlet/oauth2/client/client-authentication.adoc index af81f36aebb..edc3be5a37e 100644 --- a/docs/modules/ROOT/pages/servlet/oauth2/client/client-authentication.adoc +++ b/docs/modules/ROOT/pages/servlet/oauth2/client/client-authentication.adoc @@ -1,6 +1,87 @@ [[oauth2Client-client-auth-support]] = Client Authentication Support +[[oauth2Client-client-credentials-auth]] +== Client Credentials + +=== Authenticate using `client_secret_basic` + +Client Authentication with HTTP Basic is supported out of the box and no customization is necessary to enable it. +The default implementation is provided by `DefaultOAuth2TokenRequestHeadersConverter`. + +Given the following Spring Boot properties for an OAuth 2.0 client registration: + +[source,yaml] +---- +spring: + security: + oauth2: + client: + registration: + okta: + client-id: client-id + client-secret: client-secret + client-authentication-method: client_secret_basic + authorization-grant-type: authorization_code + ... +---- + +The following example shows how to configure `DefaultAuthorizationCodeTokenResponseClient` to disable URL encoding of the client credentials: + +[tabs] +====== +Java:: ++ +[source,java,role="primary"] +---- +DefaultOAuth2TokenRequestHeadersConverter headersConverter = + new DefaultOAuth2TokenRequestHeadersConverter<>(); +headersConverter.setEncodeClientCredentials(false); + +OAuth2AuthorizationCodeGrantRequestEntityConverter requestEntityConverter = + new OAuth2AuthorizationCodeGrantRequestEntityConverter(); +requestEntityConverter.setHeadersConverter(headersConverter); + +DefaultAuthorizationCodeTokenResponseClient tokenResponseClient = + new DefaultAuthorizationCodeTokenResponseClient(); +tokenResponseClient.setRequestEntityConverter(requestEntityConverter); +---- + +Kotlin:: ++ +[source,kotlin,role="secondary"] +---- +val headersConverter = DefaultOAuth2TokenRequestHeadersConverter() +headersConverter.setEncodeClientCredentials(false) + +val requestEntityConverter = OAuth2AuthorizationCodeGrantRequestEntityConverter() +requestEntityConverter.setHeadersConverter(headersConverter) + +val tokenResponseClient = DefaultAuthorizationCodeTokenResponseClient() +tokenResponseClient.setRequestEntityConverter(requestEntityConverter) +---- +====== + +=== 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. + +The following Spring Boot properties for an OAuth 2.0 client registration demonstrate the configuration: + +[source,yaml] +---- +spring: + security: + oauth2: + client: + registration: + okta: + client-id: client-id + client-secret: client-secret + client-authentication-method: client_secret_post + authorization-grant-type: authorization_code + ... +---- [[oauth2Client-jwt-bearer-auth]] == JWT Bearer @@ -203,3 +284,28 @@ converter.setJwtClientAssertionCustomizer { context -> } ---- ====== + +[[oauth2Client-public-auth]] +== Public Authentication + +Public Client Authentication is supported out of the box and no customization is necessary to enable it. + +The following Spring Boot properties for an OAuth 2.0 client registration demonstrate the configuration: + +[source,yaml] +---- +spring: + security: + oauth2: + client: + registration: + okta: + client-id: client-id + client-authentication-method: none + authorization-grant-type: authorization_code + ... +---- + +[NOTE] +Public Clients are supported using https://tools.ietf.org/html/rfc7636[Proof Key for Code Exchange] (PKCE). +PKCE will automatically be used when `client-authentication-method` is set to "none" (`ClientAuthenticationMethod.NONE`).