|
@@ -3,60 +3,50 @@
|
|
|
:index-link: ../how-to.html
|
|
|
:docs-dir: ..
|
|
|
|
|
|
-This guide shows how to configure OpenID Connect Dynamic Client Registration 1.0 in Spring Authorization Server and walks through an example of how to register a client.
|
|
|
-Spring Authorization Server implements https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration 1.0]
|
|
|
-specification, gaining the ability to dynamically register and retrieve OpenID clients.
|
|
|
+This guide shows how to configure OpenID Connect Dynamic Client Registration in Spring Authorization Server and walks through an example of how to register a client.
|
|
|
+Spring Authorization Server implements the https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration 1.0] specification, providing the capability to dynamically register and retrieve OpenID Connect clients.
|
|
|
|
|
|
-- xref:guides/how-to-dynamic-client-registration.adoc#enable[Enable Dynamic Client Registration]
|
|
|
-- xref:guides/how-to-dynamic-client-registration.adoc#configure-initial-client[Configure initial client]
|
|
|
-- xref:guides/how-to-dynamic-client-registration.adoc#obtain-initial-access-token[Obtain initial access token]
|
|
|
-- xref:guides/how-to-dynamic-client-registration.adoc#register-client[Register a client]
|
|
|
+* xref:guides/how-to-dynamic-client-registration.adoc#enable-dynamic-client-registration[Enable Dynamic Client Registration]
|
|
|
+* xref:guides/how-to-dynamic-client-registration.adoc#configure-client-registrar[Configure client registrar]
|
|
|
+* xref:guides/how-to-dynamic-client-registration.adoc#obtain-initial-access-token[Obtain initial access token]
|
|
|
+* xref:guides/how-to-dynamic-client-registration.adoc#register-client[Register a client]
|
|
|
|
|
|
-[[enable]]
|
|
|
+[[enable-dynamic-client-registration]]
|
|
|
== Enable Dynamic Client Registration
|
|
|
|
|
|
By default, dynamic client registration functionality is disabled in Spring Authorization Server.
|
|
|
To enable, add the following configuration:
|
|
|
|
|
|
-[[sample.dcrAuthServerConfig]]
|
|
|
+[[sample.SecurityConfig]]
|
|
|
[source,java]
|
|
|
----
|
|
|
-include::{examples-dir}/main/java/sample/dcr/DcrConfiguration.java[]
|
|
|
+include::{examples-dir}/main/java/sample/registration/SecurityConfig.java[]
|
|
|
----
|
|
|
|
|
|
-<1> Add a `SecurityFilterChain` `@Bean` that registers an `OAuth2AuthorizationServerConfigurer`
|
|
|
-<2> In the configurer, apply OIDC client registration endpoint customizer with default values.
|
|
|
-This enables dynamic client registration functionality.
|
|
|
+<1> Enable the xref:protocol-endpoints.adoc#oidc-client-registration-endpoint[OpenID Connect 1.0 Client Registration Endpoint] with the default configuration.
|
|
|
|
|
|
-Please refer to xref:protocol-endpoints.adoc#oidc-client-registration-endpoint[Client Registration Endpoint docs] for in-depth configuration details.
|
|
|
+[[configure-client-registrar]]
|
|
|
+== Configure client registrar
|
|
|
|
|
|
-[[configure-initial-client]]
|
|
|
-== Configure initial client
|
|
|
+An existing client is used to register new clients with the authorization server.
|
|
|
+The client must be configured with scopes `client.create` and optionally `client.read` for registering clients and retrieving clients, respectively.
|
|
|
+The following listing shows an example client:
|
|
|
|
|
|
-An initial client is required in order to register new clients in the authorization server.
|
|
|
-The client must be configured with scopes `client.create` and optionally `client.read` for creating clients and reading clients, respectively.
|
|
|
-A programmatic example of such a client is below.
|
|
|
-
|
|
|
-[[sample.dcrRegisteredClientConfig]]
|
|
|
+[[sample.ClientConfig]]
|
|
|
[source,java]
|
|
|
----
|
|
|
-include::{examples-dir}/main/java/sample/dcr/RegisteredClientConfiguration.java[]
|
|
|
+include::{examples-dir}/main/java/sample/registration/ClientConfig.java[]
|
|
|
----
|
|
|
|
|
|
-<1> A `RegisteredClientRepository` `@Bean` is configured with a set of clients.
|
|
|
-<2> An initial client with client id `dcr-client` is configured.
|
|
|
-<3> `client_credentials` grant type is set to fetch access tokens directly.
|
|
|
-<4> `client.create` scope is configured for the client to ensure they are able to create clients.
|
|
|
-<5> `client.read` scope is configured for the client to ensure they are able to fetch and read clients.
|
|
|
-<6> The initial client is saved into the data store.
|
|
|
-
|
|
|
-After configuring the above, run the authorization server in your preferred environment.
|
|
|
+<1> `client_credentials` grant type is configured to obtain access tokens directly.
|
|
|
+<2> `client.create` scope is configured to allow the client to register a new client.
|
|
|
+<3> `client.read` scope is configured to allow the client to retrieve a registered client.
|
|
|
|
|
|
[[obtain-initial-access-token]]
|
|
|
== Obtain initial access token
|
|
|
|
|
|
-An initial access token is required to be able to create client registration requests.
|
|
|
-The token request must contain a request for scope `client.create` only.
|
|
|
+An "initial" access token is required for the client registration request.
|
|
|
+The access token request *MUST* contain the `scope` parameter value `client.create` only.
|
|
|
|
|
|
[source,httprequest]
|
|
|
----
|
|
@@ -69,18 +59,18 @@ grant_type=client_credentials&scope=client.create
|
|
|
|
|
|
[WARNING]
|
|
|
====
|
|
|
-If you provide more than one scope in the request, you will not be able to register a client.
|
|
|
-The client creation request requires an access token with a single scope of `client.create`
|
|
|
+The client registration request requires an access token with a single scope of `client.create`.
|
|
|
+If the access token contains additional scope, the client registration request will be denied.
|
|
|
====
|
|
|
|
|
|
[TIP]
|
|
|
====
|
|
|
-To obtain encoded credentials for the above request, `base64` encode the client credentials in the format of
|
|
|
-`<clientId>:<clientSecret>`. Below is an encoding operation for the example in this guide.
|
|
|
+To obtain encoded credentials for the above request, `base64` encode the client credentials in the format of `<clientId>:<clientSecret>`.
|
|
|
+Below is an encoding operation for the example in this guide.
|
|
|
|
|
|
[source,console]
|
|
|
----
|
|
|
-echo -n "initial-app:secret" | base64
|
|
|
+echo -n "registrar-client:secret" | base64
|
|
|
----
|
|
|
====
|
|
|
|
|
@@ -90,30 +80,26 @@ echo -n "initial-app:secret" | base64
|
|
|
With an access token obtained from the previous step, a client can now be dynamically registered.
|
|
|
|
|
|
[NOTE]
|
|
|
-The access token can only be used once. After a single registration request, the access token is invalidated.
|
|
|
+The "initial" access token can only be used once.
|
|
|
+After the client is registered, the access token is invalidated.
|
|
|
|
|
|
-[[sample.dcrClientRegistration]]
|
|
|
+[[sample.ClientRegistrar]]
|
|
|
[source,java]
|
|
|
----
|
|
|
-include::{examples-dir}/main/java/sample/dcr/DcrClient.java[]
|
|
|
+include::{examples-dir}/main/java/sample/registration/ClientRegistrar.java[]
|
|
|
----
|
|
|
|
|
|
-<1> A minimal client registration request object.
|
|
|
-You may add additional fields as per https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationRequest[OpenID Connect Dynamic Client Registration 1.0 spec - Client Registration Request].
|
|
|
-<2> A minimal client registration response object.
|
|
|
-You may add additional response fields as per https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationResponse[OpenID Connect Dynamic Client Registration 1.0 spec - Client Registration Response].
|
|
|
-<3> A sample client registration request object which will be used to register a sample client.
|
|
|
-<4> Example dynamic client registration procedure, demonstrating dynamic registration and client retrieval.
|
|
|
-<5> Register a client using sample request from step 2, using initial access token from previous step.
|
|
|
-Skip to step 10 for implementation.
|
|
|
-<6> After registration, assert on the fields that should be populated in the response upon successful registration.
|
|
|
-<7> Extract `registration_access_token` and `registration_client_uri` fields, for use in retrieval of the newly registered client.
|
|
|
-<8> Retrieve client. Skip to step 11 for implementation.
|
|
|
-<9> After client retrieval, assert on the fields that should be populated in the response.
|
|
|
-<10> Sample client registration procedure using Spring WebFlux's `WebClient`.
|
|
|
-Note that the `WebClient` must have `baseUrl` of the authorization server configured.
|
|
|
-<11> Sample client retrieval procedure using Spring WebFlux's `WebClient`.
|
|
|
-Note that the `WebClient` must have `baseUrl` of the authorization server configured.
|
|
|
-
|
|
|
-The retrieve client response should contain the same information about the client as seen when the client was first
|
|
|
-registered, except for `registration_access_token` field.
|
|
|
+<1> A minimal representation of a client registration request. You may add additional client metadata parameters as per https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationRequest[Client Registration Request].
|
|
|
+<2> A minimal representation of a client registration response. You may add additional client metadata parameters as per https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationResponse[Client Registration Response].
|
|
|
+<3> Example demonstrating client registration and client retrieval.
|
|
|
+<4> A sample client registration request object.
|
|
|
+<5> Register the client using the "initial" access token and client registration request object.
|
|
|
+<6> After successful registration, assert on the client metadata parameters that should be populated in the response.
|
|
|
+<7> Extract `registration_access_token` and `registration_client_uri` response parameters, for use in retrieval of the newly registered client.
|
|
|
+<8> Retrieve the client using the `registration_access_token` and `registration_client_uri`.
|
|
|
+<9> After client retrieval, assert on the client metadata parameters that should be populated in the response.
|
|
|
+<10> Sample https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationRequest[Client Registration Request] using `WebClient`.
|
|
|
+<11> Sample https://openid.net/specs/openid-connect-registration-1_0.html#ReadRequest[Client Read Request] using `WebClient`.
|
|
|
+
|
|
|
+[NOTE]
|
|
|
+The https://openid.net/specs/openid-connect-registration-1_0.html#ReadResponse[Client Read Response] should contain the same client metadata parameters as the https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationResponse[Client Registration Response], except the `registration_access_token` parameter.
|