$ export PATH=$PATH:$KEYCLOAK_HOME/bin $ kcreg.sh
客户端注册 CLI 是一个命令行界面 (CLI) 工具，供应用程序开发人员在与 Keycloak 集成时以自助服务方式配置新客户端。它专门设计用于与 Keycloak 客户端注册 REST 端点交互。
任何应用程序要使用 Keycloak，都必须创建或获取客户端配置。通常，您为托管在唯一主机名上的每个新应用程序配置一个新客户端。当应用程序与 Keycloak 交互时，应用程序使用客户端 ID 标识自己，以便 Keycloak 可以提供登录页面、单点登录 (SSO) 会话管理和其他服务。
您可以使用客户端注册 CLI 从命令行配置应用程序客户端，并且可以在 shell 脚本中使用它。
为了允许特定用户使用 Client Registration CLI，Keycloak 管理员通常使用管理控制台配置具有适当角色的新用户，或者配置新的客户端和客户端密钥以授予对客户端注册 REST API 的访问权限。
以 admin 身份登录到管理控制台（例如，https://127.0.0.1:8080）。
选择要管理的 realm。
如果您想使用现有用户，请选择该用户进行编辑；否则，创建一个新用户。
选择 角色映射，分配角色。 从选项列表中，单击 按客户端过滤。 在搜索栏中，键入 manage-clients。 选择角色，或者如果您在 master realm 中，请选择带有 NAME-realm 的角色，其中 NAME 是目标 realm 的名称。 您可以向 master realm 中的用户授予对任何其他 realm 的访问权限。
单击 分配 以授予完整的客户端管理权限集。 另一个选项是选择 view-clients 进行只读访问，或选择 create-client 来创建新客户端。
选择 可用角色，manage-client 以授予完整的客户端管理权限集。 另一个选项是选择 view-clients 进行只读访问，或选择 create-client 来创建新客户端。
|
这些权限授予用户执行操作的能力，而无需使用初始访问令牌或注册访问令牌（有关更多信息，请参阅 客户端注册服务）。 |
可以不向用户分配任何 realm-management 角色。 在这种情况下，用户仍然可以使用客户端注册 CLI 登录，但没有初始访问令牌就无法使用它。 尝试在没有令牌的情况下执行任何操作都会导致 403 Forbidden 错误。
管理员可以从管理控制台的客户端区域中的 初始访问令牌 选项卡中颁发初始访问令牌。
默认情况下，服务器将客户端注册 CLI 识别为 admin-cli 客户端，该客户端是为每个新 realm 自动配置的。 使用用户名登录时，无需额外的客户端配置。
如果您想为客户端注册 CLI 使用单独的客户端配置，请创建一个客户端（例如，reg-cli）。
取消选中 启用标准流程。
通过将 客户端身份验证 切换为 启用 来加强安全性。
选择您要使用的帐户类型。
如果您想使用与客户端关联的服务帐户，请选中 服务帐户角色。
如果您喜欢使用普通用户帐户，请选中 直接访问授权。
单击 下一步。
单击 保存。
单击 凭据 选项卡。
配置 客户端 ID 和密钥 或 签名 JWT。
如果您使用服务帐户角色，请单击 服务帐户角色 选项卡。
选择角色以配置服务帐户的访问权限。 有关选择哪些角色的详细信息，请参阅 配置新普通用户以使用客户端注册 CLI。
单击 保存。
当您运行 kcreg config credentials 时，使用 --secret 选项提供配置的密钥。
运行 kcreg config credentials 时，指定要使用的 clientId（例如，--client reg-cli）。
启用服务帐户后，您可以在运行 kcreg config credentials 时省略指定用户，而只需提供客户端密钥或密钥库信息。
客户端注册 CLI 打包在 Keycloak 服务器发行版中。 您可以在 bin 目录中找到执行脚本。 Linux 脚本名为 kcreg.sh，Windows 脚本名为 kcreg.bat。
在设置客户端以便从文件系统上的任何位置使用时，将 Keycloak 服务器目录添加到您的 PATH。
例如，在
Linux
$ export PATH=$PATH:$KEYCLOAK_HOME/bin $ kcreg.sh
Windows
c:\> set PATH=%PATH%;%KEYCLOAK_HOME%\bin c:\> kcreg
KEYCLOAK_HOME 指的是解压缩 Keycloak 服务器发行版的目录。
通过使用您的凭据登录来启动经过身份验证的会话。
在 客户端注册 REST 端点上运行命令。
例如，在
Linux
$ kcreg.sh config credentials --server https://127.0.0.1:8080 --realm demo --user user --client reg-cli $ kcreg.sh create -s clientId=my_client -s 'redirectUris=["https://127.0.0.1:8980/myapp/*"]' $ kcreg.sh get my_client
Windows
c:\> kcreg config credentials --server https://127.0.0.1:8080 --realm demo --user user --client reg-cli c:\> kcreg create -s clientId=my_client -s "redirectUris=[\"https://127.0.0.1:8980/myapp/*\"]" c:\> kcreg get my_client
|
在生产环境中，必须使用 |
如果服务器的证书不是由 Java 默认证书信任存储库中包含的受信任证书颁发机构 (CA) 之一颁发的，请准备一个 truststore.jks 文件并指示客户端注册 CLI 使用它。
例如，在
Linux
$ kcreg.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks
Windows
c:\> kcreg config truststore --trustpass %PASSWORD% %HOMEPATH%\.keycloak\truststore.jks
当您使用客户端注册 CLI 登录时，请指定服务器端点 URL 和 realm。
指定用户名或客户端 ID，这将导致使用特殊的服务器帐户。 使用用户名时，您必须使用指定用户的密码。 使用客户端 ID 时，您可以使用客户端密钥或 签名 JWT 而不是密码。
无论登录方法如何，登录的帐户都需要适当的权限才能执行客户端注册操作。 请记住，非 master realm 中的任何帐户只能拥有在同一 realm 内管理客户端的权限。 如果您需要管理不同的 realm，您可以配置不同 realm 中的多个用户，或者您可以在 master realm 中创建一个用户并添加用于管理不同 realm 中客户端的角色。
您无法使用客户端注册 CLI 配置用户。 使用管理控制台 Web 界面或管理客户端 CLI 配置用户。 有关更多详细信息，请参阅 服务器管理指南。
当 kcreg 成功登录时，它会接收授权令牌并将它们保存在私有配置文件中，以便令牌可以用于后续调用。 有关配置文件的更多信息，请参阅 使用备用配置。
有关使用客户端注册 CLI 的更多信息，请参阅内置帮助。
例如，在
Linux
$ kcreg.sh help
Windows
c:\> kcreg help
有关启动经过身份验证的会话的更多信息，请参阅 kcreg config credentials --help。
默认情况下，客户端注册 CLI 会自动在用户主目录下的默认位置 ./.keycloak/kcreg.config 维护一个配置文件。 您可以使用 --config 选项指向不同的文件或位置，以并行维护多个经过身份验证的会话。 这是从单个线程执行绑定到单个配置文件的操作的最安全方法。
|
不要使配置文件对系统上的其他用户可见。 配置文件包含应保密的访问令牌和密钥。 |
您可能希望通过将 --no-config 选项与您的所有命令一起使用来避免将密钥存储在配置文件中，即使这样做不太方便并且需要更多的令牌请求。 在每次 kcreg 调用中指定所有身份验证信息。
没有在他们想要使用的 Keycloak 服务器上配置帐户的开发人员可以使用客户端注册 CLI。 这只有在 realm 管理员向开发人员颁发初始访问令牌时才有可能。 由 realm 管理员决定如何以及何时颁发和分发这些令牌。 realm 管理员可以限制初始访问令牌的最大有效期以及可以使用它创建的客户端总数。
一旦开发人员拥有初始访问令牌，开发人员就可以使用它来创建新客户端，而无需使用 kcreg config credentials 进行身份验证。 初始访问令牌可以存储在配置文件中，也可以指定为 kcreg create 命令的一部分。
例如，在
Linux
$ kcreg.sh config initial-token $TOKEN $ kcreg.sh create -s clientId=myclient
或
$ kcreg.sh create -s clientId=myclient -t $TOKEN
Windows
c:\> kcreg config initial-token %TOKEN% c:\> kcreg create -s clientId=myclient
或
c:\> kcreg create -s clientId=myclient -t %TOKEN%
使用初始访问令牌时，服务器响应包括新颁发的注册访问令牌。 对该客户端的任何后续操作都需要通过使用该令牌进行身份验证来执行，该令牌仅对该客户端有效。
客户端注册 CLI 自动使用其私有配置文件来保存和使用此令牌及其关联的客户端。 只要相同的配置文件用于所有客户端操作，开发人员就不需要进行身份验证即可读取、更新或删除以这种方式创建的客户端。
有关初始访问令牌和注册访问令牌的更多信息，请参阅 客户端注册服务。
运行 kcreg config initial-token --help 和 kcreg config registration-token --help 命令，以获取有关如何使用客户端注册 CLI 配置令牌的更多信息。
使用凭据进行身份验证或配置初始访问令牌后的首要任务通常是创建新客户端。 通常，您可能希望使用准备好的 JSON 文件作为模板，并设置或覆盖某些属性。
以下示例演示了如何读取 JSON 文件，覆盖它可能包含的任何客户端 ID，设置任何其他属性，并在成功创建后将配置打印到标准输出。
Linux
$ kcreg.sh create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s 'redirectUris=["/myclient/*"]' -o
Windows
C:\> kcreg create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s "redirectUris=[\"/myclient/*\"]" -o
运行 kcreg create --help 以获取有关 kcreg create 命令的更多信息。
您可以使用 kcreg attrs 列出可用属性。 请记住，许多配置属性未检查有效性或一致性。 由您来指定正确的值。 请记住，您的模板中不应有任何 id 字段，并且不应将它们指定为 kcreg create 命令的参数。
您可以使用 kcreg get 命令检索现有客户端。
例如，在
Linux
$ kcreg.sh get myclient
Windows
C:\> kcreg get myclient
您还可以将客户端配置作为适配器配置文件检索，您可以将其与您的 Web 应用程序打包在一起。
例如，在
Linux
$ kcreg.sh get myclient -e install > keycloak.json
Windows
C:\> kcreg get myclient -e install > keycloak.json
运行 kcreg get --help 命令以获取有关 kcreg get 命令的更多信息。
有两种方法可以更新客户端配置。
一种方法是在获取当前配置后，将完整的新状态提交到服务器，将其保存到文件，对其进行编辑，然后将其发布回服务器。
例如，在
Linux
$ kcreg.sh get myclient > myclient.json $ vi myclient.json $ kcreg.sh update myclient -f myclient.json
Windows
C:\> kcreg get myclient > myclient.json C:\> notepad myclient.json C:\> kcreg update myclient -f myclient.json
第二种方法是获取当前客户端，在其上设置或删除字段，然后一步将其发布回去。
例如，在
Linux
$ kcreg.sh update myclient -s enabled=false -d redirectUris
Windows
C:\> kcreg update myclient -s enabled=false -d redirectUris
您还可以使用仅包含要应用的更改的文件，这样您就不必将太多值指定为参数。 在这种情况下，指定 --merge 以告诉客户端注册 CLI，它应该将 JSON 文件视为要应用于现有配置的一组属性，而不是将其视为完整的、新的配置。
例如，在
Linux
$ kcreg.sh update myclient --merge -d redirectUris -f mychanges.json
Windows
C:\> kcreg update myclient --merge -d redirectUris -f mychanges.json
运行 kcreg update --help 命令以获取有关 kcreg update 命令的更多信息。
使用以下示例删除客户端。
Linux
$ kcreg.sh delete myclient
Windows
C:\> kcreg delete myclient
运行 kcreg delete --help 命令以获取有关 kcreg delete 命令的更多信息。
当使用 --no-config 模式执行创建、读取、更新和删除 (CRUD) 操作时，客户端注册 CLI 无法为您处理注册访问令牌。 在这种情况下，可能会丢失对客户端最近颁发的注册访问令牌的跟踪，这使得在没有具有 manage-clients 权限的帐户进行身份验证的情况下，无法对该客户端执行任何进一步的 CRUD 操作。
如果您有权限，您可以为客户端颁发新的注册访问令牌，并将其打印到标准输出或保存到您选择的配置文件中。 否则，您必须请求 realm 管理员为您的客户端颁发新的注册访问令牌并将其发送给您。 然后，您可以通过 --token 选项将其传递给任何 CRUD 命令。 您还可以使用 kcreg config registration-token 命令将新令牌保存在配置文件中，并让客户端注册 CLI 从那时起自动为您处理它。
运行 kcreg update-token --help 命令以获取有关 kcreg update-token 命令的更多信息。