#LDAP 管理

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

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

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

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

#开始之前

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

• 从 ACP 集群可访问的 LDAP 服务器主机名和端口。
• 具有目标用户和组只读权限的 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 执行目录查询，其 DNS、路由、防火墙和证书信任应与 ACP 集群等效。笔记本电脑查询可作为有用的初步证据，但 ACP Connector 创建和同步仍然是权威的集群侧检查。

#2. 查找目录根

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

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

在运行子树查询之前，请先使用外部 base-scope 查询确认绑定账户可以读取候选 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. 选择身份和登录属性

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

#6. 逐步构建 User Filter

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

1. 使用 objectClass 选择用户条目。
2. 使用 (attribute=*) 约束 ACP 身份和登录属性必须存在。
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. 确定组成员模型

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

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

ACP 会按 (<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。ACP 在创建期间会针对采样组条目验证 member。更宽泛的 (objectClass=group) Filter 可能会采样到不返回 member 属性的空组，从而拒绝一个原本有效的映射。

#添加 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 表达式。ACP 会以 UTC 评估该规则。
9. 单击 Add。

#控制台字段参考

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

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

#验证集成

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

#同步与生命周期

#首次登录同步

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

#手动同步

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

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

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

#自动同步

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

#更新 Connector

当服务器、搜索边界、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 * * *"
    # 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 字段：

连接和传输字段：

userSearch 字段：

groupSearch 字段：

当 ACP 不需要组同步时，请完全省略 groupSearch。

将传输标志作为一个整体来选择：

上面的 Active Directory 模板使用的是 ACP 验证过的普通 LDAP 传输。普通 LDAP 不会在网络上传输保护 bind 密码。仅当客户的网络和安全策略允许时才使用它。当需要 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；当前的定时同步会按该标识查找 Connector。

#按症状排查

#站点诊断工具

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

#外部：Linux 和 macOS LDAP 工具

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

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

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

下面的查询示例使用普通 LDAP，因此只匹配 insecureNoSSL: true 的 Connector。对于 LDAPS，请在运行每个示例之前将 -H 值替换为匹配的行。如果 LDAP 证书由私有 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 搜索行为。检查 LDAPS 端口可达性时，请改用端口 636。

外部命令：验证服务器、传输和 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

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

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 命令行 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 组成员查找

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 负责手动和定时同步、跳过的条目、组查找以及登录行为。