LDAP 管理

ACP 可以使用 LDAP 目录对用户进行身份验证，并可选择性地同步目录组。控制台工作流支持常见的 OpenLDAP 和 Microsoft Active Directory 布局。

只有在以下所有检查都通过后，集成才算完成：

ACP 创建了 LDAP IDP。
预期的用户以及（如果启用）组已完成同步。
一个具有代表性的目录用户可以登录并获得预期的 ACP 角色。

本指南从最短的控制台工作流开始。如果目录管理员尚未提供 Base DN、Filter 或属性映射，请先使用 Discover the Directory Settings。

开始之前

在配置 ACP 之前，请准备以下值：

可从 ACP 集群访问的 LDAP server 主机名和端口。
具有目标用户和组只读权限的 Bind DN 和密码。
User Base DN 和 user Filter。
一个稳定、唯一且非空的用户身份属性。
一个或多个登录属性。
可选的 group Base DN、group Filter、member attribute、user matching attribute 和 group name attribute。
一个具有代表性的用户账户，用于最终登录验证。

从工程师的 laptop 上成功查询，并不能证明 ACP 可以连接。ACP Connector 的创建和同步才是集群侧的检查。如果目录管理员已经提供并验证了所有必需值，请继续阅读 Add LDAP。

Discover the Directory Settings

当 Base DN、Filter 或属性映射未知时，请使用此工作流。这里引用的命令行工具是外部集成前诊断工具，不是 ACP 功能。

1. 从正确的网络运行检查

尽可能从一个诊断主机或 Pod 上运行目录查询，其 DNS、路由、防火墙和证书信任与 ACP 集群一致。laptop 查询可作为有用的初步证据，但 ACP Connector 的创建和同步仍是权威的集群侧检查。

2. 查找目录根

查询目录 Root DSE 并记录 naming root：

OpenLDAP 和兼容目录通常会发布 namingContexts。
Active Directory 会发布 defaultNamingContext。

请使用最终 On-Site Diagnostic Tools 部分中的 Root DSE 示例。返回值（例如 dc=example,dc=com）是定位用户和组分支的起点；它不一定自动就是最佳的 User Base DN。

3. 选择 User 和 Group 的 Base DN

将 Base DN 视为 ACP 搜索的下界。例如：

dc=example,dc=com
|- ou=People
|  |- ou=Engineering
|  `- ou=Operations
`- ou=Groups

如果所有目标用户都位于 ou=People,dc=example,dc=com 下，请将其作为 User Base DN。
如果目标用户分布在 ou=People 之外的多个分支，请使用它们的最近公共父节点。
如果组存放在 ou=Groups 下，请使用单独的 Group Base DN。

在运行 subtree 查询之前，请先使用外部 base-scope 查询确认 bind 账户可以读取候选 Base DN。ACP 表单会在配置的 Base DN 下面执行 subtree 搜索，但不会暴露 Search Scope 字段。YAML 可以使用 scope: sub 或 scope: one；在当前 Connector 运行时中，未指定 scope 时默认是 sub。

4. 检查具有代表性的用户

在选择映射之前，至少检查三个条目：

一个预期可以登录的普通用户。
另一个目标 OU 或目录分支中的用户。
一个边界情况，例如被禁用的用户、没有任何组的用户，或缺少可选属性的用户。

对于 OpenLDAP，请请求 DN、objectClass、uid、cn 和 mail。对于 Active Directory，请请求 DN、objectClass、sAMAccountName、displayName、mail、userAccountControl 和 memberOf。在缩小 Filter 之前，请确认目标用户集合位于候选 Base DN 之下。

5. 选择身份和登录属性

用途	OpenLDAP 候选项	Active Directory 候选项	选择规则
ACP user identity	`uid`	`sAMAccountName`	对每个目标用户都存在、唯一、稳定且非空
Login Field	`uid`, `mail`	`sAMAccountName`	用户熟悉，并且只返回一个条目
仅用于显示的信息	`cn`	`displayName`	可能会变化，不应作为默认 identity
Group member value	`member`, `memberUid`	`member`	必须与示例 group 条目中存储的值匹配
Group name	`cn`	`cn`	对管理员来说可读且稳定

不要仅仅因为 cn、displayName 或用户 DN 可读，就将它们用作默认的 ACP identity。这些值可能会重复，并且在用户重命名或移动时也可能发生变化。在创建 Connector 之前，请先在目录中解决缺失或重复的 identity 值问题。

6. 逐步构建 User Filter

按以下顺序构建并重新测试 Filter：

使用 objectClass 选择用户条目。
使用 (attribute=*) 要求 ACP identity 和 login 属性存在。
当客户的目录策略要求时，排除计算机、已禁用账户、服务账户或系统账户。
只有在宽泛结果与预期用户集合匹配后，才添加业务限制。

在添加每个条件后，重新运行外部目录查询，并将返回数量和代表性条目与预期用户集合进行比较。使用这些 Filter 查找那些因为建议的 identity 不存在而会被跳过的条目：

# OpenLDAP entries that would be skipped because uid is missing
(&(objectClass=inetOrgPerson)(!(uid=*)))

# Active Directory user objects missing sAMAccountName
(&(objectClass=user)(!(objectClass=computer))(!(sAMAccountName=*)))

# Optional Active Directory exclusion for disabled accounts
(&(objectClass=user)(!(objectClass=computer))(sAMAccountName=*)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))

最后一个表达式是可复制的用于排除已禁用账户的 Active Directory LDAP Filter。只有当该排除条件符合客户的目录策略时，才应用它。

LDAP Filter 语法速查

请使用能返回目标条目的最小表达式来构建 Filter。以下 operator 已在本指南使用的测试目录上进行过验证。

需求	语法	示例
精确值	`(attribute=value)`	`(uid=alice)`
属性存在	`(attribute=*)`	`(mail=*)`
所有条件都匹配	`(&(condition1)(condition2))`	`(&(objectClass=inetOrgPerson)(uid=*))`
任一条件匹配	`(\|(condition1)(condition2))`	`(\|(uid=alice)(mail=alice@test.com))`
排除某个条件	`(!(condition))`	`(!(objectClass=computer))`
排除已禁用的 Active Directory 账户	`(!(userAccountControl:1.2.840.113556.1.4.803:=2))`	在上面所示的 Active Directory user Filter 中使用

不要在已配置的 user Filter 中放置 <username> 占位符。同步会按原样运行已配置的 Filter。在登录期间，ACP 会将该 Filter 与每个已配置 Login Field 属性的等值查找组合起来。

7. 确定 Group Membership 模型

检查一个已知的 group，并将其存储的 membership 值与代表性用户进行比较：

当 member 包含完整的用户 DN 时，使用 Group Attr member 和 User Attr DN。
当 memberUid 包含简短的用户 ID 时，使用 Group Attr memberUid 和 User Attr uid。

ACP 会针对每个用户按 (<Group Attr>=<User Attr value>) 评估 group membership。使用外部目录查询重现该查找，例如 (member=uid=alice,ou=People,dc=example,dc=com) 或 (memberUid=alice)。在验证该映射时，不要只依赖用户的 memberOf 值。

选择已测试的映射

以下映射是本版本对所列布局支持的起点。Active Directory Filter 会排除计算机对象和已禁用账户。只有在客户目录策略要求不同的用户集合时，才更改该 Filter，并在更改后重复执行外部计数、ACP 同步和登录检查。

Directory layout	User Filter	User Name Attr	Login Field	Group Attr	User Attr	Group Name Attr
OpenLDAP `groupOfNames`	`(&(objectClass=inetOrgPerson)(uid=*))`	`uid`	`uid`	`member`	`DN`	`cn`
OpenLDAP `posixGroup`	`(&(objectClass=inetOrgPerson)(uid=*))`	`uid`	`uid`	`memberUid`	`uid`	`cn`
Active Directory	`(&(objectClass=user)(!(objectClass=computer))(sAMAccountName=*)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))`	`sAMAccountName`	`sAMAccountName`	`member`	`DN`	`cn`

当 Active Directory group synchronization 使用 Group Attr member 和 User Attr DN 时，请使用 (&(objectClass=group)(member=*)) 作为 Group Filter。ACP 会在创建期间针对采样的 group 条目验证 member。更宽泛的 (objectClass=group) Filter 可能会采样到不返回 member 属性的空 group，并拒绝本来有效的映射。

Add LDAP

转到 Users > IDP。
单击 Add LDAP。
填写 Basic Info：Name、Display Name 和可选的 Description。
填写 LDAP Server Setting：Server Address、Admin Account 和 Admin Password。
填写 Search Setting：Filter 和 Base DN。
如果需要 group synchronization，请启用 Group Search Setting，并输入 Filter、Base DN、Group Attr 和 User Attr。
完成 Field Mapping：User Name Attr、可选的 Group Name Attr、Login Field 和 Username Tip In Login Box。User Name Attr 会成为用于同步后的 ACP user 的稳定 identity 值；它不只是一个显示标签。Login Field 决定 ACP 如何搜索登录账户，并支持以逗号分隔的多个候选项。
可选地打开 Advanced Settings，启用 Auto Sync，并在 Sync Rules 中输入五字段 cron 表达式。ACP 会以 UTC 评估该规则。
单击 Add。

NOTE

在创建期间，ACP 会验证 server connectivity、bind、Base DN、Filter 以及映射后的属性。由于当前表单不会收集测试用户凭证，因此在创建期间不会对普通目录用户进行身份验证。提交的 bind 密码会在创建后迁移到受管理的 Secret 中。

Console 字段参考

使用下表将通过 ldapsearch 发现的值转换为当前 ACP 表单，以及后面描述的 YAML 字段（如有需要）。

ACP console field	YAML field	如何选择该值
Name	`id` 和 `metadata.name`	两个字段都使用相同的、符合 DNS 规则的值。
Display Name	`name`	显示在 ACP IDP 选择器中的名称。
Description	`metadata.annotations["cpaas.io/description"]`	可选的、面向 operator 的描述。
Server Address	`spec.config.host`	可从 ACP 访问的目录 hostname 或 IP 和端口。
Admin Account	`spec.config.bindDN`	具有目标条目只读访问权限的 bind 账户 DN。
Admin Password	`spec.config.bindPW`	初始创建输入；ACP 会将其存储在受管理的 Secret 中。
User Filter	`spec.config.userSearch.filter`	仅返回目标用户集合的 Filter。
User Base DN	`spec.config.userSearch.baseDN`	包含所有目标用户的最低目录分支。
Group Filter	`spec.config.groupSearch.filter`	目标 group 的 Filter；如果存在空 group，则需要显式要求成员属性。
Group Base DN	`spec.config.groupSearch.baseDN`	包含目标 group 的最低目录分支。
Group Attr	`spec.config.groupSearch.groupAttr`	group 上存储成员值的属性，例如 `member` 或 `memberUid`。
User Attr	`spec.config.groupSearch.userAttr`	与 Group Attr 可比较的 user 值，例如 `DN` 或 `uid`。
User Name Attr	`spec.config.userSearch.nameAttr`	用于 v2 ACP username 和 primary identifier 的稳定、唯一且非空 identity。
Group Name Attr	`spec.config.groupSearch.nameAttr`	可读的 group 名称，通常为 `cn`。
Login Field	`spec.config.userSearch.username`	一个或多个以逗号分隔的登录属性。仅配置你已验证且存在于过滤后条目上的属性。
Username Tip In Login Box	`spec.config.usernamePrompt`	在 LDAP 登录页显示的提示文本。
Auto Sync	`metadata.labels["cpaas.io/ldap.autoSync"]`	仅在手动同步正确后启用。
Sync Rules	`metadata.annotations["cpaas.io/ldap.autoSyncRule"]`	以 UTC 评估的五字段 cron 表达式。

表单不会暴露 scope、TLS 标志、CA 数据或可选的 profile 映射。只有在需要时，才通过 YAML 配置这些字段。

验证集成

打开新的 LDAP IDP，并选择 Actions > Sync user。
确认同步结果，并将同步后的 user 和 group 数量与预期的目录用户集合进行比较。
打开一个已同步用户，并验证其 source、identity 值和状态是否正确。
使用 Manage User Roles 或 Manage User Group Roles 分配一个最小权限角色。
使用一个不带 ACP 登录状态的单独浏览器会话，以代表性目录账户登录。
确认身份验证成功，并且分配的 ACP 权限可用。

WARNING

整体同步可能会报告成功，但缺少 User Name Attr 的条目会被跳过。某个用户没有匹配的目录 group，并不意味着该用户同步失败。请比较计数并检查具有代表性的条目，而不要只依赖整体结果。

同步与生命周期

首次登录同步

目录用户可以在未进行完整手动同步之前先登录。身份验证成功后，ACP 会同步该单个 LDAP 用户。请使用上面的完整验收路径来验证预期清单、group 映射和授权，而不要把首次登录视为完整集成验收。

手动同步

打开 LDAP IDP 并选择 Actions > Sync user，即可按需同步并协调目录用户集合。请检查结果、计数、跳过条目消息以及具有代表性的用户和 group。

新同步的 LDAP 用户是活动的、有效的，其默认有效期为 Permanent，除非管理员之后更改其有效期。

在同步开始之前，ACP 会警告：如果某个 IDP user 与现有本地用户同名，可能会覆盖或重新关联该用户，同时保留现有的角色分配。在首次完整同步之前，请检查建议的 User Name Attr 是否与当前 ACP 用户冲突。不要使用内置本地管理员账户作为集成测试身份。

自动同步

当需要定期协调时，请在 Advanced Settings 下启用 Auto Sync，并提供 Sync Rules。自动同步使用已配置的 Base DN、Filter 和映射；它不会对目录用户密码进行身份验证。ACP 会以 UTC 评估五字段 cron 表达式。对于验收测试，*/1 * * * * 表示每分钟运行一次；在观察到计划运行后，请将该临时规则替换掉。

更新 Connector

当 server、搜索边界、Filter、映射或自动同步设置发生变化时，请更新 LDAP IDP。更新后运行一次手动同步，以确认新配置并协调现有的 source 用户和 group。

协调上游已删除的用户

在手动或自动协调之后，从上游目录中删除的用户会在 ACP 中变为无效，并且不能再通过该 source 进行身份验证。

删除 Connector

删除 Connector 而不进行清理时，会保留来自该 source 的用户和 group，并将用户标记为无效。如果在删除时选择 Clean up IDP users and User Groups，ACP 会删除由该 Connector 生成的用户和 group。

使用 YAML 配置 LDAP

以下 v2 Connector 模板仅将 bindPW 作为初始创建输入。请通过 ACP 控制台的 YAML 选项卡提交它们。ACP 会将提交的密码迁移到受管理的 Secret 中，而存储后的 YAML 将包含受管理的 clientSecretRef，而不是 bindPW。不要使用带有内联 bindPW 的 kubectl apply：Kubernetes 的 last-applied annotation 可能会在 Connector metadata 中保留提交的密码。使用前请替换每个示例值。

模板中有意显示的字段

当创建 Connector 时，ACP 会添加 metadata.labels["cpaas.io/idp.version"]: v2。对于没有 rootCAData 的普通 LDAP 连接，ACP 还会持久化 insecureNoSSL: true、insecureSkipVerify: true 和 startTLS: false。模板显式展示这些值，以便提交的 YAML 能够描述实际生效的连接模式。

ACP 可以从 Filter 中第一个 objectClass 推断部分 user 和 group 属性。不要依赖这种推断来交付给客户：它无法确定目录实际的 identity 和 membership 模型。在检查过代表性条目后，请显式设置 idAttr、nameAttr、username、groupAttr、userAttr 以及 group 的 nameAttr。模板还显式写入了 scope: sub，尽管 sub 是运行时默认值。clientSecretRef 并不是这些模板中的输入字段，因为 ACP 只有在将 bindPW 迁移到受管理的 Secret 之后才会写入它。

严格验证的 OpenLDAP 模板

636 端口上的证书验证限制

在此 ACP 版本中，任何 host 以 :636 结尾的 Connector，都会被存储为 insecureSkipVerify: true，即使提交的值是 false 且 rootCAData 包含正确的 CA 也是如此。标准端口上的 LDAPS 流量会被加密，但 ACP 不会验证 LDAP server 证书。

下面的模板适用于在非 636 端口上提供 LDAPS 的目录。在该端口上，请保持 insecureSkipVerify: false，并通过 rootCAData 提供受信任的 CA。如果需要证书验证，请与目录和网络管理员协调端口，然后再完成 Connector 创建、同步和真实登录，以便正式发布。

apiVersion: dex.coreos.com/v1
kind: Connector
id: corporate-ldap
name: Corporate LDAP
type: ldap
metadata:
  name: corporate-ldap
  namespace: cpaas-system
  labels:
    cpaas.io/idp.version: v2
spec:
  config:
    host: "<LDAPS_HOST>:<NON_636_LDAPS_PORT>"
    bindDN: cn=reader,dc=example,dc=com
    bindPW: <BIND_PASSWORD>
    insecureNoSSL: false
    insecureSkipVerify: false
    startTLS: false
    rootCAData: <BASE64_ENCODED_CA_CERTIFICATE_PEM>
    usernamePrompt: Directory username
    userSearch:
      baseDN: ou=People,dc=example,dc=com
      filter: "(&(objectClass=inetOrgPerson)(uid=*))"
      scope: sub
      idAttr: uid
      nameAttr: uid
      username: uid
    groupSearch:
      baseDN: ou=Groups,dc=example,dc=com
      filter: "(objectClass=groupOfNames)"
      scope: sub
      groupAttr: member
      userAttr: DN
      nameAttr: cn

Active Directory 模板

apiVersion: dex.coreos.com/v1
kind: Connector
id: corporate-ad
name: Corporate Active Directory
type: ldap
metadata:
  name: corporate-ad
  namespace: cpaas-system
  labels:
    cpaas.io/idp.version: v2
spec:
  config:
    host: ad.example.com:389
    bindDN: CN=ACP Reader,OU=Service Accounts,DC=example,DC=com
    bindPW: <BIND_PASSWORD>
    insecureNoSSL: true
    insecureSkipVerify: true
    startTLS: false
    usernamePrompt: AD username
    userSearch:
      baseDN: OU=Employees,DC=example,DC=com
      filter: "(&(objectClass=user)(!(objectClass=computer))(sAMAccountName=*)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))"
      scope: sub
      idAttr: sAMAccountName
      nameAttr: sAMAccountName
      username: sAMAccountName
    groupSearch:
      baseDN: OU=Groups,DC=example,DC=com
      filter: "(&(objectClass=group)(member=*))"
      scope: sub
      groupAttr: member
      userAttr: DN
      nameAttr: cn

完整的 LDAP YAML 字段参考

下面的骨架包含对 v2 LDAP Connector 有用的 ACP 集成字段。可选的 profile 映射已注释掉，以便在目录不提供这些属性时示例仍然有效。如果某些属性在过滤后的用户中不存在，请移除未使用的可选字段，而不要为缺失属性命名。

apiVersion: dex.coreos.com/v1
kind: Connector
id: corporate-ldap
name: Corporate LDAP
type: ldap
metadata:
  name: corporate-ldap
  namespace: cpaas-system
  annotations:
    cpaas.io/description: Corporate directory
    cpaas.io/ldap.autoSyncRule: "0 2 * * *"
    # cpaas.io/idp.validation: "false"
  labels:
    cpaas.io/idp.version: v2
    cpaas.io/ldap.autoSync: "true"
spec:
  config:
    host: ldap.example.com:1636
    bindDN: cn=reader,dc=example,dc=com
    bindPW: <BIND_PASSWORD>
    insecureNoSSL: false
    insecureSkipVerify: false
    startTLS: false
    rootCAData: <BASE64_ENCODED_CA_CERTIFICATE_PEM>
    usernamePrompt: Directory username
    userSearch:
      baseDN: ou=People,dc=example,dc=com
      filter: "(&(objectClass=inetOrgPerson)(uid=*))"
      scope: sub
      idAttr: uid
      nameAttr: uid
      username: uid
      # emailAttr: mail
      # preferredUsernameAttr: cn
      # phoneAttr: telephoneNumber
      # emailSuffix: test.com
    groupSearch:
      baseDN: ou=Groups,dc=example,dc=com
      filter: "(&(objectClass=groupOfNames)(member=*))"
      scope: sub
      groupAttr: member
      userAttr: DN
      nameAttr: cn

顶层和 metadata 字段：

字段	是否必需	产品行为
`apiVersion`	是	使用 `dex.coreos.com/v1`。
`kind`	是	使用 `Connector`。
`id`	是	Connector identity。保持其与 `metadata.name` 相同。
`name`	是	在 ACP 登录选择器中显示的名称。
`type`	是	使用 `ldap`。
`metadata.name`	是	Kubernetes 资源名和 ACP Connector 查询键。
`metadata.namespace`	是	使用 `cpaas-system`。
`metadata.annotations["cpaas.io/description"]`	否	ACP 显示的描述。
`metadata.annotations["cpaas.io/idp.validation"]`	仅用于临时故障排查	字符串值 `"false"` 会跳过此创建或更改 spec 的更新过程中的目录连通性验证；格式验证仍会执行。不要将其设为 `"true"`。
`metadata.labels["cpaas.io/idp.version"]`	是	对于本文档中的映射，请使用 `v2`。
`metadata.labels["cpaas.io/ldap.autoSync"]`	否	字符串值 `"true"` 或 `"false"`；启用计划同步。
`metadata.annotations["cpaas.io/ldap.autoSyncRule"]`	启用自动同步时	以 UTC 评估的五字段 cron 表达式。

连接和传输字段：

字段	是否必需	产品行为
`host`	是	ACP 集群可访问的目录主机和端口。
`bindDN`	是	用于读取用户和组的 bind 账户 DN。
`bindPW`	初始创建时必需	ACP YAML 页面接受的明文输入。ACP 会移除它并将密码存储在受管理的 Secret 中。
`clientSecretRef`	存储后的输出	ACP 写入的受管理 Secret 引用。不要将其与 `bindPW` 一起提交，也不要手动编辑。
`insecureNoSSL`	是	`true` 选择明文 LDAP；`false` 则根据 `startTLS` 选择 TLS。
`startTLS`	是	当 `insecureNoSSL: false` 且为 `false` 时，选择 LDAPS。`true` 则选择通过 LDAP 的 StartTLS。
`insecureSkipVerify`	TLS 连接	`false` 请求 server 证书验证，但受下方 636 端口限制影响。
`rootCAData`	私有 CA 严格 TLS	用于 Connector trust pool 的 Base64 编码 PEM CA 证书。
`usernamePrompt`	否	登录页 LDAP username 字段上方显示的文本。

userSearch 字段：

字段	是否必需	产品行为
`baseDN`	是	用户条目的搜索边界。
`filter`	是	用于选择同步用户集合的 LDAP Filter。
`scope`	否	`sub` 搜索整个子树，是运行时默认值；`one` 只搜索 `baseDN` 下一级。
`nameAttr`	v2 必需	在同步期间用作 ACP username 和 primary identifier 的稳定唯一值。
`idAttr`	是	验证和兼容性 identity 字段。对于 v2，请将其设置为与 `nameAttr` 相同的稳定属性。
`username`	是	在登录期间用于查找用户的一个或多个以逗号分隔的属性。
`emailAttr`	否	将目录值复制到 ACP 用户的 `mail` 字段。仅当过滤后的用户提供该属性时配置。
`preferredUsernameAttr`	否	在 LDAP 登录期间提供 preferred-username Claim；它不会替代来自 `nameAttr` 的 v2 同步 identity。
`phoneAttr`	否	将目录值复制到 ACP 用户的 mobile 字段。仅当过滤后的用户提供该属性时配置。
`emailSuffix`	否	在 LDAP 登录期间，将 identity email 构造为 `<nameAttr>@<suffix>`；输入 suffix 时不要带 `@`。

Warning

emailSuffix 和 v2 同步

在经过验证的 v2 行为中，emailSuffix: test.com 会为首次登录 identity 生成 admin@test.com，而手动同步仍会将不带后缀的 nameAttr 存为 primary identifier。除非已针对客户的同步和冲突要求测试过这种差异，否则请保持 emailSuffix 未设置。

groupSearch 字段：

字段	在启用 group 同步时是否必需	产品行为
`baseDN`	是	group 条目的搜索边界。
`filter`	是	用于选择 group 的 LDAP Filter。要求成员属性可以避免对空 group 的验证。
`scope`	否	`sub` 是运行时默认值；`one` 搜索 `baseDN` 下一级。
`groupAttr`	是	group 条目中包含成员值的属性。
`userAttr`	是	与 `groupAttr` 比较的用户条目中的属性或 `DN` 值。
`nameAttr`	是	用作 ACP group 显示名称的属性，通常为 `cn`。

当 ACP 不需要 group synchronization 时，请完全省略 groupSearch。

临时绕过验证

仅当目录暂时不可达且必须先部署 Connector 时，才使用 cpaas.io/idp.validation: "false"。ACP 仍会检查配置结构，但会跳过网络、TLS、bind、Base DN、Filter 以及映射属性检查。因此，即使同步和登录无法工作，Connector 也可能已经存在。

admission webhook 会从存储的 Connector 中移除此注解，并将跳过标记复制到受管理的凭证 Secret。之后如果对 Connector 做不带该注解的 spec 更改更新，则会执行正常的 Connector 验证。要为后续凭证更改恢复验证，请通过不带该注解的 Connector 更新凭证；不要直接编辑受管理的 Secret。不要使用 cpaas.io/idp.validation: "true"；正常验证时请省略该注解。

在正式发布前，请完成一次正常验证的创建或真实纠正性更新，然后运行手动同步和具有代表性的登录。仅进行 metadata 更新，不能证明正常验证已经运行。

请将传输标志作为一组来选择：

传输类型	典型端口	`insecureNoSSL`	`startTLS`	证书验证
明文 LDAP	389	`true`	`false`	不适用；仅在网络策略允许且网络受信任时使用
标准端口上的 LDAPS	636	`false`	`false`	Connector 实现会存储 `insecureSkipVerify: true`；流量已加密，但不会验证 LDAP server 证书
具有严格证书验证的 LDAPS	已配置的非 636 LDAPS 端口	`false`	`false`	保持 `insecureSkipVerify: false`，通过 `rootCAData` 提供受信任的 CA，并在正式发布前完成验收检查

上面的 Active Directory 模板使用的是明文 LDAP。明文 LDAP 不会在网络上传输时保护 bind 密码。仅当客户的网络和安全策略允许时才使用它。当需要 TLS 时，首先要确定策略是否还要求证书验证：在此版本中，标准端口 636 提供加密，但不提供 server 证书验证；而严格验证则需要非 636 的 LDAPS 端口和 rootCAData。在正式发布前，请完成一次 ACP LDAPS 创建、同步和登录测试。

要在非 636 的 LDAPS 端口上进行严格证书验证，请将 PEM CA 证书编码为不包含换行的 Base64，并将输出用作 rootCAData：

openssl base64 -A -in ldap-ca.pem

如果要在 YAML 中进行计划同步，请向 Connector 添加受支持的 metadata：

metadata:
  labels:
    cpaas.io/ldap.autoSync: "true"
  annotations:
    cpaas.io/ldap.autoSyncRule: "*/1 * * * *"

示例规则仅适用于观察一次验收测试运行。在验证完成后，请将其替换为所需的 UTC 计划。顶层 id 必须等于 metadata.name；当前计划同步会通过该 identity 查找 Connector。

按症状排查

症状	产品阶段	可能原因	具体检查
ACP 无法创建 Connector，因为它无法连接。	Connector 创建	集群 DNS、路由、防火墙、端口、TLS 模式或证书信任不正确。	从一个与 ACP 可达性等效的主机或 Pod 上运行下面的外部 TCP 或 TLS 检查，然后查看 `auth-controller2` 日志。
Bind 成功，但 Base DN 或 Filter 验证失败。	Connector 创建和搜索验证	对于 bind 账户而言，Base DN 不存在，Filter 无效，或 Filter 返回的条目不可用。	对 Base DN 运行外部 base-scope 查询，然后运行精确的 subtree Filter，并查看 `auth-controller2` 日志。
ACP 拒绝 Active Directory Group Attr `member`，并且也建议使用 `member`。	Connector 创建和 group 属性验证	Group Filter 采样到了没有返回 `member` 属性的空 group。	使用 `(&(objectClass=group)(member=*))`，确认外部查询返回的是目标 group，然后重试创建。
同步报告成功，但返回的用户比预期少。	手动或计划同步	Filter 排除了用户、用户不在 Base DN 范围内，或者缺少必需的 User Name Attr 值。	将外部 subtree 结果与预期数量进行比较，运行上面缺失属性的 Filter，并检查 `apollo` 日志中的跳过条目消息。
Connector 创建成功，但某个目录用户无法登录。	登录	Login Field 未能找到唯一条目，账户被排除或已禁用，或者代表性凭证无效。	使用每个已配置的 login attribute 查询代表性的登录值，确认结果唯一，然后在单独的浏览器会话中重试，并查看 `apollo` 日志。
用户已同步，但组没有同步。	Group 同步	Group Attr 和 User Attr 无法表示 group 中存储的值，或者 Group Base DN 或 Filter 错误。	检查一个已知 group，并使用外部 subtree 查询重现 `(<Group Attr>=<User Attr value>)`，然后检查 `apollo` 中的 group 查找消息。
identity 发生冲突或意外变化。	用户同步和协调	User Name Attr 重复、为空、可变，或基于在重命名或移动后已更改的 DN。	在整个 User Base DN 范围内查询建议的 identity 属性，检查缺失值和重复值，并选择一个稳定且唯一的属性。
自动同步未运行。	计划同步	Auto Sync metadata 缺失或无效，或者顶层 `id` 与 `metadata.name` 不同。	检查已存储的 Connector metadata 和 identity，然后查看 `apollo` 日志中的计划同步消息。

现场诊断工具

本节中的工具是外部集成前诊断工具或高级 ACP 证据收集工具。它们不是内置的 ACP 功能。

外部：Linux 和 macOS LDAP 工具

LDAP 命令需要已安装的 OpenLDAP 客户端，例如 ldapsearch 和 ldapwhoami。它们会使用 -W 提示输入 bind 密码。该选项只能避免密码出现在命令行中，并不会加密网络传输。

下面的私有 CA 环境变量已在 Linux OpenLDAP 客户端上验证通过。内置的 macOS /usr/bin/ldapsearch 和 /usr/bin/ldapwhoami 则使用 macOS 系统信任存储；请使用 Linux 诊断主机或 Pod，或者在使用这些内置客户端之前先在 macOS Keychain 中配置 CA。

对于每个 ldapwhoami 和 ldapsearch 命令，请使用与正在调查的 Connector 相同的传输组合：

Connector transport	Connector settings	OpenLDAP client transport	Bind credential protection
Plain LDAP	`insecureNoSSL: true`, `startTLS: false`	`-H ldap://ldap.example.com:389` without `-ZZ`	No TLS protection; use only when network policy permits
LDAPS	`insecureNoSSL: false`, `startTLS: false`	`-H ldaps://ldap.example.com:636` without `-ZZ`	TLS starts when the connection is established

下面的查询示例使用的是明文 LDAP，因此只与 insecureNoSSL: true 的 Connector 匹配。对于 LDAPS，请在运行每个示例之前，将 -H 值替换为对应行的值。如果 LDAP 证书由私有 CA 签名，诊断客户端也必须信任该 CA。对于 Linux OpenLDAP 客户端，请在每个 ldapwhoami 或 ldapsearch 命令前加上如下前缀：

LDAPTLS_REQCERT=demand \
LDAPTLS_CACERT=/path/to/ldap-ca.pem \
ldapwhoami -x -H ldaps://ldap.example.com:636 \
  -D 'cn=reader,dc=example,dc=com' -W

如果没有 LDAPTLS_CACERT 设置，经过验证的 Linux 客户端会失败并提示 unable to get local issuer certificate；加上 CA 文件后，同样的 bind 则会成功。

外部命令：仅测试 TCP 端口可达性

nc -vz ldap.example.com 389

此命令只检查 TCP 端口是否可达，不会验证 TLS、bind 凭证或 LDAP 搜索行为。检查 LDAPS 端口可达性时，请改用端口 636。

外部命令：验证 server、传输和 bind 账户

ldapwhoami -x -H ldap://ldap.example.com:389 \
  -D 'cn=reader,dc=example,dc=com' -W

外部命令：读取目录 Root DSE

ldapsearch -LLL -x -H ldap://ldap.example.com:389 \
  -D 'cn=reader,dc=example,dc=com' -W \
  -b '' -s base '(objectClass=*)' namingContexts defaultNamingContext

外部命令：确认候选 Base DN 可读

ldapsearch -LLL -x -H ldap://ldap.example.com:389 \
  -D 'cn=reader,dc=example,dc=com' -W \
  -b 'ou=People,dc=example,dc=com' -s base \
  '(objectClass=*)' dn

外部命令：重现 OpenLDAP user subtree 搜索

ldapsearch -LLL -x -H ldap://ldap.example.com:389 \
  -D 'cn=reader,dc=example,dc=com' -W \
  -b 'ou=People,dc=example,dc=com' -s sub \
  '(&(objectClass=inetOrgPerson)(uid=*))' \
  dn uid cn mail objectClass

外部命令：查找缺少建议 identity 的 OpenLDAP 条目

ldapsearch -LLL -x -H ldap://ldap.example.com:389 \
  -D 'cn=reader,dc=example,dc=com' -W \
  -b 'ou=People,dc=example,dc=com' -s sub \
  '(&(objectClass=inetOrgPerson)(!(uid=*)))' dn cn mail

外部命令：打印建议的 OpenLDAP identity 的重复值

ldapsearch -LLL -x -H ldap://ldap.example.com:389 \
  -D 'cn=reader,dc=example,dc=com' -W \
  -b 'ou=People,dc=example,dc=com' -s sub \
  '(&(objectClass=inetOrgPerson)(uid=*))' uid | \
  awk -F ': ' '$1 == "uid" { print $2 }' | \
  LC_ALL=C sort -f | uniq -di

在评估其他候选 identity 属性时，请替换 uid、Base DN 和 Filter。没有输出意味着在返回的条目中没有发现重复值。与其他 ldapsearch 示例一样，请使用与 Connector 匹配的传输组合。

外部命令：重现 groupOfNames 的 membership 查找

ldapsearch -LLL -x -H ldap://ldap.example.com:389 \
  -D 'cn=reader,dc=example,dc=com' -W \
  -b 'ou=Groups,dc=example,dc=com' -s sub \
  '(&(objectClass=groupOfNames)(member=uid=alice,ou=People,dc=example,dc=com))' \
  dn cn member

外部命令：使用预期的 CA 验证 LDAPS 证书链

openssl s_client -connect ldap.example.com:636 \
  -servername ldap.example.com \
  -CAfile ldap-ca.pem -verify_return_error

只有当输出报告验证成功时，证书检查才算通过，例如 Verify return code: 0 (ok) 或 Verification: OK。

外部：使用 `ldapsearch` 查询 Active Directory

同一个 OpenLDAP 命令行客户端无需 Windows 或 RSAT 也可以检查 Active Directory。请使用具有只读权限的目录账户。

外部命令：检查目标 Active Directory 用户

ldapsearch -LLL -x -H ldap://ad.example.com:389 \
  -D 'CN=ACP Reader,OU=Service Accounts,DC=example,DC=com' -W \
  -b 'OU=Employees,DC=example,DC=com' -s sub \
  '(&(objectClass=user)(!(objectClass=computer))(sAMAccountName=*)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))' \
  dn sAMAccountName displayName mail userAccountControl memberOf

外部命令：重现 Active Directory group membership 查找

ldapsearch -LLL -x -H ldap://ad.example.com:389 \
  -D 'CN=ACP Reader,OU=Service Accounts,DC=example,DC=com' -W \
  -b 'OU=Groups,DC=example,DC=com' -s sub \
  '(&(objectClass=group)(member=CN=Alice,OU=Employees,DC=example,DC=com))' \
  dn cn member

高级：ACP 组件日志

这些部署名称是当前 ACP 组件名称。运行这些命令需要读取集群日志的权限。

高级 ACP 命令：检查 Connector 创建验证

kubectl -n cpaas-system logs deployment/auth-controller2 --since=10m

auth-controller2 负责 Connector 创建验证，包括网络连接、TLS、bind、Base DN、Filter 和映射后的属性。

高级 ACP 命令：检查同步和登录行为

kubectl -n cpaas-system logs deployment/apollo --since=10m

apollo 负责手动和计划同步、跳过条目、group 查找以及登录行为。

NOTE

使用外部工具成功，并不能证明 ACP 能够访问或使用该目录。请通过 ACP Connector 创建、预期的同步结果以及使用目标 ACP 权限进行一次真实的目录登录，来完成证据链。

#LDAP 管理

#目录

#开始之前

#Discover the Directory Settings

#1. 从正确的网络运行检查

#2. 查找目录根

#3. 选择 User 和 Group 的 Base DN

#4. 检查具有代表性的用户

#5. 选择身份和登录属性

#6. 逐步构建 User Filter

#LDAP Filter 语法速查

#7. 确定 Group Membership 模型

#选择已测试的映射

#Add LDAP

#Console 字段参考

#验证集成

#同步与生命周期

#首次登录同步

#手动同步

#自动同步

#更新 Connector

#协调上游已删除的用户

#删除 Connector

#使用 YAML 配置 LDAP

#严格验证的 OpenLDAP 模板

#Active Directory 模板

#完整的 LDAP YAML 字段参考

#按症状排查

#现场诊断工具

#外部：Linux 和 macOS LDAP 工具

#外部：使用 ldapsearch 查询 Active Directory

#高级：ACP 组件日志