#LDAP 管理

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

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

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

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

#开始之前

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

• 从 ACP 集群可达的 LDAP server 主机名和端口。
• 具有对预期用户和组读取权限的 Bind DN 和 password。
• User Base DN 和 user Filter。
• 一个稳定、唯一、非空的用户身份属性。
• 一个或多个 login attributes。
• 可选的 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。

请使用最终 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 account 能够读取候选 Base DN。ACP 表单会在配置的 Base DN 下执行 subtree search。它不提供 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 之下。

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

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

#6. 逐步构建 User Filter

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

1. 通过 objectClass 选择用户条目。
2. 使用 (attribute=*) 要求 ACP 身份和 login attributes 存在。
3. 如果客户的目录策略要求，排除计算机、已禁用账户、服务账户或系统账户。
4. 仅在广泛结果与预期对象匹配后，再添加业务限制。

在每个条件之后，重新运行外部目录查询，并将返回数量和代表性条目与预期对象进行比较。使用这些 Filter 查找由于建议的身份不存在而会被跳过的条目：

# 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。以下运算符已在本指南使用的测试目录上验证过。

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

#7. 确定 Group Membership 模型

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

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

ACP 会将每个用户的 group membership 计算为 (<Group Attr>=<User Attr value>)。使用外部目录查询复现该查找，例如 (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 population 与配置的 membership 映射一致。

#添加 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 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 user 所使用的稳定身份值；它不仅仅是显示标签。Login Field 决定 ACP 如何搜索登录账号，并支持以逗号分隔的多个备选项。
8. 可选地打开 Advanced Settings，启用 Auto Sync，并在 Sync Rules 中输入五字段 cron expression。ACP 会以 UTC 解释该规则。
9. 点击 Add。

#控制台字段参考

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

表单不暴露 scope、TLS 标志、CA data 或可选的 profile mappings。仅当需要时，才通过 YAML 配置这些字段。

#验证集成

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

#同步与生命周期

#首次登录同步

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

#手动同步

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

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

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

#自动同步

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

#更新 Connector

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

#协调上游已删除的用户

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

#删除 Connector

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

#使用 YAML 配置 LDAP

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

#严格验证的 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 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 * * *"
  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 同步，则完全省略 groupSearch。

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

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

对于非 636 LDAPS 端口上的严格证书验证，请将 PEM CA certificate 编码为不含换行符的 Base64，并将输出用作 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；当前计划同步会通过该身份查找 Connector。

#按症状排查

#现场诊断工具

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

#外部：Linux 和 macOS LDAP 工具

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

下面的私有 CA 环境变量已在 Linux OpenLDAP client 上验证。macOS 内置的 /usr/bin/ldapsearch 和 /usr/bin/ldapwhoami 使用的是 macOS 系统信任库；请使用 Linux 诊断主机或 Pod，或者先在 macOS Keychain 中配置 CA，然后再使用这些内置 client。

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

下面的查询示例使用普通 LDAP，因此只匹配 insecureNoSSL: true 的 Connector。对于 LDAPS，请在运行每个示例之前，将 -H 值替换为对应行。若 LDAP certificate 由私有 CA 签名，诊断 client 也必须信任该 CA。对于 Linux OpenLDAP client，请按如下方式为每个 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 client 会失败并报错 unable to get local issuer certificate；使用 CA 文件后，同样的 bind 成功了。

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

nc -vz ldap.example.com 389

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

外部命令：验证 server、transport 和 bind account

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

外部命令：查找缺少建议身份的 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 身份的重复值

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

在评估其他候选身份属性时，请替换 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 certificate chain

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 命令行 client 无需 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 组件日志

以下 deployment 名称是当前 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 负责手动和计划同步、跳过的条目、组查找以及登录行为。