Skip to content

Commit e51ca79

Browse files
jgrandjajgrandja
committed
Document Jwt Client Authentication support
Closes gh-9578
1 parent 85fb9c0 commit e51ca79

File tree

4 files changed

+129
-5
lines changed

4 files changed

+129
-5
lines changed

‎config/src/main/resources/org/springframework/security/config/spring-security-5.5.rnc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -526,8 +526,8 @@ client-registration.attlist &=
526526
## The client secret.
527527
attribute client-secret {xsd:token}?
528528
client-registration.attlist &=
529-
## The method used to authenticate the client with the provider. The supported values are client_secret_basic, client_secret_post and none (public clients).
530-
attribute client-authentication-method {"client_secret_basic" | "basic" | "client_secret_post" | "post" | "none"}?
529+
## The method used to authenticate the client with the provider. The supported values are client_secret_basic, client_secret_post, private_key_jwt, client_secret_jwt and none (public clients).
530+
attribute client-authentication-method {"client_secret_basic" | "basic" | "client_secret_post" | "post" | "private_key_jwt" | "client_secret_jwt" | "none"}?
531531
client-registration.attlist &=
532532
## The OAuth 2.0 Authorization Framework defines four Authorization Grant types. The supported values are authorization_code, client_credentials, password, implicit, as well as, extension grant type urn:ietf:params:oauth:grant-type:jwt-bearer.
533533
attribute authorization-grant-type {"authorization_code" | "client_credentials" | "password" | "implicit" | "urn:ietf:params:oauth:grant-type:jwt-bearer"}?

‎config/src/main/resources/org/springframework/security/config/spring-security-5.5.xsd

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1657,7 +1657,8 @@
16571657
<xs:attribute name="client-authentication-method">
16581658
<xs:annotation>
16591659
<xs:documentation>The method used to authenticate the client with the provider. The supported values are
1660-
client_secret_basic, client_secret_post and none (public clients).
1660+
client_secret_basic, client_secret_post, private_key_jwt, client_secret_jwt and none
1661+
(public clients).
16611662
</xs:documentation>
16621663
</xs:annotation>
16631664
<xs:simpleType>
@@ -1666,6 +1667,8 @@
16661667
<xs:enumeration value="basic"/>
16671668
<xs:enumeration value="client_secret_post"/>
16681669
<xs:enumeration value="post"/>
1670+
<xs:enumeration value="private_key_jwt"/>
1671+
<xs:enumeration value="client_secret_jwt"/>
16691672
<xs:enumeration value="none"/>
16701673
</xs:restriction>
16711674
</xs:simpleType>

‎docs/manual/src/docs/asciidoc/_includes/servlet/appendix/namespace.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1061,7 +1061,7 @@ The client secret.
10611061
[[nsa-client-registration-client-authentication-method]]
10621062
* **client-authentication-method**
10631063
The method used to authenticate the Client with the Provider.
1064-
The supported values are *client_secret_basic*, *client_secret_post* and *none* https://tools.ietf.org/html/rfc6749#section-2.1[(public clients)].
1064+
The supported values are *client_secret_basic*, *client_secret_post*, *private_key_jwt*, *client_secret_jwt* and *none* https://tools.ietf.org/html/rfc6749#section-2.1[(public clients)].
10651065

10661066

10671067
[[nsa-client-registration-authorization-grant-type]]

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

Lines changed: 122 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@ At a high-level, the core features available are:
1212
* https://tools.ietf.org/html/rfc6749#section-1.3.3[Resource Owner Password Credentials]
1313
* https://datatracker.ietf.org/doc/html/rfc7523#section-2.1[JWT Bearer]
1414

15+
.Client Authentication support
16+
* https://datatracker.ietf.org/doc/html/rfc7523#section-2.2[JWT Bearer]
17+
1518
.HTTP Client support
1619
* <<oauth2Client-webclient-servlet, `WebClient` integration for Servlet Environments>> (for requesting protected resources)
1720

@@ -155,6 +158,8 @@ The following sections will go into more detail on the core components used by O
155158
** <<oauth2Client-client-creds-grant, Client Credentials>>
156159
** <<oauth2Client-password-grant, Resource Owner Password Credentials>>
157160
** <<oauth2Client-jwt-bearer-grant, JWT Bearer>>
161+
* <<oauth2Client-client-auth-support>>
162+
** <<oauth2Client-jwt-bearer-auth, JWT Bearer>>
158163
* <<oauth2Client-additional-features>>
159164
** <<oauth2Client-registered-authorized-client, Resolving an Authorized Client>>
160165
* <<oauth2Client-webclient-servlet>>
@@ -207,7 +212,7 @@ public final class ClientRegistration {
207212
<2> `clientId`: The client identifier.
208213
<3> `clientSecret`: The client secret.
209214
<4> `clientAuthenticationMethod`: The method used to authenticate the Client with the Provider.
210-
The supported values are *client_secret_basic*, *client_secret_post* and *none* https://tools.ietf.org/html/rfc6749#section-2.1[(public clients)].
215+
The supported values are *client_secret_basic*, *client_secret_post*, *private_key_jwt*, *client_secret_jwt* and *none* https://tools.ietf.org/html/rfc6749#section-2.1[(public clients)].
211216
<5> `authorizationGrantType`: The OAuth 2.0 Authorization Framework defines four https://tools.ietf.org/html/rfc6749#section-1.3[Authorization Grant] types.
212217
The supported values are `authorization_code`, `client_credentials`, `password`, as well as, extension grant type `urn:ietf:params:oauth:grant-type:jwt-bearer`.
213218
<6> `redirectUri`: The client's registered redirect URI that the _Authorization Server_ redirects the end-user's user-agent
@@ -1851,6 +1856,122 @@ class OAuth2ResourceServerController {
18511856
====
18521857

18531858

1859+
[[oauth2Client-client-auth-support]]
1860+
=== Client Authentication Support
1861+
1862+
1863+
[[oauth2Client-jwt-bearer-auth]]
1864+
==== JWT Bearer
1865+
1866+
[NOTE]
1867+
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.
1868+
1869+
The default implementation for JWT Bearer Client Authentication is `NimbusJwtClientAuthenticationParametersConverter`,
1870+
which is a `Converter` that customizes the Token Request parameters by adding
1871+
a signed JSON Web Token (JWS) in the `client_assertion` parameter.
1872+
1873+
The `java.security.PrivateKey` or `javax.crypto.SecretKey` used for signing the JWS
1874+
is supplied by the `com.nimbusds.jose.jwk.JWK` resolver associated with `NimbusJwtClientAuthenticationParametersConverter`.
1875+
1876+
1877+
===== Authenticate using `private_key_jwt`
1878+
1879+
Given the following Spring Boot 2.x properties for an OAuth 2.0 Client registration:
1880+
1881+
[source,yaml]
1882+
----
1883+
spring:
1884+
security:
1885+
oauth2:
1886+
client:
1887+
registration:
1888+
okta:
1889+
client-id: okta-client-id
1890+
client-authentication-method: private_key_jwt
1891+
authorization-grant-type: authorization_code
1892+
...
1893+
----
1894+
1895+
The following example shows how to configure `DefaultAuthorizationCodeTokenResponseClient`:
1896+
1897+
====
1898+
.Java
1899+
[source,java,role="primary"]
1900+
----
1901+
Function<ClientRegistration, JWK> jwkResolver = (clientRegistration) -> {
1902+
if (clientRegistration.getClientAuthenticationMethod().equals(ClientAuthenticationMethod.PRIVATE_KEY_JWT)) {
1903+
// Assuming RSA key type
1904+
RSAPublicKey publicKey = ...
1905+
RSAPrivateKey privateKey = ...
1906+
return new RSAKey.Builder(publicKey)
1907+
.privateKey(privateKey)
1908+
.keyID(UUID.randomUUID().toString())
1909+
.build();
1910+
}
1911+
return null;
1912+
};
1913+
1914+
OAuth2AuthorizationCodeGrantRequestEntityConverter requestEntityConverter =
1915+
new OAuth2AuthorizationCodeGrantRequestEntityConverter();
1916+
requestEntityConverter.addParametersConverter(
1917+
new NimbusJwtClientAuthenticationParametersConverter<>(jwkResolver));
1918+
1919+
DefaultAuthorizationCodeTokenResponseClient tokenResponseClient =
1920+
new DefaultAuthorizationCodeTokenResponseClient();
1921+
tokenResponseClient.setRequestEntityConverter(requestEntityConverter);
1922+
----
1923+
====
1924+
1925+
1926+
===== Authenticate using `client_secret_jwt`
1927+
1928+
Given the following Spring Boot 2.x properties for an OAuth 2.0 Client registration:
1929+
1930+
[source,yaml]
1931+
----
1932+
spring:
1933+
security:
1934+
oauth2:
1935+
client:
1936+
registration:
1937+
okta:
1938+
client-id: okta-client-id
1939+
client-secret: okta-client-secret
1940+
client-authentication-method: client_secret_jwt
1941+
authorization-grant-type: client_credentials
1942+
...
1943+
----
1944+
1945+
The following example shows how to configure `DefaultClientCredentialsTokenResponseClient`:
1946+
1947+
====
1948+
.Java
1949+
[source,java,role="primary"]
1950+
----
1951+
Function<ClientRegistration, JWK> jwkResolver = (clientRegistration) -> {
1952+
if (clientRegistration.getClientAuthenticationMethod().equals(ClientAuthenticationMethod.CLIENT_SECRET_JWT)) {
1953+
SecretKeySpec secretKey = new SecretKeySpec(
1954+
clientRegistration.getClientSecret().getBytes(StandardCharsets.UTF_8),
1955+
"HmacSHA256");
1956+
return new OctetSequenceKey.Builder(secretKey)
1957+
.keyID(UUID.randomUUID().toString())
1958+
.build();
1959+
}
1960+
return null;
1961+
};
1962+
1963+
OAuth2ClientCredentialsGrantRequestEntityConverter requestEntityConverter =
1964+
new OAuth2ClientCredentialsGrantRequestEntityConverter();
1965+
requestEntityConverter.addParametersConverter(
1966+
new NimbusJwtClientAuthenticationParametersConverter<>(jwkResolver));
1967+
1968+
DefaultClientCredentialsTokenResponseClient tokenResponseClient =
1969+
new DefaultClientCredentialsTokenResponseClient();
1970+
tokenResponseClient.setRequestEntityConverter(requestEntityConverter);
1971+
----
1972+
====
1973+
1974+
18541975
[[oauth2Client-additional-features]]
18551976
=== Additional Features
18561977

0 commit comments

Comments
 (0)