LDAP 管理

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

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

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

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

开始之前

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

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

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

发现目录设置

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

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

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

2. 查找目录根

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

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

请使用最终 现场诊断工具 部分中的 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 查询确认绑定账户可以读取候选 Base DN。ACP 表单会在配置的 Base DN 下执行 subtree 搜索，不会暴露 Search Scope 字段。YAML 可以使用 scope: sub 或 scope: one；在当前 Connector runtime 中，未指定的 scope 默认是 sub。

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

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

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

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

目的	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 和登录属性存在。
当客户目录策略要求时，排除计算机、禁用账户、服务账户或系统账户。
仅在广泛结果与预期用户集合匹配之后，再添加业务限制。

在每个条件之后，重新运行外部目录查询，并将计数和代表性条目与预期用户集合进行比较。使用以下 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，并将其存储的成员值与代表性用户进行比较：

当 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 同步和登录检查。

目录布局	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，并拒绝一个原本有效的映射。

添加 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 用户所使用的稳定 identity 值；它不只是一个显示标签。Login Field 决定 ACP 如何搜索登录账户，并支持以逗号分隔的多个候选项。
可选地打开 Advanced Settings，启用 Auto Sync，并在 Sync Rules 中输入五段式 cron 表达式。ACP 会按 UTC 评估该规则。
单击 Add。

NOTE

在创建期间，ACP 会验证 server connectivity、bind、Base DN、Filter 和映射属性。当前表单在创建时不会认证普通目录用户，因为它不收集测试用户凭证。提交的 bind password 会在创建后移动到受管理的 Secret 中。

控制台字段参考

使用此表将 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 可达的目录主机名或 IP 和端口。
Admin Account	`spec.config.bindDN`	具有读取目标条目权限的绑定账户 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 时，需要要求 member 属性。
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 比较的用户值，例如 `DN` 或 `uid`。
User Name Attr	`spec.config.userSearch.nameAttr`	用于 v2 ACP username 和主标识的稳定、唯一、非空 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 mappings。只有在需要时，才通过 YAML 配置这些字段。

验证集成

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

WARNING

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

同步与生命周期

首次登录同步

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

手动同步

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

新同步的 LDAP 用户是 active、valid 的，且默认 validity period 为 Permanent，除非管理员之后更改其 validity。

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

自动同步

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

更新 Connector

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

协调上游已删除的用户

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

删除 Connector

删除 Connector 而不进行清理时，会保留来自该 source 的用户和 group，并将这些用户标记为 invalid。如果在删除期间选择了 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 推断某些用户和 group 属性。对于客户交付，不要依赖这种推断：它无法判断目录实际的 identity 和 membership 模型。请在检查代表性条目后，显式设置 idAttr、nameAttr、username、groupAttr、userAttr 和 group 的 nameAttr。模板还会显式写入 scope: sub，尽管 sub 是运行时默认值。这里的模板不把 clientSecretRef 作为输入字段，因为 ACP 只有在将 bindPW 移动到受管理的 Secret 后才会写入它。

严格验证的 OpenLDAP 模板

636 端口上的证书验证限制

在此 ACP 版本中，若 Connector 的 host 以 :636 结尾，即使提交的值为 false 且 rootCAData 包含正确的 CA，系统也会将其存储为 insecureSkipVerify: true。标准端口的 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 mappings 已注释掉，以便在目录不提供这些属性时示例仍然有效。请移除未使用的可选字段，而不是为缺失于过滤后用户中的属性命名。

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"]`	启用 auto sync 时需要	在 UTC 中评估的五段式 cron 表达式。

连接和传输字段：

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

userSearch 字段：

字段	是否必需	产品行为
`baseDN`	是	用户条目的搜索边界。
`filter`	是	用于选择已同步用户集合的 LDAP Filter。
`scope`	否	`sub` 搜索完整子树，是运行时默认值；`one` 只搜索 `baseDN` 下的一层。
`nameAttr`	v2 时必需	同步期间用作 ACP username 和主标识的稳定唯一值。
`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>`；输入时不要包含 `@`。

Warning

emailSuffix 和 v2 同步

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

groupSearch 字段：

字段	启用 group synchronization 时是否必需	产品行为
`baseDN`	是	group 条目的搜索边界。
`filter`	是	用于选择 group 的 LDAP Filter。当存在空 group 时，需要要求 membership attribute，以避免对空 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 仍会检查配置结构，但会跳过 network、TLS、bind、Base DN、Filter 和映射属性检查。因此，即使同步和登录无法工作，Connector 仍可能存在。

admission webhook 会从已存储的 Connector 中移除此注解，并将 skip 标记复制到受管理的 credential Secret。之后，如果在没有该注解的情况下更新 Connector 的 spec，系统会执行正常的 Connector 验证。要在未来的凭证变更中恢复验证，请通过不带该注解的 Connector 更新 credential；不要直接编辑受管理的 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 password。仅当客户的网络和安全策略允许时才使用它。当需要 TLS 时，先确定策略是否也要求证书验证：此版本中，标准端口 636 提供加密，但不提供服务器证书验证；而严格验证需要非 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 没有找到恰好一个条目，账户被排除或禁用，或代表性凭证无效。	使用每个已配置的登录属性查询代表性的登录值，确认恰好一个结果，在独立浏览器会话中重试，并检查 `apollo` 日志。
用户已同步，但 group 未同步。	group 同步	Group Attr 和 User Attr 不能代表存储在 group 中的值，或者 Group Base DN 或 Filter 有误。	检查一个已知 group，并使用外部 subtree 查询复现 `(<Group Attr>=<User Attr value>)`，然后检查 `apollo` 中的 group lookup 消息。
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 password。该选项只能防止密码出现在命令行中，并不会加密网络传输。

下面的私有 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 用户 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 管理

#目录

#开始之前

#发现目录设置

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

#2. 查找目录根

#3. 选择 User 和 Group Base DN

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

#5. 选择 Identity 和 Login 属性

#6. 逐步构建 User Filter

#LDAP Filter 语法速查

#7. 确定 Group Membership 模型

#选择经过验证的映射

#添加 LDAP

#控制台字段参考

#验证集成

#同步与生命周期

#首次登录同步

#手动同步

#自动同步

#更新 Connector

#协调上游已删除的用户

#删除 Connector

#使用 YAML 配置 LDAP

#严格验证的 OpenLDAP 模板

#Active Directory 模板

#完整 LDAP YAML 字段参考

#按症状排查

#现场诊断工具

#外部：Linux 和 macOS LDAP 工具

#外部：使用 ldapsearch 查询 Active Directory

#高级：ACP 组件日志