Merge pull request #45 from mstruk/cli-reg
Add Client Registration CLI documentation
This commit is contained in:
Stian Thorgersen
GitHub
commit
8af25d88bb
2 changed files with 387 additions and 0 deletions
|
|
@ -86,3 +86,4 @@
|
|||
{% endif %}
|
||||
.. link:topics/saml/mod-auth-mellon.adoc[mod_auth_mellon Apache HTTPD Module]
|
||||
. link:topics/client-registration.adoc[Client Registration]
|
||||
.. link:topics/client-registration/client-registration-cli.adoc[Client Registration CLI]
|
||||
|
|
|
|||
386
topics/client-registration/client-registration-cli.adoc
Normal file
386
topics/client-registration/client-registration-cli.adoc
Normal file
|
|
@ -0,0 +1,386 @@
|
|||
[[_client_registration_cli]]
|
||||
== Client Registration CLI
|
||||
|
||||
`Client Registration CLI` is a command line interface tool that can be used by application developers to configure new clients
|
||||
to integrate with {book_project_name}. It is specifically designed to interact with {{book.project.name}} Client Registration REST endpoints.
|
||||
|
||||
It is necessary to create a new client configuration for each new application hosted on a unique hostname in order for Keycloak
|
||||
to be able to interact with the application (and vice-versa) and perform its function of providing a login page, SSO session management etc.
|
||||
|
||||
`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` a {book_project_name} administrator will typically use `Admin Console` to configure
|
||||
a new user, or configure a new client, and a client secret, to protect 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 it for edit, otherwise create a new user. Go to `Role Mappings` tab. Under
|
||||
`Client Roles` select `realm-management`. 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` or
|
||||
`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 having 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 `Initial Access Token` tab under `Realm Settings`.
|
||||
|
||||
[[_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 as `admin-cli` client which is automatically configured for every new realm.
|
||||
No additional client configuration is required when using login with a 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 e.g. by using `--secret`.
|
||||
|
||||
If you want to use a separate client configuration for `Registration Client CLI` then you can create a new client - for
|
||||
example you can call it `reg-cli`. When running `kcreg config credentials` you then need to specify a `clientId` to use e.g. `--client reg-cli`.
|
||||
|
||||
If you want to use a service account associated with the client, then you need to enable a service account. In `Admin Client`
|
||||
you go to `Clients` section, and select a client for edit. Then under `Settings` first change `Access Type` to `Confidential`.
|
||||
Then toggle `Service Accounts Enabled` setting to `On`, and `Save` the configuration.
|
||||
|
||||
Under `Credentials` tab you can choose to configure either `Client Id and Secret`, or `Signed JWT`.
|
||||
|
||||
You can now avoid specifying user when using `kcreg config credentials` and only provide a 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 to be used 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
|
||||
----
|
||||
|
||||
[[_using_client_registration_cli]]
|
||||
=== Using Client Registration CLI
|
||||
|
||||
Usually a user will first start an authenticated session by providing credentials, then perform some CRUD operations.
|
||||
|
||||
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
|
||||
----
|
||||
|
||||
|
||||
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, then 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 you can only specify 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 to have proper permissions in order to be able to perform client
|
||||
registration operations. Keep in mind that any account can only have permissions to manage clients within the same realm.
|
||||
If you need to manage different realms, you need to configure users in different realms with permissions to manage clients.
|
||||
|
||||
`Client Registration CLI` by itself does not support configuring the users, for that you would need to use `Admin Console`
|
||||
web interface or `Admin Client CLI` once it's available.
|
||||
|
||||
When `kcreg` successfully logs in it receives authorization tokens and saves them into a private config file so they can be
|
||||
used for subsequent invocations. See <<fake/#_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 use `--config` option at any time 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 a 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 an Initial Access Token by 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.
|
||||
|
||||
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 for client that was
|
||||
just created. Any subsequent operation for that client needs to be performed by authenticating with that token.
|
||||
|
||||
`Client Registration CLI` automatically uses its private configuration file to save, and make use of this token for each
|
||||
created 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 they created.
|
||||
|
||||
|
||||
You can read more about Initial Access and Registration Access Tokens in <<fake/../client-registration.adoc#_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]]
|
||||
==== Performing CRUD operations
|
||||
|
||||
|
||||
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 command to create a new client already. Often we may want to use a prepared JSON file as a template,
|
||||
and set / override some of the attributes. For example, this is how you read a JSON file in default client configuration format,
|
||||
override any clientId it may contain with a new one, override / set any other attributes as well, and after successful creation
|
||||
print the new client configuration to standard output.
|
||||
|
||||
On Linux:
|
||||
[source,bash]
|
||||
----
|
||||
$ kcreg.sh create -s clientId=myclient -f client-template.json -s baseUrl=/myclient -s 'redirectUris=["/myclient/*"]' -o
|
||||
----
|
||||
|
||||
On Windows:
|
||||
[source,bash]
|
||||
----
|
||||
C:\> kcreg create -s clientId=myclient -f client-template.json -s baseUrl=/myclient -s "redirectUris=[\"/myclient/*\"]" -o
|
||||
----
|
||||
|
||||
|
||||
See `kcreg create --help` for more information about `kcreg create`.
|
||||
|
||||
|
||||
You can use `kcreg attrs` to list the available attributes. Note, 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 or specify them as arguments to `kcreg create`.
|
||||
|
||||
|
||||
Once a new client is created you can retrieve it again by using `kcreg get`.
|
||||
|
||||
On Linux:
|
||||
[source,bash]
|
||||
----
|
||||
$ kcreg.sh get
|
||||
----
|
||||
|
||||
On Windows:
|
||||
[source,bash]
|
||||
----
|
||||
C:\> kcreg get
|
||||
----
|
||||
|
||||
|
||||
You can also get an adapter configuration which you can drop into your web application in order to integrate with Keycloak server.
|
||||
|
||||
On Linux:
|
||||
[source,bash]
|
||||
----
|
||||
$ kcreg.sh get -e install
|
||||
----
|
||||
|
||||
On Windows:
|
||||
[source,bash]
|
||||
----
|
||||
C:\> kcreg get -e install
|
||||
----
|
||||
|
||||
See `kcreg get --help` for more information about `kcreg get`.
|
||||
|
||||
|
||||
It's simple to update client configurations as well. There are two modes of updating.
|
||||
|
||||
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.json
|
||||
$ vi myclient.json
|
||||
$ kcreg.sh update myclient -f myclient.json
|
||||
----
|
||||
|
||||
On Windows:
|
||||
[source,bash]
|
||||
----
|
||||
C:\> kcreg get > myclient.json
|
||||
C:\> notepad myclient.json
|
||||
C:\> kcreg update myclient -f myclient.json
|
||||
----
|
||||
|
||||
|
||||
Another is to get current client, set or delete fields on it, and post it back all in one single step.
|
||||
|
||||
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 contains only changes to be applied so you don't have to specify too many values as arguments.
|
||||
In this case we specify `--merge` to tell `Client Registration CLI` that rather than treating mychanges.json as full
|
||||
new configuration, it should see 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`.
|
||||
|
||||
|
||||
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 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 using credentials of an account with 'manage-clients' permissions.
|
||||
|
||||
If you have permissions you can reissue a new Registration Access Token for the client, and have it printed to stdout or saved to a config
|
||||
file of your choice. If not you have to ask realm administrator to reissue a new Registration Access Token for your client, and send it
|
||||
to you. You can then use the token by passing 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.
|
||||
Loading…
Reference in a new issue