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 {project_name}. It is specifically designed to interact with {project_name} Client Registration REST endpoints.
It is necessary to create or obtain a client configuration for any application to be able to use {project_name}. You usually configure a new client for each new application hosted on a unique host name. When an application interacts with {project_name}, the application identifies itself with a client ID so {project_name} can provide a login page, single sign-on (SSO) session management, and other services.
To allow a particular user to use `Client Registration CLI` the {project_name} 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.
. Log in to the Admin Console (for example, http://localhost:8080/auth/admin) as [command]`admin`.
. Select a realm to administer.
. If you want to use an existing user, select that user to edit; otherwise, create a new user.
. 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.
. 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.
These permissions grant the user the capability to perform operations without the use of <<_initial_access_token,Initial Access Token>> or <<_registration_access_token,Registration Access Token>>.
It is possible to not assign any [command]`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.
By default, the server recognizes the Client Registration CLI as the [filename]`admin-cli` client, which is configured automatically for every new realm. No additional client configuration is necessary when logging in with a user name.
. Strengthen the security by configuring the client [filename]`Access Type` as [filename]`Confidential` and selecting *Credentials > ClientId and Secret*.
. Provide a secret when running [command]`kcreg config credentials` by using the [command]`--secret` option.
. Specify which [filename]`clientId` to use (for example, [command]`--client reg-cli`) when running [command]`kcreg config credentials`.
. 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`.
. With the service account enabled, you can omit specifying the user when running [command]`kcreg config credentials` and only provide the client secret or keystore information.
The Client Registration CLI is packaged inside the {project_name} Server distribution. You can find execution scripts inside the [filename]`bin` directory. The Linux script is called [filename]`kcreg.sh`, and the Windows script is called [filename]`kcreg.bat`.
. 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 [filename]`truststore.jks` file and instruct the Client Registration CLI to use it.
. 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 [filename]`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 [filename]`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 link:{adminguide_link}[{adminguide_name}] for more details.
When [filename]`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 <<_working_with_alternative_configurations>> for more information on configuration files.
By default, the Client Registration CLI automatically maintains a configuration file at a default location, [filename]`./.keycloak/kcreg.config`, under the user's home directory. You can use the [command]`--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.
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 [command]`--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 [command]`kcreg` invocation.
Developers who do not have an account configured at the {project_name} 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 [command]`kcreg config credentials`. The Initial Access Token can be stored in the configuration file or specified as part of the [command]`kcreg create` command.
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.
Run the [command]`kcreg config initial-token --help` and [command]`kcreg config registration-token --help` commands for more information on how to configure tokens with the Client Registration CLI.
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.
You can use [command]`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
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.
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 [command]`--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.
When performing a create, read, update, and delete (CRUD) operation using the [command]`--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 [command]`--token` option. You can also use the [command]`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.
A: This error means your client is configured with [filename]`Signed JWT` token credentials, which means you have to use the [command]`--keystore` parameter when logging in.
