libre.sh/keycloak-scim
2
0
Fork 0
Code Issues 14 Pull requests Releases Packages Activity Actions 6
keycloak-scim/docs/guides/securing-apps/client-registration-cli.adoc
rmartinc 942d5d0aa3 Convert chapter planning for securing applications and services to guides 
Final removal of the securing_apps documentation
Final checks for links, order and other minor things
Closes #31328

Signed-off-by: rmartinc <rmartinc@redhat.com>
2024-08-01 16:45:56 +02:00

386 lines
17 KiB
Text
Raw Blame History

<#import "/templates/guide.adoc" as tmpl>
<#import "/templates/links.adoc" as links>
<@tmpl.guide
title="Client registration CLI"
priority=110
summary="Automating Client Registration with the 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 {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.
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 {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.
[[_configuring_a_user_for_client_registration_cli]]
== Configuring a new regular user for use with Client Registration CLI
.Procedure
. Log in to the Admin Console (for example, http://localhost:8080) 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 Mapping*, *Assign role*. From the option list, click *Filter by clients*. In the search bar, type `manage-clients`. Select the role, or if you are in the master realm, select the one with *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.
. Click *Assign* 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.
. 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 (see <@links.securingapps id="client-registration" anchor="_authentication" /> for more information).
====
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 in the Clients area on the *Initial Access Token* tab.
[[_configuring_a_client_for_use_with_client_registration_cli]]
== Configuring a client for use with the Client Registration CLI
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.
.Procedure
. Create a client (for example, [filename]`reg-cli`) if you want to use a separate client configuration for the Client Registration CLI.
. Uncheck *Standard Flow Enabled*.
. Strengthen the security by toggling *Client authentication* to *On*.
. Choose the type of account that you want to use.
.. If you want to use a service account associated with the client, check *Service accounts roles*.
.. If you prefer to use a regular user account, check *Direct access grants*.
. Click *Next*.
. Click *Save*.
. Click the *Credentials* tab.
+
Configure either [filename]`Client Id and Secret` or [filename]`Signed JWT`.
. If you are using service account roles, click the *Service Account Roles* tab.
+
Select the roles to configure the access for the service account. For the details on what roles to select, see <<_configuring_a_user_for_client_registration_cli>>.
. Click *Save*.
When you run the [command]`kcreg config credentials`, use the [command]`--secret` option to supply the configured secret.
* Specify which [filename]`clientId` to use (for example, [command]`--client reg-cli`) when running [command]`kcreg config credentials`.
* 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.
[[_installing_client_registration_cli]]
== Installing the Client Registration CLI
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`.
Add the {project_name} server directory to your [filename]`PATH` when setting up the client for use from any location on the file system.
For example, on:
* Linux:
[options="npwrap"]
----
$ export PATH=$PATH:$KEYCLOAK_HOME/bin
$ kcreg.sh
----
* Windows:
[options="npwrap"]
----
c:\> set PATH=%PATH%;%KEYCLOAK_HOME%\bin
c:\> kcreg
----
[filename]`KEYCLOAK_HOME` refers to a directory where the {project_name} Server distribution was unpacked.
[[_using_client_registration_cli]]
== Using the Client Registration CLI
.Procedure
. Start an authenticated session by logging in with your credentials.
. Run commands on the [filename]`Client Registration REST` endpoint.
+
For example, on:
* Linux:
+
[options="npwrap",subs="attributes+"]
----
$ kcreg.sh config credentials --server http://localhost:8080 --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:
+
[options="npwrap",subs="attributes+"]
----
c:\> kcreg config credentials --server http://localhost:8080 --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, {project_name} has to be accessed with [filename]`https:` to avoid exposing tokens to network sniffers.
====
. 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.
+
For example, on:
* Linux:
+
[options="npwrap"]
----
$ kcreg.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks
----
* Windows:
+
[options="npwrap"]
----
c:\> kcreg config truststore --trustpass %PASSWORD% %HOMEPATH%\.keycloak\truststore.jks
----
[[_logging_in]]
=== Logging in
.Procedure
. Specify a server endpoint URL and a realm when you log in with the Client Registration CLI.
. 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.
See the built-in help for more information on using the Client Registration CLI.
For example, on:
* Linux:
[options="nowrap"]
----
$ kcreg.sh help
----
* Windows:
[options="nowrap"]
----
c:\> kcreg help
----
See [filename]`kcreg config credentials --help` for more information about starting an authenticated session.
[[_working_with_alternative_configurations]]
=== Working with alternative configurations
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 maintain 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 [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.
[[_initial_access_and_registration_access_tokens]]
=== Initial Access and Registration Access Tokens
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.
For example, on:
* Linux:
[options="nowrap"]
----
$ kcreg.sh config initial-token $TOKEN
$ kcreg.sh create -s clientId=myclient
----
or
[options="nowrap"]
----
$ kcreg.sh create -s clientId=myclient -t $TOKEN
----
* Windows:
[options="nowrap"]
----
c:\> kcreg config initial-token %TOKEN%
c:\> kcreg create -s clientId=myclient
----
or
[options="nowrap"]
----
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 <@links.securingapps id="client-registration" anchor="_authentication" /> for more information about Initial Access and Registration Access Tokens.
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.
[[_performing_crud_operations]]
=== 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:
[options="nowrap"]
----
$ kcreg.sh create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s 'redirectUris=["/myclient/*"]' -o
----
* Windows:
[options="nowrap"]
----
C:\> kcreg create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s "redirectUris=[\"/myclient/*\"]" -o
----
Run the [command]`kcreg create --help` for more information about the [command]`kcreg create` command.
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
template and should not specify them as arguments to the [command]`kcreg create` command.
=== Retrieving a client configuration
You can retrieve an existing client by using the [command]`kcreg get` command.
For example, on:
* Linux:
[options="nowrap"]
----
$ kcreg.sh get myclient
----
* Windows:
[options="nowrap"]
----
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:
[options="nowrap"]
----
$ kcreg.sh get myclient -e install > keycloak.json
----
* Windows:
[options="nowrap"]
----
C:\> kcreg get myclient -e install > keycloak.json
----
Run the [command]`kcreg get --help` command for more information about the [command]`kcreg get` command.
=== 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:
[options="nowrap"]
----
$ kcreg.sh get myclient > myclient.json
$ vi myclient.json
$ kcreg.sh update myclient -f myclient.json
----
* Windows:
[options="nowrap"]
----
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:
[options="nowrap"]
----
$ kcreg.sh update myclient -s enabled=false -d redirectUris
----
* Windows:
[options="nowrap"]
----
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 [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.
For example, on:
* Linux:
[options="nowrap"]
----
$ kcreg.sh update myclient --merge -d redirectUris -f mychanges.json
----
* Windows:
[options="nowrap"]
----
C:\> kcreg update myclient --merge -d redirectUris -f mychanges.json
----
Run the [command]`kcreg update --help` command for more information about the [command]`kcreg update` command.
=== Deleting a client configuration
Use the following example to delete a client.
* Linux:
[options="nowrap"]
----
$ kcreg.sh delete myclient
----
* Windows:
[options="nowrap"]
----
C:\> kcreg delete myclient
----
Run the [command]`kcreg delete --help` command for more information about the [command]`kcreg delete` command.
[[_refreshing_invalid_registration_access_tokens]]
=== Refreshing invalid Registration Access Tokens
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.
Run the [command]`kcreg update-token --help` command for more information about the [command]`kcreg update-token` command.
[[_troubleshooting_2]]
== 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 [filename]`Signed JWT` token credentials, which means you have to use the [command]`--keystore` parameter when logging in.
</@tmpl.guide>
Reference in a new issue View git blame Copy permalink