在Ruby生态中对接轻量目录访问协议服务，最成熟的方案是使用net-ldap这个第三方库。它用纯Ruby实现了会话绑定、目录搜索、增删改以及StartTLS和LDAPS等加密方式，避免了调用系统命令行带来的运维复杂度。下面我们先看一个最基础但安全的连接建立方式，再逐步展开认证与查询逻辑。
建立TLS加密的LDAP连接
很多企业目录服务要求客户端必须使用加密通道，否则拒绝绑定操作。net-ldap支持两种加密模式：一种是在建立TCP连接后立即进行SSL握手，即LDAPS（默认端口636）；另一种是先用明文端口389连接，再发送StartTLS指令升级为加密通道。从运维兼容性看，StartTLS更灵活，因为同一端口既能接受明文也能升级加密，而LDAPS需要独立端口。
在Ruby代码中配置TLS时，最关键的是证书校验策略。如果简单将tls_options中的校验关闭，虽然本地调试能通，但生产环境会面临中间人伪造目录服务器的风险。正确做法是指定可信CA证书路径，并开启对端主机名校验。下面的示例展示了如何通过Net::LDAP.new传入加密参数，其中encryption键使用:simple_tls代表直接LDAPS，若用:start_tls则是升级模式。
require 'net-ldap'
ldap = Net::LDAP.new(
host: 'ldap.ipipp.com',
port: 636,
encryption: {
method: :simple_tls,
tls_options: {
ca_file: '/etc/ssl/certs/ca-bundle.crt',
verify_mode: OpenSSL::SSL::VERIFY_PEER,
ssl_version: :TLSv1_2
}
}
)
if ldap.bind
puts '加密连接建立成功'
else
puts '无法连接目录服务器'
end
上述代码明确限制了TLS版本不低于1.2，并加载了系统级CA文件。实际项目中，如果目录服务器使用内部私有CA签发证书，你需要把该私有CA的证书内容追加到ca_file指向的文件中，或者单独指定内部CA路径。这样Ruby的OpenSSL底层才会信任对端证书，完成双向身份确认前的单向校验。
基于简单绑定的用户认证实现
用户认证的本质是用账号对应的可分辨名称（DN）和密码向目录服务器发起绑定请求。很多系统并不直接暴露DN给用户，而是让用户提交邮箱或工号，此时需要先用一个具有搜索权限的服务账号查到该用户的DN，再用查到的DN加密码做二次绑定。不过在结构简单的场景下，也可以约定用户DN格式为uid=用户名,ou=people,dc=ipipp,dc=com，直接拼接后绑定。
net-ldap提供了bind_as辅助方法，可以在一次调用中完成搜索加绑定，也可以直接用auth设置DN与密码后调用bind。下面的例子演示了直接绑定模式：先设置认证凭据，再执行绑定，根据返回值判断密码是否正确。注意绑定失败不一定代表密码错，也可能是账号被锁或服务器策略限制，因此要捕获异常并打印错误信息辅助排查。
require 'net-ldap'
ldap = Net::LDAP.new(
host: 'ldap.ipipp.com',
port: 389,
encryption: { method: :start_tls, tls_options: { ca_file: '/etc/ssl/certs/ca-bundle.crt' } }
)
ldap.auth 'uid=zhangsan,ou=people,dc=ipipp,dc=com', 'user_password_123'
begin
result = ldap.bind
if result
puts '用户认证通过'
else
puts '认证失败，凭据错误'
end
rescue Net::LDAP::Error => e
puts "目录服务异常: #{e.message}"
end
如果希望减少硬编码DN的风险，可以采用bind_as方式：用一个只读管理员账号先查到用户条目，再在该条目上做密码验证。这种方式对用户更友好，登录时只需输入工号。但代价是需要维护一个服务账号的密码，并且搜索过滤器要写得严谨，防止注入式查询。例如过滤字符串应当用数组参数化，而不是字符串拼接。
目录查询与组织结构遍历
目录查询是LDAP最强大的能力之一。通过基础DN（base）和搜索范围（scope），可以列出某个组织单元下的所有用户，或者根据属性过滤出特定群体。常见的scope有Net::LDAP::SearchScope_BaseObject（仅基节点）、SingleLevel（直接子节点）和WholeSubtree（整棵子树）。在人员同步场景中，通常使用WholeSubtree拉取部门全部成员。
下面的代码展示了如何查询某个OU下所有启用的用户，并提取其邮件和姓名。过滤器使用Net::LDAP::Filter构造，避免手动拼接字符串。同时设置attributes参数只返回需要的字段，减少网络开销。查询结果是一个条目数组，每个条目用符号方法读取属性，属性值一般为数组，需要取第一个元素。
require 'net-ldap'
ldap = Net::LDAP.new(
host: 'ldap.ipipp.com',
port: 636,
encryption: { method: :simple_tls, tls_options: { ca_file: '/etc/ssl/certs/ca-bundle.crt' } }
)
ldap.auth 'cn=readonly,dc=ipipp,dc=com', 'ro_password'
base_dn = 'ou=people,dc=ipipp,dc=com'
filter = Net::LDAP::Filter.eq('objectClass', 'person') &
Net::LDAP::Filter.eq('userAccountControl', '512')
ldap.search(base: base_dn, filter: filter, scope: Net::LDAP::SearchScope_WholeSubtree) do |entry|
uid = entry.uid.first
mail = entry.mail.first
cn = entry.cn.first
puts "账号:#{uid} 姓名:#{cn} 邮箱:#{mail}"
end
在复杂企业中，目录往往存在嵌套OU。此时可以先用递归思路或多次搜索获取部门树，再对每个叶子节点并发查询。由于LDAP协议本身连接较轻，适当使用连接池或每个线程独立实例能提升批量同步效率。另外，若查询结果过大，服务器端可能限制返回条数，需要利用paged_searches分页参数分批拉取，防止单次查询超时或被截断。
常见错误与运维排查要点
在Ruby实现LDAP客户端时，最容易遇到的是证书校验失败和绑定返回模糊错误。证书问题通常表现为certificate verify failed，这时要确认CA文件确实包含签发服务器证书的链，且系统时钟误差在证书有效期内。有些内部服务使用自签名证书，直接把证书内容塞进ca_file即可，不要图省事关闭verify_mode。
另一个隐蔽问题是编码。目录中的属性值可能是UTF-8，而老版本Ruby或底层库在序列化时若未指定编码，会导致中文姓名乱码。建议在程序入口设置Encoding.default_external = Encoding::UTF_8，并在读取条目后主动调用force_encoding。此外，防火墙常只开放389或636之一，若连接超时，先用telnet或nc确认端口通断，再怀疑代码逻辑。把连接、绑定、搜索三步分开写日志，能迅速定位是哪一层失败。