Chapter 6. Client Registration CLI

The Client Registration CLI is a command-line interface (CLI) tool for application developers to configure new clients in a self-service manner when integrating with Red Hat Single Sign-On. It is specifically designed to interact with Red Hat Single Sign-On Client Registration REST endpoints.

It is necessary to create or obtain a client configuration for any application to be able to use Red Hat Single Sign-On. You usually configure a new client for each new application hosted on a unique host name. When an application interacts with Red Hat Single Sign-On, the application identifies itself with a client ID so Red Hat Single Sign-On can provide a login page, single sign-on (SSO) session management, and other services.

You can configure application clients from a command line with the Client Registration CLI, and you can use it in shell scripts.

To allow a particular user to use Client Registration CLI the Red Hat Single Sign-On administrator typically uses the Admin Console to configure a new user with proper roles or to configure a new client and client secret to grant access to the Client Registration REST API.

6.1. Configuring a new regular user for use with Client Registration CLI

  1. Log in to the Admin Console (for example, http://localhost:8080/auth/admin) as admin.
  2. Select a realm to administer.
  3. If you want to use an existing user, select that user to edit; otherwise, create a new user.
  4. Select Role Mappings > Client Roles > realm-management. If you are in the master realm, select NAME-realm, where NAME is the name of the target realm. You can grant access to any other realm to users in the master realm.

  5. Select Available Roles > manage-client to grant a full set of client management permissions. Another option is to choose view-clients for read-only or create-client to create new clients.

    Note

    These permissions grant the user the capability to perform operations without the use of Initial Access Token or Registration Access Token.

It is possible to not assign any realm-management roles to a user. In that case, a user can still log in with the Client Registration CLI but cannot use it without an Initial Access Token. Trying to perform any operations without a token results in a 403 Forbidden error.

The Administrator can issue Initial Access Tokens from the Admin Console through the Realm Settings > Client Registration > Initial Access Token menu.

6.2. Configuring a client for use with the Client Registration CLI

By default, the server recognizes the Client Registration CLI as the admin-cli client, which is configured automatically for every new realm. No additional client configuration is necessary when logging in with a user name.

  1. Strengthen the security by configuring the client Access Type as Confidential and selecting Credentials > ClientId and Secret.
  2. Provide a secret when running kcreg config credentials by using the --secret option.
  3. Create a new client (for example, reg-cli) if you want to use a separate client configuration for the Client Registration CLI.
  4. Specify which clientId to use (for example, --client reg-cli) when running kcreg config credentials.
  5. Enable service accounts if you want to use a service account associated with the client by selecting a client to edit in the Clients section of the Admin Console.

  6. Under Settings, change the Access Type to Confidential, toggle the Service Accounts Enabled setting to On, and click Save.

    Note

    You can configure either Client Id and Secret or Signed JWT under the Credentials tab .

  7. With the service account enabled, you can omit specifying the user when running kcreg config credentials and only provide the client secret or keystore information.

6.3. Installing the Client Registration CLI

The Client Registration CLI is packaged inside the Red Hat Single Sign-On Server distribution. You can find execution scripts inside the bin directory. The Linux script is called kcreg.sh, and the Windows script is called kcreg.bat.

Add the Red Hat Single Sign-On server directory to your PATH when setting up the client for use from any location on the file system.

For example, on:

  • Linux: 
$ export PATH=$PATH:$KEYCLOAK_HOME/bin
$ kcreg.sh
  • Windows: 
c:\> set PATH=%PATH%;%KEYCLOAK_HOME%\bin
c:\> kcreg

KEYCLOAK_HOME refers to a directory where the Red Hat Single Sign-On Server distribution was unpacked.

6.4. Using the Client Registration CLI

  1. Start an authenticated session by logging in with your credentials.

  2. Run commands on the Client Registration REST endpoint.

    For example, on:

    • Linux: 

      $ kcreg.sh config credentials --server http://localhost:8080/auth --realm demo --user user --client reg-cli
$ kcreg.sh create -s clientId=my_client -s 'redirectUris=["http://localhost:8980/myapp/*"]'
$ kcreg.sh get my_client

    • Windows: 

      c:\> kcreg config credentials --server http://localhost:8080/auth --realm demo --user user --client reg-cli
c:\> kcreg create -s clientId=my_client -s "redirectUris=[\"http://localhost:8980/myapp/*\"]"
c:\> kcreg get my_client
      Note

      In a production environment, Red Hat Single Sign-On has to be accessed with https: to avoid exposing tokens to network sniffers.

  3. If a server’s certificate is not issued by one of the trusted certificate authorities (CAs) that are included in Java’s default certificate truststore, prepare a truststore.jks file and instruct the Client Registration CLI to use it.

    For example, on:

    • Linux: 

      $ kcreg.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks

    • Windows: 

      c:\> kcreg config truststore --trustpass %PASSWORD% %HOMEPATH%\.keycloak\truststore.jks

6.4.1. Logging in

  1. Specify a server endpoint URL and a realm when you log in with the Client Registration CLI.
  2. Specify a user name or a client id, which results in a special service account being used. When using a user name, you must use a password for the specified user. When using a client ID, you use a client secret or a Signed JWT instead of a password.

Regardless of the login method, the account that logs in needs proper permissions to be able to perform client registration operations. Keep in mind that any account in a non-master realm can only have permissions to manage clients within the same realm. If you need to manage different realms, you can either configure multiple users in different realms, or you can create a single user in the master realm and add roles for managing clients in different realms.

You cannot configure users with the Client Registration CLI. Use the Admin Console web interface or the Admin Client CLI to configure users. See Server Administration Guide for more details.

When kcreg successfully logs in, it receives authorization tokens and saves them in a private configuration file so the tokens can be used for subsequent invocations. See Section 6.4.2, “Working with alternative configurations” for more information on configuration files.

See the built-in help for more information on using the Client Registration CLI.

For example, on:

  • Linux: 
$ kcreg.sh help
  • Windows: 
c:\> kcreg help

See kcreg config credentials --help for more information about starting an authenticated session.

6.4.2. Working with alternative configurations

By default, the Client Registration CLI automatically maintains a configuration file at a default location, ./.keycloak/kcreg.config, under the user’s home directory. You can use the --config option to point to a different file or location to mantain multiple authenticated sessions in parallel. It is the safest way to perform operations tied to a single configuration file from a single thread.

Important

Do not make the configuration file visible to other users on the system. The configuration file contains access tokens and secrets that should be kept private.

You might want to avoid storing secrets inside a configuration file by using the --no-config option with all of your commands, even though it is less convenient and requires more token requests to do so. Specify all authentication information with each kcreg invocation.

6.4.3. Initial Access and Registration Access Tokens

Developers who do not have an account configured at the Red Hat Single Sign-On server they want to use can use the Client Registration CLI. This is possible only when the realm administrator issues a developer an Initial Access Token. It is up to the realm administrator to decide how and when to issue and distribute these tokens. The realm administrator can limit the maximum age of the Initial Access Token and the total number of clients that can be created with it.

Once a developer has an Initial Access Token, the developer can use it to create new clients without authenticating with kcreg config credentials. The Initial Access Token can be stored in the configuration file or specified as part of the kcreg create command.

For example, on:

  • Linux: 
$ kcreg.sh config initial-token $TOKEN
$ kcreg.sh create -s clientId=myclient

or 

$ kcreg.sh create -s clientId=myclient -t $TOKEN
  • Windows: 
c:\> kcreg config initial-token %TOKEN%
c:\> kcreg create -s clientId=myclient

or 

c:\> kcreg create -s clientId=myclient -t %TOKEN%

When using an Initial Access Token, the server response includes a newly issued Registration Access Token. Any subsequent operation for that client needs to be performed by authenticating with that token, which is only valid for that client.

The Client Registration CLI automatically uses its private configuration file to save and use this token with its associated client. As long as the same configuration file is used for all client operations, the developer does not need to authenticate to read, update, or delete a client that was created this way.

See Client Registration for more information about Initial Access and Registration Access Tokens.

Run the kcreg config initial-token --help and kcreg config registration-token --help commands for more information on how to configure tokens with the Client Registration CLI.

6.4.4. Creating a client configuration

The first task after authenticating with credentials or configuring an Initial Access Token is usually to create a new client. Often you might want to use a prepared JSON file as a template and set or override some of the attributes.

The following example shows how to read a JSON file, override any client id it may contain, set any other attributes, and print the configuration to a standard output after successful creation.

  • Linux: 
$ kcreg.sh create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s 'redirectUris=["/myclient/*"]' -o
  • Windows: 
C:\> kcreg create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s "redirectUris=[\"/myclient/*\"]" -o

Run the kcreg create --help for more information about the kcreg create command.

You can use kcreg attrs to list available attributes. Keep in mind that many configuration attributes are not checked for validity or consistency. It is up to you to specify proper values. Remember that you should not have any id fields in your template and should not specify them as arguments to the kcreg create command.

6.4.5. Retrieving a client configuration

You can retrieve an existing client by using the kcreg get command.

For example, on:

  • Linux: 
$ kcreg.sh get myclient
  • Windows: 
C:\> kcreg get myclient

You can also retrieve the client configuration as an adapter configuration file, which you can package with your web application.

For example, on:

  • Linux: 
$ kcreg.sh get myclient -e install > keycloak.json
  • Windows: 
C:\> kcreg get myclient -e install > keycloak.json

Run the kcreg get --help command for more information about the kcreg get command.

6.4.6. Modifying a client configuration

There are two methods for updating a client configuration.

One method is to submit a complete new state to the server after getting the current configuration, saving it to a file, editing it, and posting it back to the server.

For example, on:

  • Linux: 
$ kcreg.sh get myclient > myclient.json
$ vi myclient.json
$ kcreg.sh update myclient -f myclient.json
  • Windows: 
C:\> kcreg get myclient > myclient.json
C:\> notepad myclient.json
C:\> kcreg update myclient -f myclient.json

The second method fetches the current client, sets or deletes fields on it, and posts it back in one step.

For example, on:

  • Linux: 
$ kcreg.sh update myclient -s enabled=false -d redirectUris
  • Windows: 
C:\> kcreg update myclient -s enabled=false -d redirectUris

You can also use a file that contains only changes to be applied so you do not have to specify too many values as arguments. In this case, specify --merge to tell the Client Registration CLI that rather than treating the JSON file as a full, new configuration, it should treat it as a set of attributes to be applied over the existing configuration.

For example, on:

  • Linux: 
$ kcreg.sh update myclient --merge -d redirectUris -f mychanges.json
  • Windows: 
C:\> kcreg update myclient --merge -d redirectUris -f mychanges.json

Run the kcreg update --help command for more information about the kcreg update command.

6.4.7. Deleting a client configuration

Use the following example to delete a client.

  • Linux: 
$ kcreg.sh delete myclient
  • Windows: 
C:\> kcreg delete myclient

Run the kcreg delete --help command for more information about the kcreg delete command.

6.4.8. Refreshing invalid Registration Access Tokens

When performing a create, read, update, and delete (CRUD) operation using the --no-config mode, the Client Registration CLI cannot handle Registration Access Tokens for you. In that case, it is possible to lose track of the most recently issued Registration Access Token for a client, which makes it impossible to perform any further CRUD operations on that client without authenticating with an account that has manage-clients permissions.

If you have permissions, you can issue a new Registration Access Token for the client and have it printed to a standard output or saved to a configuration file of your choice. Otherwise, you have to ask the realm administrator to issue a new Registration Access Token for your client and send it to you. You can then pass it to any CRUD command via the --token option. You can also use the kcreg config registration-token command to save the new token in a configuration file and have the Client Registration CLI automatically handle it for you from that point on.

Run the kcreg update-token --help command for more information about the kcreg update-token command.

6.5. Troubleshooting

  • Q: When logging in, I get an error: *Parameter client_assertion_type is missing [invalid_client].

    A: This error means your client is configured with Signed JWT token credentials, which means you have to use the --keystore parameter when logging in.