The Client Registration Service provides built-in support for {project_name} Client Representations, OpenID Connect Client Meta Data and SAML Entity Descriptors.
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).
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):
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).
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.
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.
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].
To create a client create a Client Representation (JSON) then perform an HTTP POST request to `{kc_realms_path}/<realm>/clients-registrations/default`.
The endpoint to use these specifications to register clients in {project_name} is `{kc_realms_path}/<realm>/clients-registrations/openid-connect[/<client id>]`.
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`.
The following example creates a client with the clientId `myclient` using CURL. You need to replace `eyJhbGciOiJSUz...` with a proper initial access token or
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.
* 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.
* 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.
