使用 Keycloak 作为身份提供商，通过 LDAP 或 Active Directory 联合或本地管理账户来管理 IBM Bob 本地版的用户访问。

IBM Bob 本地版包含一个用于用户身份验证和访问管理的 Keycloak 身份提供商。用户可以从现有的 LDAP 或 Active Directory 环境联合，也可以直接在 Keycloak 中创建。无论以何种方式配置，用户必须分配适当的 Bob 角色才能访问该服务。

概述

概念	描述
身份提供商	Keycloak — 由 Bob Operator 部署和管理。
用户来源	用户可以直接在 Keycloak 中创建，也可以从 LDAP 或 Active Directory 服务联合。
身份验证	用户通过 Keycloak 使用 OpenID Connect（OIDC）进行身份验证。Keycloak 颁发一个短期授权码，由 `bob-authn` 换取 Bob bearer token。
授权	对 Bob 功能的访问由 Keycloak 中分配给用户的角色控制。
配置界面	LDAP 集成通过 `BobLDAP` 自定义资源和 `bobctl configure-idp` 命令管理。

支持的 LDAP 目录类型

Bob 本地版支持任何符合 LDAPv3 的目录服务。LDAP 配置中的 vendor 参数决定使用的 Keycloak 提供商模板，该模板定义所选目录类型的协议专属设置。

`vendor` 值	目录类型
`other`	OpenLDAP 及其他通用 LDAPv3 兼容目录服务
`ad`	Microsoft Active Directory
`rhds`	Red Hat Directory Server
`tivoli`	IBM Security Directory Server（前称 Tivoli Directory Server）
`edirectory`	NetIQ / Micro Focus eDirectory

身份验证和联合架构

当用户登录时，Bob 将请求传递给 Keycloak，由 Keycloak 处理身份验证。所有用户均通过 Keycloak 进行身份验证。LDAP 联合为可选项，仅在配置后才会激活。

已启用 LDAP 联合：Keycloak 直接对 LDAP 目录验证用户身份。用户密码保留在 LDAP 目录中，不存储在 Keycloak 中。

未启用 LDAP 联合：Keycloak 使用本地 Keycloak 用户存储对用户进行身份验证。

身份验证流程

用户输入凭证。

Keycloak 对用户进行身份验证。

Keycloak 颁发短期授权码。

bob-authn 将授权码换取 Bob bearer token。

所有后续 API 请求均使用 Bob 颁发的 token。

用户同步行为

Bob 本地版支持两种同步模式，通过 LDAP 配置中的 userSync.enabled 设置进行配置：

模式	`userSync.enabled`	行为
按需	`false`（默认）	仅当用户首次成功登录时，才将其导入 Keycloak，无需提前扫描目录。此选项适合目录条目非常多的环境。
预先同步（推荐）	`true`	注册 LDAP 提供商时，执行一次全量同步，将目录中的所有用户导入。初始导入后，Keycloak 每五分钟自动同步用户更新。此方式确保所有用户立即可用，通过 `adminEmails` 指定的管理员账户无需用户登录即可配置。

按需同步

对于不适合立即导入所有用户的超大型目录，请使用此模式。

首次身份验证尝试时：

用户被导入 Keycloak。

用户通过 SCIM 在 Bob 中完成配置。

由于配置延迟，第一次登录尝试会失败。

配置完成后，用户可成功登录。

预先同步

适用于大多数部署的推荐模式。同步完成后所有用户立即可用，无需登录即可完成配置。

注意：

同步间隔目前固定为 5 分钟。

使用 SCIM 同步用户

IBM Bob 本地版使用内嵌在 Keycloak 中的自定义 SCIM 2.0 插件，在 Keycloak 和 Bob 之间同步用户账户。Bob Operator 会自动配置此集成，无需额外配置。

用户同步的工作原理

当 Keycloak 中发生用户生命周期事件时，SCIM 插件会将相应事件发送给 bob-admin 服务。Bob 随后根据事件更新用户访问权限和个人信息。

此同步适用于 Keycloak 管理的所有用户，包括 LDAP 联合用户和直接在 Keycloak 管理控制台中创建的用户。

用户事件	Bob 操作
用户已创建或首次登录	为用户开通账户并授予 Bob 访问权限
用户已更新	同步个人信息变更
用户从 LDAP 中移除	撤销对 Bob 的访问权限，同时保留用户数据

注意：

从 LDAP 中删除用户会撤销其对 Bob 的访问权限，但不会删除其数据。如果该用户被重新添加到目录，访问权限将恢复，之前创建的工作也仍然可用。

验证同步

Bob 目前不提供确认 SCIM 同步处于活动状态的状态条件或健康检查。要验证配置是否正常工作，请创建或导入一个测试用户，并确认该用户在首次登录或初始 userSync 导入后出现在 Bob 中。

管理角色和群组成员资格

IBM Bob 使用 Keycloak 群组来控制用户角色。Bob Operator 会自动创建并维护所需的群组和角色映射。

Keycloak 群组	授予的 Keycloak 角色	添加对象
`bob-users`	`bob-user`	所有经过身份验证的用户在首次成功登录时通过 realm 的默认群组自动添加。
`bob-admins`	`bob-admin`	在 `BobLDAP` 配置的 `adminEmails` 字段中指定的用户，由 Operator 在每次协调周期中自动分配。

管理员访问权限

所有经过身份验证的用户均获得标准 Bob 访问权限。

授予管理员权限：

将用户的电子邮件地址添加到 IDP 配置文件的 adminEmails 中。

应用更改：./bobctl configure-idp --config my-idp.yaml

撤销管理员权限：

从 adminEmails 中移除该电子邮件地址。

重新应用配置。

重要：

bobctl configure-idp 是管理 Bob 管理员访问权限的唯一受支持方法。将电子邮件地址添加到 adminEmails 不会创建用户账户——该用户必须已通过 LDAP 联合或直接用户创建存在于 Keycloak 中。

管理 Keycloak

Bob 本地版包含提供身份和访问管理服务的 Keycloak 部署。Keycloak 管理与 Bob 管理是分离的，每个界面服务于不同的目的。

管理界面

界面	URL	用途
Keycloak 管理控制台	`https://bob-keycloak.<namespace>.<ingress-domain>`	管理 Keycloak 基础设施、用户、群组、身份提供商和联合设置。
Bob 管理 UI	`https://bob.<namespace>.<ingress-domain>/admin`	管理 Bob 用户、角色、邀请和租户专属设置。

Bob Operator 在安装期间自动创建这两条路由。

注意：

本版本的 Bob 管理 UI 中活动日志不可用。要访问服务日志，请直接从 OpenShift Container Platform 控制台或 CLI 查看身份验证服务、授权服务和管理服务的 Pod 日志。有关更多信息，请参阅已知限制。

访问 Keycloak 管理控制台

要在集群中查找 Keycloak 路由，请运行：

oc get route -n <instance-namespace> | grep keycloak

从集群 Secret 中检索初始管理员凭证：

oc get secret bob-keycloak-initial-admin \
  -n <instance-namespace> \
  -o jsonpath='{.data.username}' | base64 -d && echo

oc get secret bob-keycloak-initial-admin \
  -n <instance-namespace> \
  -o jsonpath='{.data.password}' | base64 -d && echo

警告：

请勿修改 bob-keycloak-initial-admin Secret。Bob Operator 在协调期间使用这些凭证。更改存储的凭证可能会中断 Operator 管理的功能。

如果你需要个人管理员账户，请使用初始管理员凭证登录，并在 master realm 中创建一个单独的用户，用于日常管理任务。

登录后，使用 Keycloak 控制台左上角的 realm 选择器切换到 bob realm。所有 Bob 用户、群组、身份提供商和联合提供商均从此 realm 管理。

了解 Keycloak Realm

Realm 是一个独立的管理域，包含自己的用户、凭证、角色、群组和身份提供商。

Bob 本地版使用两个 realm：

Realm	用途
master	保留用于 Keycloak 管理。此 realm 中的用户可以管理 Keycloak，但无法访问 Bob。
bob	包含所有 Bob 用户、群组、LDAP 联合提供商和应用客户端。Bob Operator 创建并管理此 realm。

两个 realm 完全独立。在一个 realm 中的成员资格或权限不会授予对另一个 realm 中资源的访问权限。

注意：

bob realm 由 Operator 管理。你可以通过 Keycloak 控制台直接进行更改，但 IBM 支持仅限于解决影响 Bob 身份验证和访问的问题。

管理 LDAP 联合提供商

通过 bobctl configure-idp 或 BobLDAP 自定义资源配置的 LDAP 联合提供商在 bob realm 的用户联合部分中可见。

Bob Operator 在创建 LDAP 提供商时注册它们。之后直接在 Keycloak 控制台中进行的更改不会同步回对应的 BobLDAP 自定义资源。

为保持一致的配置管理，请尽可能使用 BobLDAP 自定义资源和 bobctl configure-idp 命令。

安全注意事项

管理 Keycloak 时请遵循以下建议：

将对 bob-keycloak-initial-admin Secret 的访问权限限制为集群管理员。

在 bob realm 中执行 Bob 管理任务。

仅将 master realm 用于 Keycloak 基础设施管理。

除非明确需要且受支持，否则不要创建额外的 realm 或客户端。

通过 BobLDAP 资源管理 LDAP 联合，而不是直接在 Keycloak 控制台中编辑提供商设置。

将初始管理员账户视为紧急或引导账户，日常管理任务使用专用的个人管理员账户。

管理直接 Keycloak 用户

用户可以直接在 Keycloak 中创建和管理，无需集成 LDAP 目录。此方法适合概念验证环境、小规模部署，或没有 LDAP 服务器的安装场景。对于已使用企业目录服务的生产环境，推荐使用 LDAP 联合。

添加用户

要创建本地用户，请在 bob realm 的用户部分创建新用户账户。保存用户后，配置密码并分配适当的群组成员资格：

将用户添加到 bob-users 以授予标准访问权限。

将用户同时添加到 bob-users 和 bob-admins 以授予管理员访问权限。

管理密码

本地管理用户的密码通过 Keycloak 管理控制台进行管理。打开用户记录，使用凭证选项卡创建、更新或重置用户密码。

删除用户

要撤销用户的访问权限，请在 Keycloak 管理控制台中打开用户记录，然后删除或禁用该账户。被禁用的用户无法再进行身份验证，但其用户信息仍保留在系统中。

用户管理

概述