Convert chapter client registration service from securing apps into guides
Closes #31332 Signed-off-by: rmartinc <rmartinc@redhat.com>
This commit is contained in:
rmartinc
Marek Posolda
parent
e1266c2678
commit
b2b27f8a4e
1 changed files with 32 additions and 26 deletions
|
|
@ -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}/<realm>/clients-registrations/<provider>`.
|
||||
The Client Registration Service endpoint is `/realms/<realm>/clients-registrations/<provider>`.
|
||||
|
||||
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}/<realm>/clients-registrations/default`.
|
||||
To create a client create a Client Representation (JSON) then perform an HTTP POST request to `/realms/<realm>/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}/<realm>/clients-registrations/default/<client id>`.
|
||||
To retrieve the Client Representation perform an HTTP GET request to `/realms/<realm>/clients-registrations/default/<client id>`.
|
||||
|
||||
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}/<realm>/clients-registrations/default/<client id>`.
|
||||
`/realms/<realm>/clients-registrations/default/<client id>`.
|
||||
|
||||
It will also return a new registration access token.
|
||||
|
||||
To delete the Client Representation perform an HTTP DELETE request to:
|
||||
`{kc_realms_path}/<realm>/clients-registrations/default/<client id>`
|
||||
`/realms/<realm>/clients-registrations/default/<client id>`
|
||||
|
||||
=== {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}/<realm>/clients-registrations/install/<client id>`.
|
||||
To retrieve the Adapter Configuration then perform an HTTP GET request to `/realms/<realm>/clients-registrations/install/<client id>`.
|
||||
|
||||
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}/<realm>/clients-registrations/openid-connect[/<client id>]`.
|
||||
The endpoint to use these specifications to register clients in {project_name} is `/realms/<realm>/clients-registrations/openid-connect[/<client id>]`.
|
||||
|
||||
This endpoint can also be found in the OpenID Connect Discovery endpoint for the realm, `{kc_realms_path}/<realm>/.well-known/openid-configuration`.
|
||||
This endpoint can also be found in the OpenID Connect Discovery endpoint for the realm, `/realms/<realm>/.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}/<realm>/clients-registrations/saml2-entity-descriptor`.
|
||||
To create a client perform an HTTP POST request with the SAML Entity Descriptor to `/realms/<realm>/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.
|
||||
|
||||
</@tmpl.guide>
|
||||
Loading…
Reference in a new issue