395 lines
16 KiB
Text
395 lines
16 KiB
Text
[[_client_registration_cli]]
|
|
== Client Registration CLI
|
|
|
|
`Client Registration CLI` is a command line interface tool for application developers to configure new clients in self-service manner
|
|
when integrating with {project_name}. It is specifically designed to interact with {project_name} Client Registration REST endpoints.
|
|
|
|
In order for any application to be able to use {project_name} it is necessary to create or obtain a client configuration. Usually a new client is configured for
|
|
each new application hosted on a unique hostname. When application interacts with {project_name} it needs to identify itself with a `client_id` in order for {project_name}
|
|
to be able to provide login page, SSO session management, and other services.
|
|
|
|
`Client Registration CLI` allows you to configure application clients from a command line, and can be used in shell scripts as well.
|
|
|
|
To allow a particular user to use `Client Registration CLI` the {project_name} administrator will typically use `Admin Console` to configure
|
|
a new user with proper roles, or configure a new client and client secret to grant access to `Client Registration REST API`.
|
|
|
|
|
|
[[_configuring_a_user_for_client_registration_cli]]
|
|
=== Configuring a new regular user for use with Client Registration CLI
|
|
|
|
Login as `admin` into `Admin Console` (e.g. `http://localhost:8080/auth/admin`). Select a realm you want to administer.
|
|
If you want to use existing user, select that user for edit, otherwise create a new user. Go to `Role Mappings` tab. Under
|
|
`Client Roles` select `realm-management` (if in master realm, select `NAME-realm` where NAME is name of the target realm - users in master realm can have access to any other realms).
|
|
Under `Available Roles` select `manage-client` for full set of client management permissions. Alternatively you can choose
|
|
`view-clients` for read-only or `create-client` for ability to create new clients.
|
|
These permissions grant user the capability to perform operations without the use of <<_initial_access_token,Initial Access Token>> or
|
|
<<_registration_access_token,Registration Access Token>>.
|
|
|
|
It's possible to not assign users any of `realm-management` roles. In that case user can still login with `Registration Client CLI`
|
|
but will not be able to use it without being in possession of an `Initial Access Token`. Trying to perform any operations
|
|
without it will result in `403 Forbidden` error.
|
|
|
|
Administrator can issue `Initial Access Tokens` from `Admin Console` by selecting `Client Registration` tab under `Realm Settings`, then `Initial Access Token` sub-tab.
|
|
|
|
[[_configuring_a_client_for_use_with_client_registration_cli]]
|
|
=== Configuring a client for use with Client Registration CLI
|
|
|
|
By default the `Client Registration CLI` identifies to the server as `admin-cli` client which is automatically configured for every new realm.
|
|
No additional client configuration is necessary when logging in with username. You may wish to strengthen security by
|
|
configuring the client `Access Type` as `Confidential`, and under `Credentials` tab select `ClientId and Secret`. When
|
|
running `kcreg config credentials` you would then also have to provide a secret by using `--secret` option.
|
|
|
|
If you want to use a separate client configuration for `Registration Client CLI` then you can create a new client - you can call it `reg-cli`
|
|
for example. When running `kcreg config credentials` you then need to specify which `clientId` to use e.g. `--client reg-cli`.
|
|
|
|
If you want to use a service account associated with the client, you first need to enable service accounts. In `Admin Console`
|
|
go to `Clients` section, and select a client for edit. Then under `Settings` change the `Access Type` to `Confidential`, and toggle
|
|
`Service Accounts Enabled` setting to `On`. Make sure to `Save` the configuration.
|
|
|
|
Under `Credentials` tab you can choose to configure either `Client Id and Secret`, or `Signed JWT`.
|
|
|
|
Having done that you can then omit specifying user during `kcreg config credentials`, and only provide client secret or keystore info.
|
|
|
|
[[_installing_client_registration_cli]]
|
|
=== Installing Client Registration CLI
|
|
|
|
Client Registration CLI is packaged inside Keycloak Server distribution. You can find execution scripts inside `bin` directory.
|
|
|
|
The Linux script is called `kcreg.sh`, and the one for Windows is called `kcreg.bat`.
|
|
|
|
In order to setup the client for use from any location on the filesystem you may want to add Keycloak server directory to your PATH.
|
|
|
|
On Linux:
|
|
[source,bash]
|
|
----
|
|
$ export PATH=$PATH:$KEYCLOAK_HOME/bin
|
|
$ kcreg.sh
|
|
----
|
|
|
|
On Windows:
|
|
[source,bash]
|
|
----
|
|
c:\> set PATH=%PATH%;%KEYCLOAK_HOME%\bin
|
|
c:\> kcreg
|
|
----
|
|
|
|
Where KEYCLOAK_HOME refers to a directory where Keycloak Server distribution was unpacked.
|
|
|
|
|
|
[[_using_client_registration_cli]]
|
|
=== Using Client Registration CLI
|
|
|
|
First you need to start an authenticated session (i.e. logging in) by providing credentials. Then you perform operations on Client Registration REST endpoint.
|
|
|
|
For example on Linux:
|
|
|
|
[source,bash]
|
|
----
|
|
$ 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
|
|
----
|
|
|
|
Or on Windows:
|
|
|
|
[source,bash]
|
|
----
|
|
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
|
|
----
|
|
|
|
|
|
In a production environment Keycloak has to be accessed with `https:` to avoid exposing tokens to network sniffers. If server's
|
|
certificate is not issued by one of the trusted CAs that are included in Java's default certificate truststore, you will
|
|
need to prepare a truststore.jks file, and instruct `Client Registration CLI` to use it.
|
|
|
|
For example on Linux:
|
|
[source,bash]
|
|
----
|
|
$ kcreg.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks
|
|
----
|
|
|
|
Or on Windows:
|
|
|
|
[source,bash]
|
|
----
|
|
c:\> kcreg config truststore --trustpass %PASSWORD% %HOMEPATH%\.keycloak\truststore.jks
|
|
----
|
|
|
|
|
|
[[_logging_in]]
|
|
==== Logging In
|
|
|
|
When logging in with `Client Registration CLI` you specify a server endpoint url, and a realm. Then you specify a username
|
|
or, alternatively, a client id, which will result in special service account being used. In the first case,
|
|
a password for the specified user has to be used at login. In the latter case there is no user password - only client secret
|
|
or a `Signed JWT` is used.
|
|
|
|
Regardless of the method, the account that logs in needs proper permissions to be able to perform client
|
|
registration operations. Keep in mind that any account in 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 `master` realm and
|
|
add it roles for managing clients in different realms.
|
|
|
|
`Client Registration CLI` by itself does not support configuring users, for that you would need to use `Admin Console`
|
|
web interface or Admin Client CLI command line tool (see link:{adminguide_link}[{adminguide_name}] for more details).
|
|
|
|
When `kcreg` successfully logs in it receives authorization tokens and saves them into private config file so they can be
|
|
used for subsequent invocations. See <<_working_with_alternative_configurations, next chapter>> for more info on configuration file.
|
|
|
|
See built-in help for more information on using `Client Registration CLI`.
|
|
|
|
|
|
For example on Linux:
|
|
[source,bash]
|
|
----
|
|
$ kcreg.sh help
|
|
----
|
|
|
|
|
|
Or on Windows:
|
|
[source,bash]
|
|
----
|
|
c:\> kcreg help
|
|
----
|
|
|
|
See `kcreg config credentials --help` for more information about starting an authenticated session.
|
|
|
|
|
|
|
|
[[_working_with_alternative_configurations]]
|
|
==== Working with alternative configurations
|
|
|
|
By default, `Client Registration CLI` automatically maintains a configuration file at a default location - `./.keycloak/kcreg.config`
|
|
under user's home directory.
|
|
|
|
You can always use `--config` option to point to a different file / location. This way you can mantain multiple authenticated
|
|
sessions in parallel. It is safest to perform operations tied to a single config file from a single thread.
|
|
|
|
Make sure to not make the config file visible to other users on the system as it contains access tokens, and secrets that should be kept private.
|
|
|
|
You may want to avoid storing any secrets at all inside a config file for the price of less convenience and having to do more token requests.
|
|
In that case you can use `--no-config` option with all your commands. You will have to specify all authentication info with each
|
|
`kcreg` invocation.
|
|
|
|
|
|
|
|
[[_initial_access_and_registration_access_tokens]]
|
|
==== Initial Access and Registration Access Tokens
|
|
|
|
`Client Registration CLI` can be used by developers who don't have an account configured at Keycloak server they want to use.
|
|
That's possible when realm administrator issues developer an `Initial Access Token`. It is up to realm administrator to decide
|
|
how to issue and distribute these tokens. Admin can limit Initial Access Token's maximum age, and a total number of clients
|
|
that can be created with it. Many Initial Access Tokens can be created, and it's up to realm administrator to distribute them
|
|
to application developers.
|
|
|
|
Once a developer is in possession of Initial Access Token they can use it to create new clients without authenticating
|
|
with `kcreg config credentials`. Rather, Initial Access Token can be stored in configuration, or specified as part of `kcreg create`
|
|
command.
|
|
|
|
For example on Linux:
|
|
[source,bash]
|
|
----
|
|
$ kcreg.sh config initial-token $TOKEN
|
|
$ kcreg.sh create -s clientId=myclient
|
|
----
|
|
|
|
or
|
|
|
|
[source,bash]
|
|
----
|
|
$ kcreg.sh create -s clientId=myclient -t $TOKEN
|
|
----
|
|
|
|
|
|
On Windows:
|
|
[source,bash]
|
|
----
|
|
c:\> kcreg config initial-token %TOKEN%
|
|
c:\> kcreg create -s clientId=myclient
|
|
----
|
|
|
|
or
|
|
|
|
[source,bash]
|
|
----
|
|
c:\> kcreg create -s clientId=myclient -t %TOKEN%
|
|
----
|
|
|
|
|
|
When Initial Access Token is used, the server response will include 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.
|
|
|
|
`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 will not need to
|
|
authenticate in order to read, update, or delete a client that was created this way.
|
|
|
|
|
|
You can read more about Initial Access and Registration Access Tokens in <<_client_registration,Client Registration chapter>>.
|
|
|
|
See `kcreg config initial-token --help` and `kcreg config registration-token --help` for more information on how to configure them with `Client Registration CLI`.
|
|
|
|
|
|
|
|
[[_performing_crud_operations]]
|
|
==== Creating client configuration
|
|
|
|
After authenticating with credentials or configuring Initial Access Token, the first operation will usually be to create a new client.
|
|
|
|
We've seen the simplest create command already. Often we may want to use a prepared JSON file as a template and set / override
|
|
some of the attributes. For example, here is how you read a JSON file, override any `clientId` it may contain,
|
|
set any other attributes as well, and after successful creation print the configuration to standard output.
|
|
|
|
On Linux:
|
|
[source,bash]
|
|
----
|
|
$ kcreg.sh create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s 'redirectUris=["/myclient/*"]' -o
|
|
----
|
|
|
|
On Windows:
|
|
[source,bash]
|
|
----
|
|
C:\> kcreg create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s "redirectUris=[\"/myclient/*\"]" -o
|
|
----
|
|
|
|
|
|
See `kcreg create --help` for more information about `kcreg create`.
|
|
|
|
|
|
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. Also note that you should not have any `id` fields in your
|
|
template and should not specify them as arguments to `kcreg create`.
|
|
|
|
|
|
==== Retrieving client configuration
|
|
|
|
You can retrieve an existing client by using `kcreg get`.
|
|
|
|
For example, on Linux:
|
|
[source,bash]
|
|
----
|
|
$ kcreg.sh get myclient
|
|
----
|
|
|
|
On Windows:
|
|
[source,bash]
|
|
----
|
|
C:\> kcreg get myclient
|
|
----
|
|
|
|
|
|
You can also get client configuration as adapter configuration file which you can package with your web application.
|
|
|
|
For example, on Linux:
|
|
[source,bash]
|
|
----
|
|
$ kcreg.sh get myclient -e install > keycloak.json
|
|
----
|
|
|
|
On Windows:
|
|
[source,bash]
|
|
----
|
|
C:\> kcreg get myclient -e install > keycloak.json
|
|
----
|
|
|
|
See `kcreg get --help` for more information about `kcreg get`.
|
|
|
|
==== Modifying client configuration
|
|
|
|
There are two modes of updating client configuration.
|
|
|
|
One is to submit a complete new state to the server after getting current configuration, saving it into a file, editing it, and posting it back.
|
|
|
|
On Linux:
|
|
[source,bash]
|
|
----
|
|
$ kcreg.sh get myclient > myclient.json
|
|
$ vi myclient.json
|
|
$ kcreg.sh update myclient -f myclient.json
|
|
----
|
|
|
|
On Windows:
|
|
[source,bash]
|
|
----
|
|
C:\> kcreg get myclient > myclient.json
|
|
C:\> notepad myclient.json
|
|
C:\> kcreg update myclient -f myclient.json
|
|
----
|
|
|
|
|
|
Another way is to fetch current client, set or delete fields on it, and post it back all in one single step.
|
|
|
|
For example, on Linux:
|
|
[source,bash]
|
|
----
|
|
$ kcreg.sh update myclient -s enabled=false -d redirectUris
|
|
----
|
|
|
|
On Windows:
|
|
[source,bash]
|
|
----
|
|
C:\> kcreg update myclient -s enabled=false -d redirectUris
|
|
----
|
|
|
|
|
|
You can even use a file that only contains changes to be applied so you don't have to specify too many values as arguments.
|
|
In this case specify `--merge` to tell `Client Registration CLI` that rather than treating JSON file as full
|
|
new configuration, it should treat it as a set of attributes to be applied over existing configuration.
|
|
|
|
|
|
On Linux:
|
|
[source,bash]
|
|
----
|
|
$ kcreg.sh update myclient --merge -d redirectUris -f mychanges.json
|
|
----
|
|
|
|
On Windows:
|
|
[source,bash]
|
|
----
|
|
C:\> kcreg update myclient --merge -d redirectUris -f mychanges.json
|
|
----
|
|
|
|
See `kcreg update --help` for more information about `kcreg update`.
|
|
|
|
==== Deleting client configuration
|
|
|
|
You may sometimes also need to delete a client.
|
|
|
|
On Linux:
|
|
[source,bash]
|
|
----
|
|
$ kcreg.sh delete myclient
|
|
----
|
|
|
|
On Windows:
|
|
[source,bash]
|
|
----
|
|
C:\> kcreg delete myclient
|
|
----
|
|
|
|
See `kcreg delete --help` for more information about `kcreg delete`.
|
|
|
|
|
|
|
|
[[_refreshing_invalid_registration_access_tokens]]
|
|
==== Refreshing Invalid Registration Access Tokens
|
|
|
|
When performing a CRUD operation using `--no-config` mode, `Client Registration CLI` can no longer handle Registration Access Tokens for you.
|
|
In that case it is possible to lose track of 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 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 stdout or saved to a config
|
|
file of your choice. Otherwise you have to ask realm administrator to issue new Registration Access Token for your client, and send it
|
|
to you. You can then pass it to any CRUD command via `--token` option. You can also use `kcreg config registration-token`
|
|
command to save the new token in configuration file, and have `Client Registration CLI` automatically handle it for you from that point on.
|
|
|
|
See `kcreg update-token --help` for more information about `kcreg update-token`.
|
|
|
|
|
|
|
|
[[_troubleshooting_2]]
|
|
=== Troubleshooting
|
|
|
|
* Q: When logging in I get an error: `Parameter client_assertion_type is missing [invalid_client]`
|
|
+
|
|
A: Your client is configured with `Signed JWT` token credentials which means you have to use `--keystore` parameter when logging in.
|