使用 BobIDP 自定义资源和 bobctl configure-idp 命令为 IBM Bob 本地版配置 LDAP 或 Active Directory 联合。

使用 bobctl configure-idp 将你的 LDAP 或 Active Directory 环境作为用户联合提供商连接到 Keycloak。你可以在安装期间完成此设置，也可以在部署后的任何时间进行配置。

开始之前

在配置 LDAP 联合之前，请确保满足以下要求：

OpenShift Container Platform（OCP）集群能够通过适当端口连接到 LDAP 服务器：

ldap:// 使用 389 端口
ldaps:// 使用 636 端口

具有目录读取权限的服务账户（绑定 DN）可用，或者 LDAP 服务器配置为允许匿名绑定。

如果使用带有私有或内部签名证书颁发机构（CA）的 ldaps://，请获取 PEM 格式的 LDAP 服务器 CA 证书。

bobctl 命令行工具已安装，并且 oc 已配置并通过对目标集群的身份验证。

配置文件参考

在注册 LDAP 提供商之前，请从提供的模板创建 IDP 配置文件。

cp config-idp-template.yaml my-idp.yaml

配置文件分为两个部分：适用于整个部署的顶级字段，以及可选的 ldaps 列表，其中每个条目描述一个 LDAP 联合提供商。

顶级字段

字段	是否必填	描述
`domains`	是	Bob 在登录时接受的电子邮件域列表。移除某个域将取消其注册；拥有该域的用户将无法登录。
`adminEmails`	否	要授予 Bob 管理员访问权限的用户电子邮件列表。Operator 会原子地更新 Keycloak `bob-admins` 群组和 Bob 管理员数据库。
`ldaps`	否	LDAP 联合提供商配置列表。对于仅使用直接 Keycloak 用户的部署，可完全省略。

必填字段（每个 LDAP 提供商条目）

字段	描述
`name`	LDAP 提供商的唯一描述性标识符。每个已配置的提供商必须有不同的名称。
`vendor`	指定要集成的 LDAP 目录类型。支持的值：`other`（OpenLDAP 和 LDAPv3 兼容）、`ad`（Microsoft Active Directory）、`rhds`（Red Hat Directory Server）、`tivoli`（IBM Security Directory Server）、`edirectory`（NetIQ eDirectory）。
`connectionUrl`	LDAP 服务器的完整 URL，包括协议（`ldap://` 或 `ldaps://`）、主机名和端口号。
`usersDn`	用户账户存储的目录位置，用户条目将从此处搜索和导入。
`usernameLDAPAttribute`	用户在身份验证时提供的用户名所对应的目录属性。
`rdnLDAPAttribute`	用于识别目录结构中条目的目录属性。在大多数配置中，这与 `usernameLDAPAttribute` 相同。
`uuidLDAPAttribute`	用于永久标识每个用户账户的唯一、稳定、不变的目录属性。
`userObjectClasses`	以逗号分隔的 LDAP 对象类列表，用于定义哪些目录条目被识别和处理为用户账户。

重要：

domains 字段是在本地版部署中配置基于域路由的唯一方式。请勿通过 Bob 管理用户界面配置域，因为这不是正确的方法，可能导致身份验证错误。

可选字段（每个 LDAP 提供商条目）

字段	描述
`bindDn`	用于身份验证和连接目录的服务账户 DN。如果目录允许匿名绑定访问，可以省略。
`bindPasswordSecret`	包含绑定账户密码的预先存在的 Secret 名称。必须在运行 `bobctl configure-idp` 之前在实例命名空间中创建。
`useTruststoreSpi`	指定何时使用 LDAP CA 证书进行服务器验证。值：`always`（默认，用于私有或内部颁发的 CA 证书）、`ldapsOnly`（用于公开受信任的 CA 证书）、`never`（通过不安全的 `ldap://` 连接时）。
`ldapsCACertSecret`	包含 PEM 格式 LDAP 服务器 CA 证书的预先存在的 Secret 名称。必须在运行 `bobctl configure-idp` 之前在实例命名空间中创建。
`searchScope`	确定目录搜索的深度。`2` 搜索所有子容器和子树（默认）；`1` 仅限于直接子条目的搜索。
`customUserSearchFilter`	应用于所有用户搜索操作的附加过滤器，例如用于排除服务账户或将搜索限制为特定用户类型。
`userSync.enabled`	设置为 `true` 时，初始配置提供商时会导入所有用户，后续目录更改每五分钟同步一次。推荐用于大多数部署。
`userAttributeMappings`	定义目录属性如何映射到 Bob 用户档案字段，例如 `email`、`firstName` 和 `lastName`。
`priority`	确定配置了多个提供商时的评估顺序。数值较低的提供商优先检查。默认值为 `0`。
`groupMapper`	将 LDAP 群组同步到 Keycloak。请参阅配置 LDAP 群组同步。

用户同步行为

当 userSync.enabled 设置为 true 时，Bob 在注册 LDAP 提供商时执行一次性的全量用户导入。初始导入完成后，后续用户生命周期同步通过 SCIM 自动处理。

提示：

对于大型 LDAP 目录，考虑将 userSync.enabled 设置为 false，让用户在首次登录时配置。这种方式可以缩短注册 LDAP 提供商所需的时间。

配置 LDAP 群组同步

使用可选的 groupMapper 配置将 LDAP 群组与 Keycloak 同步。通过群组同步，LDAP 目录中的用户和群组成员资格将通过 Keycloak 导入和管理。

groupsDn 参数为必填项。所有其他参数为可选项，可自定义以匹配你的 LDAP 目录 schema 和群组结构。

限制：

bob-admins 和 bob-users 群组是平台管理的群组，不包含在 LDAP 群组同步中。

参数	默认值	描述
`groupsDn`	必填	包含 LDAP 群组条目的基本可分辨名称（DN）。
`name`	`groups`	Keycloak 中群组映射器的显示名称。
`groupNameLdapAttribute`	`cn`	Keycloak 用作群组名称的 LDAP 属性。
`groupObjectClasses`	`groupOfNames`	标识群组条目的 LDAP 对象类。
`membershipLdapAttribute`	`member`	群组条目中包含成员信息的属性。
`membershipAttributeType`	`DN`	成员值的格式。支持的值：`DN`（可分辨名称）和 `UID`（用户 ID）。
`userRolesRetrieveStrategy`	`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	用于确定群组成员资格的方法。
`memberOfLdapAttribute`	`memberOf`	使用 `GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE` 时包含群组成员信息的用户属性。
`customGroupSearchFilter`	无	搜索群组时使用的附加 LDAP 过滤器。过滤器必须用括号括起来，例如 `(cn=dept-*)`。
`mode`	`LDAP_ONLY`	同步模式。支持的值：`LDAP_ONLY` 和 `READ_ONLY`。
`groupsPath`	`/`	在 Keycloak 群组层次结构中创建同步群组的位置。

群组成员资格检索策略

userRolesRetrieveStrategy 参数控制 Keycloak 如何识别用户的群组成员资格。

策略	描述
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	通过搜索包含用户引用的群组条目来检索群组成员资格。
`GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`	从用户的 `memberOf` 属性检索群组成员资格。
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY`	递归检索群组成员资格，包括 LDAP 目录支持的嵌套群组。

提示：

除非你的 LDAP 目录通过 memberOf 属性在用户条目中存储群组成员信息，或使用需要递归搜索的嵌套群组结构，否则请使用 LOAD_GROUPS_BY_MEMBER_ATTRIBUTE。

配置示例

# Bob 在登录时应接受的电子邮件域
domains:
  - corp.example.com

# 要授予 Bob 管理员访问权限的用户
adminEmails:
  - alice@corp.example.com

# LDAP 联合提供商
ldaps:
  - name: corp-ldap

    vendor: other
    connectionUrl: ldaps://ldap.corp.example.com:636
    usersDn: ou=People,dc=corp,dc=example,dc=com
    usernameLDAPAttribute: uid
    rdnLDAPAttribute: uid
    uuidLDAPAttribute: entryUUID
    userObjectClasses: inetOrgPerson,organizationalPerson,person

    bindDn: cn=bob-svc,ou=ServiceAccounts,dc=corp,dc=example,dc=com
    bindPasswordSecret: corp-ldap-bind

    useTruststoreSpi: always
    ldapsCACertSecret: corp-ldap-ca

    userSync:
      enabled: true

    userAttributeMappings:
      - ldapAttribute: mail
        userModelAttribute: email
      - ldapAttribute: givenName
        userModelAttribute: firstName
      - ldapAttribute: sn
        userModelAttribute: lastName

    # 可选：将 LDAP 群组同步到 Keycloak
    groupMapper:
      groupsDn: ou=Groups,dc=corp,dc=example,dc=com
      groupObjectClasses: groupOfNames
      membershipLdapAttribute: member

./bobctl configure-idp --config my-idp.yaml

在应用前验证 IDP 配置

在将 IDP 配置应用到集群之前，使用 --dry-run 选项验证配置并预览将要创建的资源。执行演习运行有助于在对集群进行任何更改之前识别常见的配置问题。

./bobctl configure-idp --config my-idp.yaml --dry-run

演习运行执行以下检查：

验证配置文件中是否存在所有必填配置参数。

显示将要创建或更新的 BobIDP 自定义资源的预览。

退出而不在集群中创建、修改或删除任何资源。

注意：

演习运行操作不会验证到 LDAP 服务器的网络连接、对目录验证提供的凭证，也不会确认集群中引用的 Secret 是否存在。这些验证仅在配置应用后执行，并反映在 LDAPReachable 和 LDAPAuthenticated 状态条件中。

应用配置

创建并验证 IDP 配置文件后，运行 configure-idp 命令将配置应用到集群。

./bobctl configure-idp --config my-idp.yaml

标志	是否必填	描述
`--config <file>`	是	指定 IDP 配置文件的路径。
`--dry-run`	否	验证配置并显示将要创建或更新的资源预览，不对集群应用任何更改。

命令运行时，bobctl 会等待 Operator 协调配置，并通过检查 BobIDP 自定义资源报告的状态条件来验证 IDP。

检查	确认内容
`Ready`	配置已成功应用。
`LDAPRegistered`	LDAP 提供商已在 Keycloak 中注册。
`LDAPReachable`	LDAP 服务器可从集群访问。
`LDAPAuthenticated`	配置的绑定凭证有效。
`LDAPUserSyncSucceeded`	初始用户导入已成功完成。仅在 `userSync.enabled` 设置为 `true` 时评估此条件。

默认验证超时为 600 秒（10 分钟）。在目录条目较多的环境中，初始用户同步可能需要几分钟完成。要增加超时，请设置 BOB_IDP_WAIT_TIMEOUT 环境变量：

BOB_IDP_WAIT_TIMEOUT=900 ./bobctl configure-idp --config my-idp.yaml

配置多个 LDAP 提供商

要集成来自多个 LDAP 或 Active Directory 源的用户，请在 IDP 配置文件的 ldaps 列表中将每个目录作为单独的条目添加，然后重新运行 configure-idp。

./bobctl configure-idp --config my-idp.yaml

检查 IDP 资源状态

查看 IDP 配置的状态：

oc get bobidp -n <instance-namespace>

查看详细配置和状态信息：

oc get bobidp bob-idp -n <instance-namespace> -o yaml

验证集成

bobctl configure-idp 成功完成后，验证 LDAP 集成是否正常工作。

检查 BobIDP 自定义资源的状态：

oc get bobidp bob-idp -n <instance-namespace> -o yaml

验证以下状态条件是否设置为 True：

条件	用途
`Ready`	确认配置已成功应用。
`LDAPRegistered`	确认 LDAP 提供商已在 Keycloak 中注册。
`LDAPReachable`	确认集群可以与 LDAP 服务器通信。
`LDAPAuthenticated`	确认配置的绑定凭证有效。
`LDAPUserSyncSucceeded`	确认所有用户已成功导入。仅在 `userSync.enabled: true` 时存在。

如果任何条件为 False，请查看相应的 message 字段以获取诊断详情。

使用联合 LDAP 目录中的凭证登录，以验证用户身份验证是否正常工作。

打开 Bob URL：

https://bob.<namespace>.<ingress-domain>

成功登录确认了连接性、身份验证、域路由、SCIM 配置和角色映射均正常工作。

用户首次登录后，确认用户记录在 Bob 中可用。

打开 Bob 管理 UI：

https://bob.<namespace>.<ingress-domain>/admin

以 Bob 管理员身份登录，并验证测试用户是否出现在用户列表中。

如果配置了 groupMapper 以将 LDAP 群组映射到 Bob 管理员：

使用属于已映射管理员群组的用户账户登录。
确认该用户可以访问 Bob 管理 UI。
验证管理员级别功能是否可用。

如果 userSync.enabled: true，则在注册 LDAP 提供商后自动导入用户。测试用户无需初始登录即可出现在 Bob 中。

如果用户在几分钟后仍未出现，请查看 bob-admin 日志以了解配置错误：

oc logs -n <instance-namespace> -l app=bob-admin --tail=100

查看任何已报告的 SCIM 相关错误，并在重试同步过程之前解决它们。

LDAP 集成

本页内容