Go LDAP 怎样对查询过滤器中的用户输入进行转义

在 Go LDAP 查询中，用户输入如果直接拼进 (uid=%s)，输入里的括号、星号或反斜杠就可能改变过滤器的含义。这个问题的正确落点不是“把字符串删干净”，而是把输入当作过滤器值，交给 ldap.EscapeFilter 按 LDAP 过滤器规则转义。

官方地址：https://pkg.go.dev/github.com/go-ldap/ldap/v3

固定属性名、操作符和基础 DN，只对用户输入调用 EscapeFilter，再把转义后的值放进固定模板；不要用 EscapeDN 代替它。

本文只讨论 github.com/go-ldap/ldap/v3 的过滤器值转义，不展开 LDAP 连接认证、权限设计或完整目录服务建模。

先把真正需要保护的资产画清楚

一次按用户名搜索，通常包含四类不同数据：基础 DN 决定搜索树，属性名决定查哪个字段，过滤器操作符决定匹配关系，用户输入只是属性值。前三类都应该由服务端代码固定，最后一类才是外部输入边界。

例如，业务想表达的是“在固定目录下查找 uid 等于某个值的用户”，那么可变部分只能是 uid 右侧的值。若把属性名也交给请求参数，调用方就可能改变查询字段；若把完整过滤器交给请求参数，转义一个值也无法约束整体语义。

用 EscapeFilter 处理过滤器中的用户值

官方文档说明，EscapeFilter 会处理 LDAP 过滤器中的特殊字符，包括 (、)、*、反斜杠以及规定范围内的 ASCII 控制字符。它的参数是“要作为值放入过滤器的字符串”，不是完整过滤器。

package directory

import (
    "fmt"
    "github.com/go-ldap/ldap/v3"
)

func userFilter(username string) string {
    // 属性名、连接符和括号由服务端固定，外部输入只作为 uid 的值。
    escaped := ldap.EscapeFilter(username)
    return fmt.Sprintf("(&(objectClass=organizationalPerson)(uid=%s))", escaped)
}

这里的关键不是 fmt.Sprintf 本身，而是格式化之前已经完成了值级转义。比如用户输入中出现 *，它应当被当作用户名里的普通字符，而不是 LDAP 的通配匹配符；括号也不能再额外闭合或打开过滤器分支。

把转义值接入 SearchRequest

生成过滤器后，再把它交给 NewSearchRequest。示例保留了连接关闭、搜索错误和结果数量判断，避免把“过滤器写对”误认为“查询一定安全”。下面的代码是文章示例，不代表已经连接到真实 LDAP 服务执行。

func findUser(conn *ldap.Conn, username string) (*ldap.Entry, error) {
    // 只允许固定的 uid 查询，避免调用方提交完整 LDAP 过滤器。
    filter := userFilter(username)
    request := ldap.NewSearchRequest(
        "ou=people,dc=example,dc=com",
        ldap.ScopeWholeSubtree,
        ldap.NeverDerefAliases,
        2,
        5,
        false,
        filter,
        []string{"dn", "uid", "mail"},
        nil,
    )

    result, err := conn.Search(request)
    if err != nil {
        // 将 LDAP 错误交给上层，日志不要直接记录原始用户名。
        return nil, fmt.Errorf("search directory: %w", err)
    }
    if len(result.Entries) != 1 {
        // 0 条或多条都不能被当成唯一身份继续处理。
        return nil, fmt.Errorf("expected one directory entry, got %d", len(result.Entries))
    }
    return result.Entries[0], nil
}

结果数量限制是业务控制，不是转义的替代品。它可以减少“多个账号都匹配”时误选身份的风险，但不能修复输入改变过滤器语义的问题。

三个容易混淆的边界

过滤器值与 DN 不是一回事。EscapeFilter 对应 RFC 4515 的过滤器字符串；EscapeDN 对应 RFC 4514 的 Distinguished Name。用户输入若要作为 DN 的一部分，应该按 DN 语法处理；不能因为两者都叫“转义”就互换。

不要转义后再把它当完整过滤器。正确方式是固定模板加一个转义值，例如 (&(objectClass=organizationalPerson)(uid=%s))。不要接受一个名为 filter 的请求参数，然后试图用 EscapeFilter(filter) 让任意完整表达式变安全。

属性名和日志也要单独管。属性名应使用白名单映射，例如前端只能选择 uid 或 mail，不能直接拼接请求里的字段名。日志记录查询类型、结果数量和请求追踪标识即可，避免写入原始用户名、完整过滤器或绑定凭据。

• 固定基础 DN、属性名和运算结构。
• 只对进入过滤器值位置的用户输入调用 ldap.EscapeFilter。
• 将 0 条、多条和 LDAP 错误分别处理，不把结果数量检查当作输入防护。
• 涉及 DN 时改用 DN 语法对应的处理方式，避免跨语法复用转义函数。

发布前的复查清单

1. 搜索模板中的属性名、括号和操作符是否全部来自代码常量？
2. 用户输入是否只经过一次 EscapeFilter，并且没有被当成完整过滤器再次拼接？
3. 代码是否把连接错误、0 条结果和多条结果分开处理？
4. 是否避免把原始输入、完整过滤器和密码写入日志？
5. 若查询对象是 DN，是否明确使用了 DN 对应的转义规则？

相关问题

EscapeFilter 能限制用户只能查 uid 吗？不能。它只处理值的过滤器语法，属性名和查询模板仍必须由服务端固定。

为什么不直接删除括号和星号？删除会改变合法用户名或目录值的含义，按 LDAP 过滤器规则编码更能保留原值语义。