Merge pull request #45 from mstruk/cli-reg

Add Client Registration CLI documentation

SUMMARY.adoc

@@ -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]

topics/client-registration/client-registration-cli.adoc

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