#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 属性、user matching 属性以及 group name 属性。
• 一个代表性的用户账号，用于最终登录验证。

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

#发现目录设置

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

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

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

#2. 找出目录根

查询目录 Root DSE 并记录命名根：

• 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。

在运行子树查询之前，请先使用外部 base 范围查询确认 Bind 账号可以读取候选 Base DN。ACP 表单会在配置的 Base DN 下执行子树搜索，不提供 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. 选择 Identity 和 Login 属性

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

#6. 逐步构建 User Filter

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

1. 使用 objectClass 选择用户条目。
2. 使用 (attribute=*) 要求 ACP identity 和登录属性存在。
3. 当客户的目录策略要求时，排除计算机、已禁用账号、服务账号或系统账号。
4. 仅在宽泛结果与预期用户群相匹配后，再添加业务限制。

每增加一个条件后，都重新运行外部目录查询，并将返回数量和代表性条目与预期用户群进行比较。使用以下 Filters 查找会因建议的 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 语法速查

从能够返回目标条目的最小表达式开始构建 Filters。下面的运算符已在本指南使用的测试目录上进行过验证。

不要在配置的 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 同步和登录检查。

当 Active Directory group synchronization 使用 Group Attr member 和 User Attr DN 时，请将 (&(objectClass=group)(member=*)) 作为 Group Filter。这样可以排除不返回 member 属性的空组，并使同步后的 group 用户群与已配置的成员映射保持一致。

#添加 LDAP

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

#控制台字段参考

使用此表将通过 ldapsearch 发现的值映射到当前 ACP 表单，以及后文描述的 YAML 字段。

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

#验证集成

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

#同步与生命周期

#首次登录同步

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

#手动同步

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

新同步的 LDAP 用户处于激活、有效状态，默认有效期为 Permanent，除非管理员后来修改其有效期。

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

#自动同步

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

#更新 Connector

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

#协调上游已删除的用户

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

#删除 Connector

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

#使用 YAML 配置 LDAP

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

#严格验证的 OpenLDAP 模板

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 * * *"
  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 字段：

连接和传输字段：

userSearch 字段：

groupSearch 字段：

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

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

上面的 Active Directory 模板使用普通 LDAP。普通 LDAP 不会在网络上传输时保护 bind 密码。仅在客户的网络和安全策略允许时使用。若需要 TLS，应先确认策略是否也要求证书验证：本版本中的标准 636 端口提供加密，但不进行 server 证书验证；而严格验证需要一个非 636 的 LDAPS 端口以及 rootCAData。推广前，请完成一次 ACP LDAPS 创建、同步和登录测试。

对于在非 636 LDAPS 端口上的严格证书验证，请将 PEM CA 证书编码为无换行格式，并将输出用作 rootCAData：

openssl base64 -A -in ldap-ca.pem

若要在 YAML 中启用计划同步，请将受支持的 metadata 添加到 Connector 中：

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

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

#按症状排查

#现场诊断工具

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

#外部：Linux 和 macOS LDAP 工具

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

下面的私有 CA 环境变量已在 Linux OpenLDAP 客户端上验证。macOS 自带的 /usr/bin/ldapsearch 和 /usr/bin/ldapwhoami 使用的是 macOS 系统信任库；请使用 Linux 诊断主机或 Pod，或者在使用这些自带客户端前将 CA 配置到 macOS Keychain 中。

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

下面的查询示例使用普通 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 用户子树搜索

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 成员查找

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 lookup 以及登录行为。