当前位置：首页 > news >正文

开源身份和访问管理方案之keycloak（二）管理员引导和恢复

news 来源：原创 2025/8/22 10:46:52

文章目录

开源身份和访问管理方案之keycloak（二）管理员引导和恢复
- 管理员引导和恢复
- - 在 Keycloak 启动时引导临时管理员帐户
  - 对于恢复丢失的管理员访问权限
  - - 使用专用命令引导管理员用户或服务帐户
    - 创建一个管理员用户
    - 创建一个服务账号
    - 重新获得对具有更高安全性的域的访问权限
  - Default values默认值
  - 环境变量

开源身份和访问管理方案之keycloak（二）管理员引导和恢复

管理员引导和恢复

官方原文链接：https://www.keycloak.org/server/bootstrap-admin-recovery

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

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

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

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

这些选项的目的仅用于引导临时管理员帐户。这些帐户仅在 master 域尚不存在时在 Keycloak 服务器的初始启动期间创建。这些帐户始终在 master 域中创建。对于恢复丢失的管理员访问权限，请使用以下各节中描述的专用命令。

对于恢复丢失的管理员访问权限

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

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

If you have built an optimized version of Keycloak with the build command as outlined in Configuring Keycloak, use the command line option --optimized to have Keycloak skip the build check for a faster startup time. When doing this, remove the build time options from the command line and keep only the runtime options.
如果您已经使用配置 Keycloak 中概述的 build 命令构建了 Keycloak 的优化版本，请使用命令行选项 --optimized 让 Keycloak 跳过构建检查，以加快启动时间。执行此操作时，请从命令行中删除构建时选项，仅保留运行时选项。

if you do not use --optimized keep in mind that an bootstrap-admin command will implicitly create or update an optimized image for you - if you are running the command from the same machine as a server instance, this may impact the next start of your server.
如果您不使用 --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

此命令使用客户端 ID tmpclient 创建一个临时管理员服务帐户，并从环境变量中检索密钥。

重新获得对具有更高安全性的域的访问权限

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

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

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

最后，检索到的 ID 可用于删除高级身份验证方法（在本例中为 OTP）：

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

Default values默认值

对于启动和专用命令场景，用户名和客户端 ID 均为可选项，用户和服务帐户的用户名和客户端 ID 均默认为 temp-admin。

环境变量

对于 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>

文章目录

开源身份和访问管理方案之keycloak（二）管理员引导和恢复

管理员引导和恢复

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

对于恢复丢失的管理员访问权限

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

创建一个管理员用户

创建一个服务账号

重新获得对具有更高安全性的域的访问权限

Default values默认值

环境变量

相关文章：