Polish gh-1320
This commit is contained in:
Joe Grandja
@@ -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.
|
||||
<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`.
|
||||
|
||||
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.
|
||||
[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.
|
||||
|
||||
Reference in New Issue
Block a user