管理员引导和恢复

了解如何引导和恢复管理员帐户。

临时管理员帐户

使用以下方法之一创建的用户或服务管理员帐户是临时的。这意味着该帐户应该只在执行获得永久性和更安全管理员访问权限所需的操作的持续时间内存在。之后,需要手动删除该帐户。各种UI/UX元素,如管理控制台警告横幅、标签和日志消息,将指示Keycloak管理员该帐户是临时的。

在Keycloak启动时引导临时管理员帐户

Keycloak startstart-dev 命令支持用于引导临时管理员用户和管理员服务帐户的选项。这些选项是标准配置选项,因此可以在任何 配置源(例如环境变量或CLI参数)中指定。例如,以下示例演示了如何使用 startstart-dev 命令以及CLI参数来分别引导临时管理员用户和管理员服务帐户

bin/kc.[sh|bat] start --bootstrap-admin-username tmpadm --bootstrap-admin-password pass
bin/kc.[sh|bat] start-dev --bootstrap-admin-client-id tmpadm --bootstrap-admin-client-secret secret

可以省略用户名或客户端ID值;有关详细信息,请参阅下面的 默认值 部分。

这些选项的目的是仅仅为了引导临时管理员帐户。这些帐户只会在Keycloak服务器首次启动时创建,此时主领域还不存在。这些帐户始终在主领域中创建。要恢复丢失的管理员访问权限,请使用下面部分中描述的专用命令。

使用专用命令引导管理员用户或服务帐户

即使在Keycloak首次启动之前,也可以执行 bootstrap-admin 命令。请记住,在使用此命令之前,所有Keycloak节点都需要停止。执行此命令将触发初始主领域的创建,因此,当服务器首次启动时,用于引导管理员用户和服务帐户的启动选项将被忽略。

此外,强烈建议使用与Keycloak服务器启动时相同的选项(例如,db 选项)来使用专用命令。

如果您已使用 配置Keycloak 中概述的 build 命令构建了优化的Keycloak版本,请使用命令行选项 --optimized 使Keycloak跳过构建检查以加快启动时间。这样做时,请从命令行中删除构建时间选项,只保留运行时选项。

如果您不使用 --optimized,请记住 bootstrap-admin 命令会隐式为您创建或更新优化的映像 - 如果您从与服务器实例相同的机器运行此命令,这可能会影响服务器的下次启动。

创建管理员用户

要创建临时管理员用户,请执行以下命令

bin/kc.[sh|bat] bootstrap-admin user

如果未指定其他参数和/或未设置相应的环境变量,则会提示用户输入所需信息。可以省略用户名值以使用默认值。有关详细信息,请参阅下面的 默认值环境变量 部分。

或者,可以在命令中直接指定参数

bin/kc.[sh|bat] bootstrap-admin user --username tmpadm --password:env PASS_VAR

此命令使用从环境变量检索的密码创建一个名为 tmpadm 的临时管理员用户。

创建服务帐户

在自动化场景中,临时管理员服务帐户可能是临时管理员用户的更合适替代方案。

要创建临时管理员服务帐户,请执行以下命令

bin/kc.[sh|bat] bootstrap-admin service

同样,如果未设置相应的环境变量或其他参数,则会提示用户输入所需信息。可以省略客户端ID值以使用默认值。有关详细信息,请参阅下面的 默认值环境变量 部分。

或者,可以在命令中直接指定参数

bin/kc.[sh|bat] bootstrap-admin service --client-id tmpclient --client-secret:env=SECRET_VAR

此命令使用从环境变量检索的密钥创建一个名为 tmpclient 的临时管理员服务帐户。

重新获得对领域的访问权限,并提高安全性

对于管理员访问权限丢失的领域,可以强制执行无密码、OTP或其他高级身份验证方法。在这种情况下,需要创建管理员服务帐户才能恢复对领域的管理员访问权限。创建服务帐户后,需要针对Keycloak实例进行身份验证才能执行所有必要操作

bin/kcadm.[sh|bat] config credentials --server http://127.0.0.1:8080 --realm master --client <service_account_client_name> --secret <service_account_secret>

接下来,检索 credentialId。对于本例,OTP凭据是相关的。使用以下命令获取 CredentialRepresentation 对象数组,并找到 type 设置为 otp 的对象

bin/kcadm.[sh|bat] get users/{userId}/credentials -r {realm}

最后,可以使用检索到的ID删除高级身份验证方法(在本例中为OTP)

bin/kcadm.[sh|bat] delete users/{userId}/credentials/{credentialId} -r {realm}

默认值

对于启动和专用命令场景,用户名和客户端ID都是可选的,并且分别默认为用户和服务帐户的 temp-admin

禁用参数提示

要禁用参数提示,可以使用 --no-prompt 参数。例如

bin/kc.[sh|bat] bootstrap-admin user --username tmpadm --no-prompt

如果未设置相应的环境变量,则命令将失败并显示一条错误消息,指示缺少所需的密码参数。

如果应省略用户名或客户端ID,则 --no-prompt 参数很有用。例如

bin/kc.[sh|bat] bootstrap-admin user --password:env PASS_VAR --no-prompt

这将创建一个具有默认用户名的临时管理员用户,而无需提示确认。有关详细信息,请参阅上面的 默认值 部分。

环境变量

对于 bootstrap-admin user 命令,用户名和密码都可以可选地设置为环境变量

bin/kc.[sh|bat] bootstrap-admin user --username:env <YourUsernameEnv> --password:env <YourPassEnv>

对于 bootstrap-admin service 命令,客户端ID是可选的,默认为 temp-admin,而客户端密钥需要设置为环境变量

bin/kc.[sh|bat] bootstrap-admin service --client-id:env <YourClientIdEnv> --client-secret:env <YourSecretEnv>
在本页