Skip to content

Commit 5da0cbe

Browse files
jgrandjajgrandja
committed
Document OAuth 2.0 Dynamic Client Registration support
Issue gh-17964
1 parent e6b4d46 commit 5da0cbe

File tree

3 files changed

+81
-12
lines changed

3 files changed

+81
-12
lines changed

‎docs/modules/ROOT/pages/servlet/oauth2/authorization-server/configuration-model.adoc‎

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,9 @@ The OAuth2 authorization server `SecurityFilterChain` `@Bean` is configured with
2222
[NOTE]
2323
The JWK Set endpoint is configured *only* if a `JWKSource<SecurityContext>` `@Bean` is registered.
2424

25+
[NOTE]
26+
The xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oauth2-client-registration-endpoint[OAuth2 Client Registration endpoint] is disabled by default.
27+
2528
The following example shows how to use `OAuth2AuthorizationServerConfiguration` to apply the minimal default configuration:
2629

2730
[source,java]
@@ -71,7 +74,7 @@ In addition to the default protocol endpoints, the OAuth2 authorization server `
7174
* xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oidc-user-info-endpoint[OpenID Connect 1.0 UserInfo endpoint]
7275

7376
[NOTE]
74-
The xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oidc-client-registration-endpoint[OpenID Connect 1.0 Client Registration endpoint] is disabled by default because many deployments do not require dynamic client registration.
77+
The xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oidc-client-registration-endpoint[OpenID Connect 1.0 Client Registration endpoint] is disabled by default.
7578

7679
[TIP]
7780
`OAuth2AuthorizationServerConfiguration.jwtDecoder(JWKSource<SecurityContext>)` is a convenience (`static`) utility method that can be used to register a `JwtDecoder` `@Bean`, which is *REQUIRED* for the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oidc-user-info-endpoint[OpenID Connect 1.0 UserInfo endpoint] and the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oidc-client-registration-endpoint[OpenID Connect 1.0 Client Registration endpoint].
@@ -117,12 +120,13 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h
117120
.tokenEndpoint(tokenEndpoint -> { }) <11>
118121
.tokenIntrospectionEndpoint(tokenIntrospectionEndpoint -> { }) <12>
119122
.tokenRevocationEndpoint(tokenRevocationEndpoint -> { }) <13>
120-
.authorizationServerMetadataEndpoint(authorizationServerMetadataEndpoint -> { }) <14>
123+
.clientRegistrationEndpoint(clientRegistrationEndpoint -> { }) <14>
124+
.authorizationServerMetadataEndpoint(authorizationServerMetadataEndpoint -> { }) <15>
121125
.oidc(oidc -> oidc
122-
.providerConfigurationEndpoint(providerConfigurationEndpoint -> { }) <15>
123-
.logoutEndpoint(logoutEndpoint -> { }) <16>
124-
.userInfoEndpoint(userInfoEndpoint -> { }) <17>
125-
.clientRegistrationEndpoint(clientRegistrationEndpoint -> { }) <18>
126+
.providerConfigurationEndpoint(providerConfigurationEndpoint -> { }) <16>
127+
.logoutEndpoint(logoutEndpoint -> { }) <17>
128+
.userInfoEndpoint(userInfoEndpoint -> { }) <18>
129+
.clientRegistrationEndpoint(clientRegistrationEndpoint -> { }) <19>
126130
)
127131
);
128132
@@ -142,11 +146,12 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h
142146
<11> `tokenEndpoint()`: The configurer for the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oauth2-token-endpoint[OAuth2 Token endpoint].
143147
<12> `tokenIntrospectionEndpoint()`: The configurer for the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oauth2-token-introspection-endpoint[OAuth2 Token Introspection endpoint].
144148
<13> `tokenRevocationEndpoint()`: The configurer for the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oauth2-token-revocation-endpoint[OAuth2 Token Revocation endpoint].
145-
<14> `authorizationServerMetadataEndpoint()`: The configurer for the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oauth2-authorization-server-metadata-endpoint[OAuth2 Authorization Server Metadata endpoint].
146-
<15> `providerConfigurationEndpoint()`: The configurer for the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oidc-provider-configuration-endpoint[OpenID Connect 1.0 Provider Configuration endpoint].
147-
<16> `logoutEndpoint()`: The configurer for the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oidc-logout-endpoint[OpenID Connect 1.0 Logout endpoint].
148-
<17> `userInfoEndpoint()`: The configurer for the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oidc-user-info-endpoint[OpenID Connect 1.0 UserInfo endpoint].
149-
<18> `clientRegistrationEndpoint()`: The configurer for the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oidc-client-registration-endpoint[OpenID Connect 1.0 Client Registration endpoint].
149+
<14> `clientRegistrationEndpoint()`: The configurer for the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oauth2-client-registration-endpoint[OAuth2 Client Registration endpoint].
150+
<15> `authorizationServerMetadataEndpoint()`: The configurer for the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oauth2-authorization-server-metadata-endpoint[OAuth2 Authorization Server Metadata endpoint].
151+
<16> `providerConfigurationEndpoint()`: The configurer for the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oidc-provider-configuration-endpoint[OpenID Connect 1.0 Provider Configuration endpoint].
152+
<17> `logoutEndpoint()`: The configurer for the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oidc-logout-endpoint[OpenID Connect 1.0 Logout endpoint].
153+
<18> `userInfoEndpoint()`: The configurer for the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oidc-user-info-endpoint[OpenID Connect 1.0 UserInfo endpoint].
154+
<19> `clientRegistrationEndpoint()`: The configurer for the xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oidc-client-registration-endpoint[OpenID Connect 1.0 Client Registration endpoint].
150155

151156
[[oauth2AuthorizationServer-configuring-authorization-server-settings]]
152157
== Configuring Authorization Server Settings
@@ -170,6 +175,7 @@ public final class AuthorizationServerSettings extends AbstractSettings {
170175
.tokenEndpoint("/oauth2/token")
171176
.tokenIntrospectionEndpoint("/oauth2/introspect")
172177
.tokenRevocationEndpoint("/oauth2/revoke")
178+
.clientRegistrationEndpoint("/oauth2/register")
173179
.jwkSetEndpoint("/oauth2/jwks")
174180
.oidcLogoutEndpoint("/connect/logout")
175181
.oidcUserInfoEndpoint("/userinfo")
@@ -202,6 +208,7 @@ public AuthorizationServerSettings authorizationServerSettings() {
202208
.tokenEndpoint("/oauth2/v1/token")
203209
.tokenIntrospectionEndpoint("/oauth2/v1/introspect")
204210
.tokenRevocationEndpoint("/oauth2/v1/revoke")
211+
.clientRegistrationEndpoint("/oauth2/v1/register")
205212
.jwkSetEndpoint("/oauth2/v1/jwks")
206213
.oidcLogoutEndpoint("/connect/v1/logout")
207214
.oidcUserInfoEndpoint("/connect/v1/userinfo")

‎docs/modules/ROOT/pages/servlet/oauth2/authorization-server/index.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@ Spring Security Authorization Server supports the following features:
8686
* xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oauth2-token-endpoint[OAuth2 Token Endpoint]
8787
* xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oauth2-token-introspection-endpoint[OAuth2 Token Introspection Endpoint]
8888
* xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oauth2-token-revocation-endpoint[OAuth2 Token Revocation Endpoint]
89+
* xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oauth2-client-registration-endpoint[OAuth2 Client Registration Endpoint]
8990
* xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oauth2-authorization-server-metadata-endpoint[OAuth2 Authorization Server Metadata Endpoint]
9091
* xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-jwk-set-endpoint[JWK Set Endpoint]
9192
* xref:servlet/oauth2/authorization-server/protocol-endpoints.adoc#oauth2AuthorizationServer-oidc-provider-configuration-endpoint[OpenID Connect 1.0 Provider Configuration Endpoint]
@@ -103,6 +104,7 @@ Spring Security Authorization Server supports the following features:
103104
** https://tools.ietf.org/html/rfc8628#section-3.3[Device Verification Endpoint]
104105
* OAuth 2.0 Token Introspection (https://tools.ietf.org/html/rfc7662[RFC 7662])
105106
* OAuth 2.0 Token Revocation (https://tools.ietf.org/html/rfc7009[RFC 7009])
107+
* OAuth 2.0 Dynamic Client Registration Protocol (https://datatracker.ietf.org/doc/html/rfc7591[RFC 7591])
106108
* OAuth 2.0 Authorization Server Metadata (https://tools.ietf.org/html/rfc8414[RFC 8414])
107109
* JSON Web Key (JWK) (https://tools.ietf.org/html/rfc7517[RFC 7517])
108110
* OpenID Connect Discovery 1.0 (https://openid.net/specs/openid-connect-discovery-1_0.html[spec])

‎docs/modules/ROOT/pages/servlet/oauth2/authorization-server/protocol-endpoints.adoc‎

Lines changed: 61 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -664,6 +664,66 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h
664664
* `*AuthenticationSuccessHandler*` -- An internal implementation that handles an "`authenticated`" `OAuth2TokenRevocationAuthenticationToken` and returns the OAuth2 revocation response.
665665
* `*AuthenticationFailureHandler*` -- An `OAuth2ErrorAuthenticationFailureHandler`.
666666

667+
[[oauth2AuthorizationServer-oauth2-client-registration-endpoint]]
668+
== OAuth2 Client Registration Endpoint
669+
670+
`OAuth2ClientRegistrationEndpointConfigurer` provides the ability to customize the https://datatracker.ietf.org/doc/html/rfc7591#section-3[OAuth2 Client Registration endpoint].
671+
It defines extension points that let you customize the pre-processing, main processing, and post-processing logic for https://datatracker.ietf.org/doc/html/rfc7591#section-3.1[Client Registration requests].
672+
673+
`OAuth2ClientRegistrationEndpointConfigurer` provides the following configuration options:
674+
675+
[source,java]
676+
----
677+
@Bean
678+
public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
679+
http
680+
.oauth2AuthorizationServer((authorizationServer) ->
681+
authorizationServer
682+
.clientRegistrationEndpoint(clientRegistrationEndpoint ->
683+
clientRegistrationEndpoint
684+
.clientRegistrationRequestConverter(clientRegistrationRequestConverter) <1>
685+
.clientRegistrationRequestConverters(clientRegistrationRequestConvertersConsumer) <2>
686+
.authenticationProvider(authenticationProvider) <3>
687+
.authenticationProviders(authenticationProvidersConsumer) <4>
688+
.clientRegistrationResponseHandler(clientRegistrationResponseHandler) <5>
689+
.errorResponseHandler(errorResponseHandler) <6>
690+
)
691+
);
692+
693+
return http.build();
694+
}
695+
----
696+
<1> `clientRegistrationRequestConverter()`: Adds an `AuthenticationConverter` (_pre-processor_) used when attempting to extract a https://datatracker.ietf.org/doc/html/rfc7591#section-3.1[Client Registration request] from `HttpServletRequest` to an instance of `OAuth2ClientRegistrationAuthenticationToken`.
697+
<2> `clientRegistrationRequestConverters()`: Sets the `Consumer` providing access to the `List` of default and (optionally) added ``AuthenticationConverter``'s allowing the ability to add, remove, or customize a specific `AuthenticationConverter`.
698+
<3> `authenticationProvider()`: Adds an `AuthenticationProvider` (_main processor_) used for authenticating the `OAuth2ClientRegistrationAuthenticationToken`.
699+
<4> `authenticationProviders()`: Sets the `Consumer` providing access to the `List` of default and (optionally) added ``AuthenticationProvider``'s allowing the ability to add, remove, or customize a specific `AuthenticationProvider`.
700+
<5> `clientRegistrationResponseHandler()`: The `AuthenticationSuccessHandler` (_post-processor_) used for handling an "`authenticated`" `OAuth2ClientRegistrationAuthenticationToken` and returning the https://datatracker.ietf.org/doc/html/rfc7591#section-3.2.1[Client Registration response].
701+
<6> `errorResponseHandler()`: The `AuthenticationFailureHandler` (_post-processor_) used for handling an `OAuth2AuthenticationException` and returning the https://datatracker.ietf.org/doc/html/rfc7591#section-3.2.2[Client Registration Error response].
702+
703+
[NOTE]
704+
The OAuth2 Client Registration endpoint is disabled by default.
705+
706+
`OAuth2ClientRegistrationEndpointConfigurer` configures the `OAuth2ClientRegistrationEndpointFilter` and registers it with the OAuth2 authorization server `SecurityFilterChain` `@Bean`.
707+
`OAuth2ClientRegistrationEndpointFilter` is the `Filter` that processes https://datatracker.ietf.org/doc/html/rfc7591#section-3.1[Client Registration requests] and returns the https://datatracker.ietf.org/doc/html/rfc7591#section-3.2.1[OAuth2ClientRegistration response].
708+
709+
`OAuth2ClientRegistrationEndpointFilter` is configured with the following defaults:
710+
711+
* `*AuthenticationConverter*` -- An `OAuth2ClientRegistrationAuthenticationConverter`.
712+
* `*AuthenticationManager*` -- An `AuthenticationManager` composed of `OAuth2ClientRegistrationAuthenticationProvider`.
713+
* `*AuthenticationSuccessHandler*` -- An internal implementation that handles an "`authenticated`" `OAuth2ClientRegistrationAuthenticationToken` and returns the `OAuth2ClientRegistration` response.
714+
* `*AuthenticationFailureHandler*` -- An internal implementation that uses the `OAuth2Error` associated with the `OAuth2AuthenticationException` and returns the `OAuth2Error` response.
715+
716+
The OAuth2 Client Registration endpoint is an https://datatracker.ietf.org/doc/html/rfc7591#section-3[OAuth2 protected resource], which *REQUIRES* an access token to be sent as a bearer token in the Client Registration request.
717+
718+
[NOTE]
719+
OAuth2 resource server support is autoconfigured, however, a `JwtDecoder` `@Bean` is *REQUIRED* for the OAuth2 Client Registration endpoint.
720+
721+
[IMPORTANT]
722+
The access token in a Client Registration request *REQUIRES* the OAuth2 scope `client.create`.
723+
724+
[TIP]
725+
To allow open client registration (no access token in request), configure `OAuth2ClientRegistrationAuthenticationProvider.setOpenRegistrationAllowed(true)`.
726+
667727
[[oauth2AuthorizationServer-oauth2-authorization-server-metadata-endpoint]]
668728
== OAuth2 Authorization Server Metadata Endpoint
669729

@@ -950,7 +1010,7 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h
9501010
<6> `errorResponseHandler()`: The `AuthenticationFailureHandler` (_post-processor_) used for handling an `OAuth2AuthenticationException` and returning the https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationError[Client Registration Error response] or https://openid.net/specs/openid-connect-registration-1_0.html#ReadError[Client Read Error response].
9511011

9521012
[NOTE]
953-
The OpenID Connect 1.0 Client Registration endpoint is disabled by default because many deployments do not require dynamic client registration.
1013+
The OpenID Connect 1.0 Client Registration endpoint is disabled by default.
9541014

9551015
`OidcClientRegistrationEndpointConfigurer` configures the `OidcClientRegistrationEndpointFilter` and registers it with the OAuth2 authorization server `SecurityFilterChain` `@Bean`.
9561016
`OidcClientRegistrationEndpointFilter` is the `Filter` that processes https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationRequest[Client Registration requests] and returns the https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationResponse[OidcClientRegistration response].

0 commit comments

Comments
 (0)