diff --git a/docs/documentation/securing_apps/topics/client-registration.adoc b/docs/guides/securing-apps/client-registration.adoc similarity index 89% rename from docs/documentation/securing_apps/topics/client-registration.adoc rename to docs/guides/securing-apps/client-registration.adoc index a291f7e83fa..93538a45618 100644 --- a/docs/documentation/securing_apps/topics/client-registration.adoc +++ b/docs/guides/securing-apps/client-registration.adoc @@ -1,12 +1,16 @@ -[[_client_registration]] -== Using the client registration service +<#import "/templates/guide.adoc" as tmpl> +<#import "/templates/links.adoc" as links> + +<@tmpl.guide +title="Client registration service" +priority=50 +summary="Using the client registration service"> In order for an application or service to utilize {project_name} it has to register a client in {project_name}. -An admin can do this through the admin console (or admin REST endpoints), but clients can also register themselves through the {project_name} client -registration service. +An admin can do this through the admin console (or admin REST endpoints), but clients can also register themselves through the {project_name} client registration service. The Client Registration Service provides built-in support for {project_name} Client Representations, OpenID Connect Client Meta Data and SAML Entity Descriptors. -The Client Registration Service endpoint is `{kc_realms_path}//clients-registrations/`. +The Client Registration Service endpoint is `/realms//clients-registrations/`. The built-in supported `providers` are: @@ -17,12 +21,12 @@ The built-in supported `providers` are: The following sections will describe how to use the different providers. -=== Authentication +== Authentication To invoke the Client Registration Services you usually need a token. The token can be a bearer token, an initial access token or a registration access token. There is an alternative to register new client without any token as well, but then you need to configure Client Registration Policies (see below). -==== Bearer token +=== Bearer token The bearer token can be issued on behalf of a user or a Service Account. The following permissions are required to invoke the endpoints (see link:{adminguide_link}[{adminguide_name}] for more details): @@ -33,7 +37,7 @@ The bearer token can be issued on behalf of a user or a Service Account. The fol If you are using a bearer token to create clients it's recommend to use a token from a Service Account with only the `create-client` role (see link:{adminguide_link}[{adminguide_name}] for more details). [[_initial_access_token]] -==== Initial Access Token +=== Initial Access Token The recommended approach to registering new clients is by using initial access tokens. An initial access token can only be used to create clients and has a configurable expiration as well as a configurable limit on how many clients can be created. @@ -55,8 +59,9 @@ For example: ---- Authorization: bearer eyJhbGciOiJSUz... ---- + [[_registration_access_token]] -==== Registration Access Token +=== Registration Access Token When you create a client through the Client Registration Service the response will include a registration access token. The registration access token provides access to retrieve the client configuration later, but also to update or delete the client. @@ -68,30 +73,30 @@ If a client was created outside of the Client Registration Service it won't have You can create one through the admin console. This can also be useful if you lose the token for a particular client. To create a new token find the client in the admin console and click on `Credentials`. Then click on `Generate registration access token`. -=== {project_name} Representations +== {project_name} Representations The `default` client registration provider can be used to create, retrieve, update and delete a client. It uses {project_name} Client Representation format which provides support for configuring clients exactly as they can be configured through the admin console, including for example configuring protocol mappers. -To create a client create a Client Representation (JSON) then perform an HTTP POST request to `{kc_realms_path}//clients-registrations/default`. +To create a client create a Client Representation (JSON) then perform an HTTP POST request to `/realms//clients-registrations/default`. It will return a Client Representation that also includes the registration access token. You should save the registration access token somewhere if you want to retrieve the config, update or delete the client later. -To retrieve the Client Representation perform an HTTP GET request to `{kc_realms_path}//clients-registrations/default/`. +To retrieve the Client Representation perform an HTTP GET request to `/realms//clients-registrations/default/`. It will also return a new registration access token. To update the Client Representation perform an HTTP PUT request with the updated Client Representation to: -`{kc_realms_path}//clients-registrations/default/`. +`/realms//clients-registrations/default/`. It will also return a new registration access token. To delete the Client Representation perform an HTTP DELETE request to: -`{kc_realms_path}//clients-registrations/default/` +`/realms//clients-registrations/default/` -=== {project_name} adapter configuration +== {project_name} adapter configuration The `installation` client registration provider can be used to retrieve the adapter configuration for a client. In addition to token authentication you can also authenticate with client credentials using HTTP basic authentication. @@ -102,29 +107,29 @@ To do this include the following header in the request: Authorization: basic BASE64(client-id + ':' + client-secret) ---- -To retrieve the Adapter Configuration then perform an HTTP GET request to `{kc_realms_path}//clients-registrations/install/`. +To retrieve the Adapter Configuration then perform an HTTP GET request to `/realms//clients-registrations/install/`. No authentication is required for public clients. This means that for the JavaScript adapter you can load the client configuration directly from {project_name} using the above URL. -=== OpenID Connect Dynamic Client Registration +== OpenID Connect Dynamic Client Registration {project_name} implements https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration], which extends https://datatracker.ietf.org/doc/html/rfc7591[OAuth 2.0 Dynamic Client Registration Protocol] and https://datatracker.ietf.org/doc/html/rfc7592[OAuth 2.0 Dynamic Client Registration Management Protocol]. -The endpoint to use these specifications to register clients in {project_name} is `{kc_realms_path}//clients-registrations/openid-connect[/]`. +The endpoint to use these specifications to register clients in {project_name} is `/realms//clients-registrations/openid-connect[/]`. -This endpoint can also be found in the OpenID Connect Discovery endpoint for the realm, `{kc_realms_path}//.well-known/openid-configuration`. +This endpoint can also be found in the OpenID Connect Discovery endpoint for the realm, `/realms//.well-known/openid-configuration`. -=== SAML Entity Descriptors +== SAML Entity Descriptors The SAML Entity Descriptor endpoint only supports using SAML v2 Entity Descriptors to create clients. It doesn't support retrieving, updating or deleting clients. For those operations the {project_name} representation endpoints should be used. When creating a client a {project_name} Client Representation is returned with details about the created client, including a registration access token. -To create a client perform an HTTP POST request with the SAML Entity Descriptor to `{kc_realms_path}//clients-registrations/saml2-entity-descriptor`. +To create a client perform an HTTP POST request with the SAML Entity Descriptor to `/realms//clients-registrations/saml2-entity-descriptor`. -=== Example using CURL +== Example using CURL The following example creates a client with the clientId `myclient` using CURL. You need to replace `eyJhbGciOiJSUz...` with a proper initial access token or bearer token. @@ -135,10 +140,10 @@ curl -X POST \ -d '{ "clientId": "myclient" }' \ -H "Content-Type:application/json" \ -H "Authorization: bearer eyJhbGciOiJSUz..." \ - http://localhost:8080{kc_realms_path}/master/clients-registrations/default + http://localhost:8080/realms/master/clients-registrations/default ---- -=== Example using Java Client Registration API +== Example using Java Client Registration API The Client Registration Java API makes it easy to use the Client Registration Service using Java. To use include the dependency `org.keycloak:keycloak-client-registration-api:>VERSION<` from Maven. @@ -154,7 +159,7 @@ ClientRepresentation client = new ClientRepresentation(); client.setClientId(CLIENT_ID); ClientRegistration reg = ClientRegistration.create() - .url("http://localhost:8080{kc_base_path}", "myrealm") + .url("http://localhost:8080", "myrealm") .build(); reg.auth(Auth.token(token)); @@ -165,7 +170,7 @@ String registrationAccessToken = client.getRegistrationAccessToken(); ---- [[_client_registration_policies]] -=== Client Registration Policies +== Client Registration Policies NOTE: The current plans are for the Client Registration Policies to be removed in favor of the Client Policies described in the link:{adminguide_link}#_client_policies[{adminguide_name}]. Client Policies are more flexible and support more use cases. @@ -213,3 +218,4 @@ realm roles or client roles of other clients. * Client Disabled Policy - Newly registered client will be disabled. This means that admin needs to manually approve and enable all newly registered clients. This policy is not used by default even for anonymous registration. + \ No newline at end of file