6.4. 使用客户端注册 CLI
流程
- 使用您的凭证登录,启动经过身份验证的会话。
在
客户端注册 REST 端点上
运行命令。例如,在:
linux:
$ 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:
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
注意在生产环境中,红帽构建的 Keycloak 必须通过
https:
访问,以避免向网络嗅探器公开令牌。
如果服务器的证书不是由 Java 默认证书信任存储中包含的可信证书颁发机构(CA)发布,请准备
信任存储.jks
文件并指示客户端注册 CLI 使用它。例如,在:
linux:
$ kcreg.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks
Windows:
c:\> kcreg config truststore --trustpass %PASSWORD% %HOMEPATH%\.keycloak\truststore.jks
6.4.1. 登录
流程
- 使用客户端注册 CLI 登录时指定服务器端点 URL 和域。
-
指定用户名或客户端 id,这会导致使用特殊服务帐户。使用用户名时,您必须为指定用户使用密码。在使用客户端 ID 时,您可以使用客户端 secret 或
Signed JWT
而不是密码。
无论登录方法如何,登录的帐户都需要适当的权限才能执行客户端注册操作。请记住,非 master 域中的任何帐户都只能具有在同一域中管理客户端的权限。如果您需要管理不同的域,您可以在不同的域中配置多个用户,也可以在 master
域中创建一个用户,并在不同的域中添加管理客户端的角色。
您不能使用客户端注册 CLI 配置用户。使用 Admin Console Web 界面或 Admin Client CLI 配置用户。如需了解更多详细信息,请参阅 服务器管理指南。
当 kcreg
成功登录时,它会接收授权令牌并将其保存在私有配置文件中,以便令牌可用于后续调用。有关配置文件的详情,请参考 第 6.4.2 节 “使用其他配置”。
有关使用客户端注册 CLI 的更多信息,请参阅内置帮助。
例如,在:
- linux:
$ kcreg.sh help
- Windows:
c:\> kcreg help
有关启动经过身份验证的会话的更多信息,请参阅 kcreg config credentials --help
。
6.4.2. 使用其他配置
默认情况下,客户端注册 CLI 会在用户的主目录下自动维护一个配置文件 ./.keycloak/kcreg.config
。您可以使用 --config
选项指向不同的文件或位置,以并行维护多个经过身份验证的会话。从单个线程执行绑定到单个配置文件的操作是安全的。
不要使配置文件对系统上的其他用户可见。配置文件包含应保持私有的访问令牌和 secret。
您可能希望通过将 --no-config
选项与所有命令搭配使用,避免将 secret 存储在配置文件中,即使它不太方便,且需要更多令牌请求来执行此操作。使用每个 kcreg
调用指定所有身份验证信息。
6.4.3. 初始访问和注册访问令牌
在 Red Hat build of Keycloak 服务器中没有配置帐户的开发人员可以使用 Client Registration CLI。只有当域管理员向开发人员发出 Initial Access Token 时,才能实现。域管理员最多可决定如何以及何时发布这些令牌。域管理员可以限制 Initial Access Token 的最长期限以及可在其中创建的客户端总数。
开发人员有初始访问令牌后,开发人员可以使用它来创建新客户端,而无需通过 kcreg 配置凭据进行身份验证
。Initial Access Token 可以存储在配置文件中,也可以作为 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 配置令牌的更多信息。
6.4.4. 创建客户端配置
使用凭证或配置 Initial Access Token 进行身份验证后,第一项任务通常是创建新客户端。通常,您可能希望将准备好的 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
命令的参数。
6.4.5. 检索客户端配置
您可以使用 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
命令的更多信息。
6.4.6. 修改客户端配置
可以通过两种方法更新客户端配置。
一种方法是在获取当前配置后向服务器提交完整的新状态,将其保存到文件,编辑该文件,并将它重新发布到服务器。
例如,在:
- 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
命令的更多信息。
6.4.7. 删除客户端配置
使用以下示例删除客户端。
- linux:
$ kcreg.sh delete myclient
- Windows:
C:\> kcreg delete myclient
运行 kcreg delete --help
命令以了解有关 kcreg delete
命令的更多信息。
6.4.8. 刷新无效的注册访问令牌
使用 --no-config
模式执行创建、读取、更新和删除(CRUD)操作时,客户端注册 CLI 无法为您处理注册访问令牌。在这种情况下,可能会丢失客户端最近发布的注册访问令牌的跟踪,这样就无法在该客户端上执行进一步的 CRUD 操作,而无需使用具有 管理客户端 权限的帐户进行身份验证。
如果您有权限,您可以为客户端发布新的注册访问令牌,并将其打印到标准输出或保存到您选择的配置文件中。否则,您必须要求域管理员为您的客户端发布新的注册访问令牌,并将其发送给您。然后,您可以通过 --token
选项将其传递给任何 CRUD 命令。您还可以使用 kcreg config registration-token
命令将新令牌保存到配置文件中,并让客户端注册 CLI 会自动处理它。
运行 kcreg update-token --help
命令以了解有关 kcreg update-token
命令的更多信息。