208 lines
12 KiB
Text
208 lines
12 KiB
Text
[[_client_registration]]
|
|
== Client Registration
|
|
|
|
In order for an application or service to utilize {{book.project.name}} it has to register a client in {{book.project.name}}.
|
|
An admin can do this through the admin console (or admin REST endpoints), but clients can also register themselves through the {{book.project.name}} client
|
|
registration service.
|
|
|
|
The Client Registration Service provides built-in support for {{book.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 - {{book.project.name}} Client Representation (JSON)
|
|
* install - {{book.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
|
|
|
|
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:{{book.adminguide.link}}[{{book.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:{{book.adminguide.link}}[{{book.adminguide.name}}] for more details).
|
|
|
|
==== 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 `Realm Settings` in the menu on the left, followed by
|
|
`Client Registration` in the tabs displayed in the page. Then finally click on `Initial Access Tokens` sub-tab.
|
|
|
|
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
|
|
|
|
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.
|
|
Registration access tokens are only valid once when it's used the response will include a new token.
|
|
|
|
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 loose 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`.
|
|
|
|
=== {{book.project.name}} Representations
|
|
|
|
The `default` client registration provider can be used to create, retrieve, update and delete a client.
|
|
It uses {{book.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 do a HTTP POST 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 then do a HTTP GET to `/realms/<realm>/clients-registrations/default/<client id>`.
|
|
|
|
It will also return a new registration access token.
|
|
|
|
To update the Client Representation then do a HTTP PUT to 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 then do a HTTP DELETE to:
|
|
`/realms/<realm>/clients-registrations/default/<client id>`
|
|
|
|
=== {{book.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 do a HTTP GET 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 {{book.project.name}} using the above URL.
|
|
|
|
=== OpenID Connect Dynamic Client Registration
|
|
|
|
{{book.project.name}} implements https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration], which extends https://tools.ietf.org/html/rfc7591[OAuth 2.0 Dynamic Client Registration Protocol] and https://tools.ietf.org/html/rfc7592[OAuth 2.0 Dynamic Client Registration Management Protocol].
|
|
|
|
The endpoint to use these specifications to register clients in {{book.project.name}} is `/realms/<realm>/clients-registrations/openid-connect[/<client id>]`.
|
|
|
|
This endpoints 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 {{book.project.name}} representation endpoints should be used.
|
|
When creating a client a {{book.project.name}} Client Representation is returned with details about the created client, including a registration access token.
|
|
|
|
To create a client do a HTTP POST 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]
|
|
----
|
|
curl -X POST \
|
|
-d '{ "clientId": "myclient" }' \
|
|
-H "Content-Type:application/json" \
|
|
-H "Authorization: bearer eyJhbGciOiJSUz..." \
|
|
http://localhost:8080/auth/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]
|
|
----
|
|
String token = "eyJhbGciOiJSUz...";
|
|
|
|
ClientRepresentation client = new ClientRepresentation();
|
|
client.setClientId(CLIENT_ID);
|
|
|
|
ClientRegistration reg = ClientRegistration.create()
|
|
.url("http://localhost:8080/auth", "myrealm")
|
|
.build();
|
|
|
|
reg.auth(Auth.token(token));
|
|
|
|
client = reg.create(client);
|
|
|
|
String registrationAccessToken = client.getRegistrationAccessToken();
|
|
----
|
|
|
|
=== Client Registration Policies
|
|
|
|
{{book.project.name}} currently supports 2 ways how can be new clients 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 {{book.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 by default.
|
|
|
|
* 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 personal info and permissions (protocol mappers and roles). 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 Template Policy - Allow to whitelist `Client Templates`, which can be used with newly registered or updated clients.
|
|
There are no whitelisted templates 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.
|