Chapter 4. Client Registration

In order for an application or service to utilize Red Hat Single Sign-On it has to register a client in Red Hat Single Sign-On. An admin can do this through the admin console (or admin REST endpoints), but clients can also register themselves through the Red Hat Single Sign-On client registration service.

The Client Registration Service provides built-in support for Red Hat Single Sign-On 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 - Red Hat Single Sign-On Client Representation (JSON)
  • install - Red Hat Single Sign-On 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.

4.1. Authentication

To invoke the Client Registration Services you need a token. The token can be a bearer token, an initial access token or a registration access token.

4.1.1. 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 Server Administration Guide 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 Server Administration Guide for more details).

4.1.2. 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 Initial Access Tokens 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: 

Authorization: bearer eyJhbGciOiJSUz...

4.1.3. 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.

4.2. Red Hat Single Sign-On Representations

The default client registration provider can be used to create, retrieve, update and delete a client. It uses Red Hat Single Sign-On 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>

4.3. Red Hat Single Sign-On 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: 

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 Red Hat Single Sign-On using the above URL.

4.4. OpenID Connect Dynamic Client Registration

Red Hat Single Sign-On implements OpenID Connect Dynamic Client Registration, which extends OAuth 2.0 Dynamic Client Registration Protocol and OAuth 2.0 Dynamic Client Registration Management Protocol.

The endpoint to use these specifications to register clients in Red Hat Single Sign-On 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.

4.5. 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 Red Hat Single Sign-On representation endpoints should be used. When creating a client a Red Hat Single Sign-On 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.

4.6. 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. 

curl -X POST \
    -d '{ "clientId": "myclient" }' \
    -H "Content-Type:application/json" \
    -H "Authorization: bearer eyJhbGciOiJSUz..." \
    http://localhost:8080/auth/realms/master/clients-registrations/default

4.7. 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. 

String token = "eyJhbGciOiJSUz...";

ClientRepresentation client = new ClientRepresentation();
client.setClientId(CLIENT_ID);

ClientRegistration reg = ClientRegistration.create().url("http://localhost:8080/auth/realms/myrealm/clients").build();
reg.auth(Auth.token(token));

client = reg.create(client);

String registrationAccessToken = client.getRegistrationAccessToken();