Document requireProofKey

Issue gh-16386

Author: rwinch

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

@@ -79,6 +79,10 @@ If the client is running in an untrusted environment (eg. native application or
 . `client-secret` is omitted (or empty)
 . `client-authentication-method` is set to "none" (`ClientAuthenticationMethod.NONE`)
 
+or
+
+. When `ClientRegistration.clientSettings.requireProofKey` is `true` (in this case `ClientRegistration.authorizationGrantType` must be `authorization_code`)
+
 [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())`.

docs/modules/ROOT/pages/reactive/oauth2/client/core.adoc

@@ -39,6 +39,10 @@ public final class ClientRegistration {
 
 		}
 	}
+
+	public static final class ClientSettings {
+		private boolean requireProofKey; // <17>
+	}
 }
 ----
 <1> `registrationId`: The ID that uniquely identifies the `ClientRegistration`.
@@ -64,6 +68,7 @@ The name may be used in certain scenarios, such as when displaying the name of t
 <15> `(userInfoEndpoint)authenticationMethod`: The authentication method used when sending the access token to the UserInfo Endpoint.
 The supported values are *header*, *form* and *query*.
 <16> `userNameAttributeName`: The name of the attribute returned in the UserInfo Response that references the Name or Identifier of the end-user.
+<17> [[oauth2Client-client-registration-requireProofKey]]`requireProofKey`: If `true` or if `authorizationGrantType` is `none`, then PKCE will be enabled by default.
 
 A `ClientRegistration` can be initially configured using discovery of an OpenID Connect Provider's https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[Configuration endpoint] or an Authorization Server's https://tools.ietf.org/html/rfc8414#section-3[Metadata endpoint].
 

docs/modules/ROOT/pages/servlet/oauth2/client/authorization-grants.adoc

@@ -77,9 +77,14 @@ spring:
 Public Clients are supported by using https://tools.ietf.org/html/rfc7636[Proof Key for Code Exchange] (PKCE).
 If the client is running in an untrusted environment (such as a native application or web browser-based application) and is therefore incapable of maintaining the confidentiality of its credentials, PKCE is automatically used when the following conditions are true:
 
-. `client-secret` is omitted (or empty)
+. `client-secret` is omitted (or empty) and
 . `client-authentication-method` is set to `none` (`ClientAuthenticationMethod.NONE`)
 
+or
+
+. When `ClientRegistration.clientSettings.requireProofKey` is `true` (in this case `ClientRegistration.authorizationGrantType` must be `authorization_code`)
+
+
 [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 `DefaultOAuth2AuthorizationRequestResolver.setAuthorizationRequestCustomizer(OAuth2AuthorizationRequestCustomizers.withPkce())`.

docs/modules/ROOT/pages/servlet/oauth2/client/core.adoc

@@ -40,6 +40,10 @@ public final class ClientRegistration {
 
 		}
 	}
+
+	public static final class ClientSettings {
+		private boolean requireProofKey; // <17>
+	}
 }
 ----
 <1> `registrationId`: The ID that uniquely identifies the `ClientRegistration`.
@@ -65,6 +69,7 @@ This information is available only if the Spring Boot property `spring.security.
 <15> `(userInfoEndpoint)authenticationMethod`: The authentication method used when sending the access token to the UserInfo Endpoint.
 The supported values are *header*, *form*, and *query*.
 <16> `userNameAttributeName`: The name of the attribute returned in the UserInfo Response that references the Name or Identifier of the end-user.
+<17> [[oauth2Client-client-registration-requireProofKey]]`requireProofKey`: If `true` or if `authorizationGrantType` is `none`, then PKCE will be enabled by default.
 
 You can initially configure a `ClientRegistration` by using discovery of an OpenID Connect Provider's https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[Configuration endpoint] or an Authorization Server's https://tools.ietf.org/html/rfc8414#section-3[Metadata endpoint].
 

docs/modules/ROOT/pages/whats-new.adoc

@@ -10,3 +10,7 @@ Below are the highlights of the release, or you can view https://github.com/spri
 
 The `security.security.reached.filter.section` key name was corrected to `spring.security.reached.filter.section`.
 Note that this may affect reports that operate on this key name.
+
+== OAuth
+
+* https://github.com/spring-projects/spring-security/pull/16386[gh-16386] - Enable PKCE for confidential clients using `ClientRegistration.clientSettings.requireProofKey=true` for xref:servlet/oauth2/client/core.adoc#oauth2Client-client-registration-requireProofKey[servlet] and xref:reactive/oauth2/client/core.adoc#oauth2Client-client-registration-requireProofKey[reactive] applications