本指南旨在为管理员提供一套标准的排障流程，用于解决用户在使用 LDAP/AD 账号登录飞连时遇到的各类问题，如“用户名密码错误”、“用户不存在”等。

请先阅读身份认证常见问题，确认您遇到的问题是否已有对应的快速解决方案。若上述文档未能解决您的问题，请遵循本文提供的排查步骤进行深度诊断。

LDAP/AD 认证失败问题，绝大多数源于飞连后台的配置与您 LDAP/AD 服务器的实际情况不匹配。建议按照以下顺序进行排查。

步骤一：基础配置核对

此步骤旨在通过飞连管理后台的 UI，快速验证最核心的连接配置。

1. 登录飞连管理后台，导航至身份 ＞ 账号配置 ＞ 认证源管理。
2. 找到并进入您的 LDAP 认证源配置页面。
3. 逐一核对以下基础参数，确保其与您的 LDAP/AD 服务器的实际配置完全一致：
   • LDAP/AD 类型：​确认选择的是 LDAP还是 Windows AD。
   • 服务器地址/端口：​确保地址和端口正确无误。
   • Base DN：​确保填写的 OU 路径在您的 LDAP/AD 目录中真实存在。
   • 管理员 DN / 密码：​确保用于绑定的管理员账号格式正确（通常为完整的 DN 格式）且密码有效。

   说明

   更多配置说明，参看在飞连管理后台配置第三方登录配置文档。

4. 完成核对后，务必点击页面下方的连通性检测按钮。
   • 如果检测成功，表明飞连服务器与 LDAP 服务器之间的基础网络和绑定认证已通畅，问题可能出在后续的用户属性配置上。请继续步骤二。
   • 如果检测失败，表明存在网络不通、端口不通、或管理员账号密码错误等基础连接问题。请重点排查服务器地址和防火墙策略。

步骤二：用户属性与映射配置核对

当基础连通性正常，但用户依然无法登录时，问题通常出在“如何找到并识别用户”的配置上。

1. 在 LDAP 认证源配置页面，继续核对以下用户相关属性。
   • 用户唯一标识：​确保填写的字段（如 uid, sAMAccountName, mail）是您期望用户用来登录的“用户名”字段，并且该字段在 LDAP/AD 中真实存在。
   • 用户对象类：​确保填写的对象类与您 AD 中用户条目的objectClass属性一致。
2. 检查高级配置。
   1. 切换到高级配置 ＞ 属性映射策略，检查您配置的字段映射关系是否正确。错误的映射可能导致飞连在认证成功后，无法将 LDAP 用户与飞连内的用户身份正确关联。
   2. 检查唯一标识优先级配置，确保您在此处用作匹配依据的 LDAP 字段（例如 uid, mail），确实已在您的 LDAP/AD 数据源同步的字段映射中被正确配置并同步。

步骤三：管理员账号权限验证

如果以上所有 UI 配置均核对无误，问题可能源于管理员权限不足。

1. 飞连提供了权限探测工具。请导航至身份 ＞ 账号配置 ＞ 数据源同步，新建一个临时的 AD 数据源。
2. 在此新数据源的配置页面，使用您在认证源中配置的同一个管理员账号、密码和 Base DN，然后点击第三方权限探测。
3. 此工具可以验证该账号是否具备足够的权限来搜索和读取用户条目。

步骤四：命令行深度诊断

如果以上所有 UI 配置均核对无误，您需要登录服务器后台，使用命令行工具进行更底层的诊断。

使用命令行工具 ldapsearch 模拟查询

• 命令语法
  ldapsearch 的基本命令结构如下：

  ldapsearch [options] "filter" [attributes...]
  

• 核心参数说明

  参数	含义	示例
  -H <uri>	指定 LDAP 服务器的地址，包含协议、主机名/IP 和端口。 协议：ldap:// （非加密） 或 ldaps:// （加密）	ldaps://ldap.mycompany.com:636
  -p <port>	（可选）单独指定端口号（如果-H中未指定）。	389
  -x	使用简单认证（Simple Authentication）。	/
  -D <dn>	用于绑定（登录）到 LDAP 服务器的管理员账号 DN。	"cn=bind_user,ou=users,dc=example,dc=com"
  -w <passwd>	与 -D 参数配对的管理员账号密码。	"MySecretPassword"
  -b <dn>	指定搜索的基础 DN（Base DN），即搜索的起始点。	"ou=staff,dc=example,dc=com"
  filter	用于筛选搜索结果的过滤器。必须用引号包裹。	"(uid=testuser)"
  attributes	（可选）指定要返回的属性。若不指定，则返回所有属性。	cn mail memberOf

• 使用示例
  通过 SSH 登录到您的飞连服务器。执行以下命令，注意将示例中的服务器地址、DN 路径、密码等替换为您自己的实际值。

  • 示例 1：测试基础连接与管理员凭据
    此命令用于验证您在飞连后台配置的 LDAP 服务器地址、端口、以及管理员 DN 和密码是否正确。

    ldapsearch -H ldaps://<您的内网LDAP地址>:<端口> \
        -x \
        -D "<您的Bind DN>" \
        -w "<您的密码>" \
        -b "<您的Base DN>" \
        "(objectclass=*)" \
        cn
    

    预期结果：如果连接和认证成功，命令将返回您指定 Base DN 目录下部分条目的 cn 属性。如果报错，请检查命令中的各项参数是否与您在飞连后台的配置完全一致，并确认执行命令的机器与您的 LDAP 服务器之间网络通畅。

  • 示例 2：验证用户查找配置
    此命令用于模拟飞连查找一个具体用户（例如testuser）的过程，以验证“用户对象类”和“用户唯一字段”的配置是否正确。

    ldapsearch -H ldaps://<您的内网LDAP地址>:<端口> \
        -x \
        -D "<您的Bind DN>" \
        -w "<您的密码>" \
        -b "<您的Base DN>" \
        "(&(objectClass=<您的用户对象类>)(<您的用户唯一字段>=testuser))"
    

    预期结果：如果能成功返回 testuser 的完整信息，说明您在飞连后台配置的用户查找相关参数是正确的。如果返回为空，请检查您的 Base DN、用户对象类或过滤器语法。

使用 tcpdump 进行网络抓包分析

您可以通过tcpdump捕获飞连服务器与 LDAP 服务器之间的原始网络通信数据包，以进行最底层的故障分析。

1. 确认目标信息
   登录飞连管理后台，在身份 ＞ 账号配置 ＞ 认证源管理 ＞ LDAP 中，确认您要排查的 LDAP 服务器的 IP 地址和端口号。
   
2. 执行抓包命令

   1. 通过 SSH 登录到您的飞连服务器后台。

   2. 执行以下命令开始抓包。请将命令中的占位符替换为您的实际值。

      # 将 <ldap_server_ip> 替换为您的LDAP服务器IP
      # 将 <port> 替换为您的LDAP端口
      # 将 <output_file.pcap> 替换为您希望保存的文件名
      
      sudo tcpdump -i any host <ldap_server_ip> and port <port> -nnv -s0 -w /tmp/<output_file.pcap>
      

      • 命令参数说明：
        • -i any：监听所有网络接口，避免因不确定出口网卡（如eth0）而抓不到包。
        • host ... and port ...：过滤器，确保只抓取与目标 LDAP 服务器和端口相关的流量。
        • -nnv：以更详细、不做名称解析的方式显示信息。
        • -s0：抓取完整的数据包，而不是截断。
        • -w /tmp/...：将抓取的数据包以二进制格式写入指定的文件，以便后续使用 Wireshark 分析。

注意：​如果您的飞连是高可用（主备）部署，您需要在两台服务器上同时执行此抓包命令。

3. 复现问题
   • 在tcpdump运行的同时，请用户再次尝试登录，或在飞连后台点击“连通性检测”。
   • 问题复现后，返回 SSH 终端，按 Ctrl + C 停止抓包。
4. 下载并分析
   • 使用scp等工具，将服务器上的 /tmp/ldap_capture.pcap 文件下载到本地。
   • 使用 Wireshark 工具打开该文件进行分析。在 Wireshark 的显示过滤器中输入 ldap 可快速筛选出相关协议包。
5. 分析要点
   • TCP/TLS 握手：​检查网络连接是否正常建立，对于ldaps://，检查 TLS 握手是否成功。
   • 绑定请求/响应（bindRequest/bindResponse）：​确认bindDN是否正确，并查看bindResponse的resultCode。invalidCredentials(49)通常表示凭据错误，其附加信息（如data 52e）可能提供更详细的错误原因。
   • 搜索请求/结果（Search Request/Result）：​检查baseObject (Base DN) 和 filter是否符合预期，以及服务器是否返回了正确的用户条目或错误代码（如noSuchObject(32)）。
   

配置 LDAP/AD 认证，需要完全按照 LDAP 上的参数进行配置。

• 飞连认证渠道工程师：请通过飞书搜索飞连 FOC，提交工单处理。
• 企业用户：请通过火山引擎官网提交工单处理。