Admin 引导和恢复 - Keycloak

临时管理员帐户

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

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

Keycloak start 和 start-dev 命令支持引导临时管理员用户和管理员服务帐户的选项。这些选项是标准配置选项，因此可以在任何配置源中指定，例如环境变量或 CLI 参数。例如，以下示例演示了如何将 start 和 start-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 服务器首次启动且 master 域尚不存在时创建。这些帐户始终在 master 域中创建。要恢复丢失的管理员访问权限，请使用以下部分中描述的专用命令。

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

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

此外，强烈建议使用与 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

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

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

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

bin/kcadm.[sh|bat] config credentials --server https://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-name}

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

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

禁用参数提示

要禁用参数提示，可以使用 --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>