222 lines
13 KiB
Text
222 lines
13 KiB
Text
<#import "/templates/guide.adoc" as tmpl>
|
|
<#import "/templates/links.adoc" as links>
|
|
|
|
<@tmpl.guide
|
|
title="Client registration service"
|
|
priority=100
|
|
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.
|
|
|
|
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 `/realms/<realm>/clients-registrations/<provider>`.
|
|
|
|
The built-in supported `providers` are:
|
|
|
|
* default - {project_name} Client Representation (JSON)
|
|
* install - {project_name} Adapter Configuration (JSON)
|
|
* openid-connect - OpenID Connect Client Metadata Description (JSON)
|
|
* saml2-entity-descriptor - SAML Entity Descriptor (XML)
|
|
|
|
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
|
|
|
|
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):
|
|
|
|
* create-client or manage-client - To create clients
|
|
* view-client or manage-client - To view clients
|
|
* manage-client - To update or delete client
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
An initial access token can be created through the admin console.
|
|
To create a new initial access token first select the realm in the admin console, then click on `Client` in the menu on the left, followed by
|
|
`Initial access token` in the tabs displayed in the page.
|
|
|
|
You will now be able to see any existing initial access tokens. If you have access you can delete tokens that are no longer required. You can only retrieve the
|
|
value of the token when you are creating it. To create a new token click on `Create`. You can now optionally add how long the token should be valid, also how
|
|
many clients can be created using the token. After you click on `Save` the token value is displayed.
|
|
|
|
It is important that you copy/paste this token now as you won't be able to retrieve it later. If you forget to copy/paste it, then delete the token and create another one.
|
|
|
|
The token value is used as a standard bearer token when invoking the Client Registration Services, by adding it to the Authorization header in the request.
|
|
For example:
|
|
|
|
[source]
|
|
----
|
|
Authorization: bearer eyJhbGciOiJSUz...
|
|
----
|
|
|
|
[[_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.
|
|
The registration access token is included with the request in the same way as a bearer token or initial access token.
|
|
|
|
By default, registration access token rotation is enabled. This means a registration access token is only valid once. When the token is used, the response will include a new token. Note that registration access token rotation can be disabled by using link:{adminguide_link}#_client_policies[Client Policies].
|
|
|
|
If a client was created outside of the Client Registration Service it won't have a registration access token associated with it.
|
|
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
|
|
|
|
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 `/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 `/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:
|
|
`/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:
|
|
`/realms/<realm>/clients-registrations/default/<client id>`
|
|
|
|
== {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.
|
|
To do this include the following header in the request:
|
|
|
|
[source]
|
|
----
|
|
Authorization: basic BASE64(client-id + ':' + client-secret)
|
|
----
|
|
|
|
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
|
|
|
|
{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 `/realms/<realm>/clients-registrations/openid-connect[/<client id>]`.
|
|
|
|
This endpoint can also be found in the OpenID Connect Discovery endpoint for the realm, `/realms/<realm>/.well-known/openid-configuration`.
|
|
|
|
== 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 `/realms/<realm>/clients-registrations/saml2-entity-descriptor`.
|
|
|
|
== 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.
|
|
|
|
[source,bash,subs="attributes+"]
|
|
----
|
|
curl -X POST \
|
|
-d '{ "clientId": "myclient" }' \
|
|
-H "Content-Type:application/json" \
|
|
-H "Authorization: bearer eyJhbGciOiJSUz..." \
|
|
http://localhost:8080/realms/master/clients-registrations/default
|
|
----
|
|
|
|
== 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.
|
|
|
|
For full instructions on using the Client Registration refer to the JavaDocs.
|
|
Below is an example of creating a client. You need to replace `eyJhbGciOiJSUz...` with a proper initial access token or bearer token.
|
|
|
|
[source,java,subs="attributes+"]
|
|
----
|
|
String token = "eyJhbGciOiJSUz...";
|
|
|
|
ClientRepresentation client = new ClientRepresentation();
|
|
client.setClientId(CLIENT_ID);
|
|
|
|
ClientRegistration reg = ClientRegistration.create()
|
|
.url("http://localhost:8080", "myrealm")
|
|
.build();
|
|
|
|
reg.auth(Auth.token(token));
|
|
|
|
client = reg.create(client);
|
|
|
|
String registrationAccessToken = client.getRegistrationAccessToken();
|
|
----
|
|
|
|
[[_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.
|
|
|
|
{project_name} currently supports two ways how new clients can be registered through Client Registration Service.
|
|
|
|
* Authenticated requests - Request to register new client must contain either `Initial Access Token` or `Bearer Token` as mentioned above.
|
|
|
|
* Anonymous requests - Request to register new client doesn't need to contain any token at all
|
|
|
|
Anonymous client registration requests are very interesting and powerful feature, however you usually don't want that anyone is able to register new
|
|
client without any limitations. Hence we have `Client Registration Policy SPI`, which provide a way to limit who can register new clients and under which conditions.
|
|
|
|
In {project_name} admin console, you can click to `Client Registration` tab and then `Client Registration Policies` sub-tab. Here you will see what policies
|
|
are configured by default for anonymous requests and what policies are configured for authenticated requests.
|
|
|
|
NOTE: The anonymous requests (requests without any token) are allowed just for creating (registration) of new clients. So when you register
|
|
new client through anonymous request, the response will contain Registration Access Token, which must be used for Read, Update or Delete request of particular client.
|
|
However using this Registration Access Token from anonymous registration will be then subject to Anonymous Policy too! This means that for example request for update
|
|
client also needs to come from Trusted Host if you have `Trusted Hosts` policy. Also for example it won't be allowed to disable `Consent Required` when updating client and
|
|
when `Consent Required` policy is present etc.
|
|
|
|
Currently we have these policy implementations:
|
|
|
|
* Trusted Hosts Policy - You can configure list of trusted hosts and trusted domains. Request to Client Registration Service can be sent just from those hosts or domains.
|
|
Request sent from some untrusted IP will be rejected. URLs of newly registered client must also use just those trusted hosts or domains. For example it won't be allowed
|
|
to set `Redirect URI` of client pointing to some untrusted host. By default, there is not any whitelisted host, so anonymous client registration is de-facto disabled.
|
|
|
|
* Consent Required Policy - Newly registered clients will have `Consent Allowed` switch enabled. So after successful authentication, user will always
|
|
see consent screen when he needs to approve permissions (client scopes). It means that client won't have access to any personal
|
|
info or permission of user unless user approves it.
|
|
|
|
* Protocol Mappers Policy - Allows to configure list of whitelisted protocol mapper implementations. New client can't be registered
|
|
or updated if it contains some non-whitelisted protocol mapper. Note that this policy is used for authenticated requests as well, so
|
|
even for authenticated request there are some limitations which protocol mappers can be used.
|
|
|
|
* Client Scope Policy - Allow to whitelist `Client Scopes`, which can be used with newly registered or updated clients.
|
|
There are no whitelisted scopes by default; only the client scopes, which are defined as `Realm Default Client Scopes` are whitelisted by default.
|
|
|
|
* Full Scope Policy - Newly registered clients will have `Full Scope Allowed` switch disabled. This means they won't have any scoped
|
|
realm roles or client roles of other clients.
|
|
|
|
* Max Clients Policy - Rejects registration if current number of clients in the realm is same or bigger than specified limit. It's 200 by default for anonymous registrations.
|
|
|
|
* 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>
|