客户端注册 CLI

使用 CLI 自动化客户端注册

客户端注册 CLI 是一款命令行界面 (CLI) 工具，供应用程序开发人员在与 Keycloak 集成时以自助方式配置新的客户端。它专为与 Keycloak 客户端注册 REST 端点交互而设计。

任何应用程序都需要创建或获取客户端配置才能使用 Keycloak。通常，您需要为托管在唯一主机名上的每个新应用程序配置一个新的客户端。当应用程序与 Keycloak 交互时，应用程序会使用客户端 ID 来标识自身，以便 Keycloak 可以提供登录页面、单点登录 (SSO) 会话管理和其他服务。

您可以使用客户端注册 CLI 从命令行配置应用程序客户端，也可以在 shell 脚本中使用它。

要允许特定用户使用 `Client Registration CLI`，Keycloak 管理员通常使用管理控制台来配置具有适当角色的新用户，或配置新的客户端和客户端密钥以授予对客户端注册 REST API 的访问权限。

配置新用户以供客户端注册 CLI 使用

步骤

  1. 以 `admin` 身份登录管理控制台（例如，https://127.0.0.1:8080）。

  2. 选择要管理的 realm。

  3. 如果您想使用现有用户，请选择该用户进行编辑；否则，创建一个新用户。

  4. 选择**角色映射**、**分配角色**。在选项列表中，单击**按客户端筛选**。在搜索栏中，输入 `manage-clients`。选择该角色，如果您在主 realm 中，请选择具有 `NAME-realm` 的角色，其中 `NAME` 是目标 realm 的名称。您可以授予主 realm 中的用户对任何其他 realm 的访问权限。

  5. 单击**分配**以授予一整套客户端管理权限。另一个选择是选择 `view-clients` 以进行只读操作，或选择 `create-client` 以创建新客户端。

  6. 选择**可用角色**、**manage-client** 以授予一整套客户端管理权限。另一个选择是选择 `view-clients` 以进行只读操作，或选择 `create-client` 以创建新客户端。

    这些权限使用户能够在不使用初始访问令牌或注册访问令牌的情况下执行操作（有关详细信息，请参阅 客户端注册服务）。

可以不向用户分配任何 `realm-management` 角色。在这种情况下，用户仍然可以使用客户端注册 CLI 登录，但无法在没有初始访问令牌的情况下使用它。尝试在没有令牌的情况下执行任何操作会导致 **403 Forbidden** 错误。

管理员可以在管理控制台的“客户端”区域的“初始访问令牌”选项卡中签发初始访问令牌。

配置用于客户端注册 CLI 的客户端

默认情况下，服务器将客户端注册 CLI 识别为 `admin-cli` 客户端，该客户端是为每个新 realm 自动配置的。使用用户名登录时，无需进行其他客户端配置。

步骤

  1. 如果您想为客户端注册 CLI 使用单独的客户端配置，请创建一个客户端（例如，`reg-cli`）。

  2. 取消选中**标准流程已启用**。

  3. 通过将**客户端身份验证**切换到**打开**来增强安全性。

  4. 选择您要使用的帐户类型。

    1. 如果您想使用与客户端关联的服务帐户，请选中**服务帐户角色**。

    2. 如果您更喜欢使用普通用户帐户，请选中**直接访问授权**。

  5. 单击**下一步**。

  6. 单击**保存**。

  7. 单击**凭据**选项卡。

    配置 `Client Id and Secret` 或 `Signed JWT`。

  8. 如果您使用的是服务帐户角色，请单击**服务帐户角色**选项卡。

    选择角色以配置服务帐户的访问权限。有关要选择哪些角色的详细信息，请参阅 配置新用户以供客户端注册 CLI 使用。

  9. 单击**保存**。

运行 `kcreg config credentials` 时，使用 `--secret` 选项提供配置的密钥。

  • 运行 `kcreg config credentials` 时，指定要使用的 `clientId`（例如，`--client reg-cli`）。

  • 启用服务帐户后，您可以在运行 `kcreg config credentials` 时省略指定用户，只需提供客户端密钥或密钥库信息即可。

安装客户端注册 CLI

客户端注册 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 服务器分发版的目录。

使用客户端注册 CLI

步骤

  1. 使用您的凭据登录以启动经过身份验证的会话。

  2. 在 `Client Registration 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

      在生产环境中，必须使用 `https:` 访问 Keycloak，以避免将令牌暴露给网络嗅探器。

  3. 如果服务器的证书不是由 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

登录

步骤

  1. 使用客户端注册 CLI 登录时，请指定服务器端点 URL 和 realm。

  2. 指定用户名或客户端 ID，这会导致使用特殊的服务帐户。使用用户名时，必须使用指定用户的密码。使用客户端 ID 时，您使用客户端密钥或 `Signed JWT` 而不是密码。

无论采用哪种登录方法，登录的帐户都需要适当的权限才能执行客户端注册操作。请记住，非主 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 操作。

如果您有权限，可以为客户端颁发新的注册访问令牌，并将其打印到标准输出或保存到您选择的配置文件。否则，您必须要求领域管理员为您的客户端颁发新的注册访问令牌并将其发送给您。然后，您可以通过 --token 选项将其传递给任何 CRUD 命令。您也可以使用 kcreg config registration-token 命令将新令牌保存到配置文件中，并让客户端注册 CLI 从那时起自动为您处理它。

运行 kcreg update-token --help 命令以获取有关 kcreg update-token 命令的更多信息。

疑难解答

  • 问：登录时，我收到错误：**Parameter client_assertion_type is missing [invalid_client]**。

    答：此错误表示您的客户端已配置为使用 Signed JWT 令牌凭据，这意味着您在登录时必须使用 --keystore 参数。

在此页面上
编辑本指南