编辑
2026-11-16
随意记录
00
轻量目录访问协议(Lightweight Directory Access Protocol,简称 LDAP)是一套基于 TCP/IP 协议、用于访问和维护目录服务的开放标准协议。

规定了客户端和目录服务器之间,怎么认证身份、怎么查通讯录 / 组织架构、怎么增删改条目,所以所有支持 LDAP 的软件(Outlook、OA、打印机、VPN)都能对接所有符合 LDAP 标准的目录服务,不用每家单独写对接代码。


交互模式

纯「客户端请求 → 服务端响应」模式,服务端永远不会主动给客户端发消息。

  • 所有操作都由客户端主动发起:认证、查询、新增、修改、删除;

  • 服务端收到请求后处理,返回对应的结果;

  • 没有长连接推送、没有服务端主动通知

使用webhook,事件仅返回事件类型、userid 和部门 ID等关键信息,不包含姓名、手机号等额外敏感字段;如需完整信息,需用LDAP获取。‌

首次回调失败后,还有三次重试,三次重试全部失败,这条事件永久丢失



LDAP 的数据模型
1. 目录信息树(DIT)

所有数据组织成一棵倒挂的树,叫 Directory Information Tree,简称 DIT。

  • 最顶层是根节点;

  • 向下分层,比如按国家、公司、部门一层层分;

  • 最底层是具体的成员。

2. 条目(Entry)

树上的每一个节点,就叫一个条目,是 LDAP 的最小数据单元。

  • 一个条目对应一个现实实体:一个员工、一个部门;

3. 可分辨名称(DN)

每个条目的唯一身份证。 它是从叶子节点到根节点的完整路径,类似文件的绝对路径,全局唯一。

  • 示例:uid=zhangsan,ou=研发部,ou=5G事业群,dc=huali,dc=com

  • 示例:uid=zhangsan,ou=研发部,ou=5G事业群,o=华力

  • 规则:从左到右是「叶子 → 根」,用逗号分隔;

  • 类比文件系统:DN = C:\Users\张三\Documents 这种绝对路径。

4. 属性(Attribute)

条目里存的具体数据,类似数据库的「字段」,由「属性名 + 值」组成,一个属性可以有多个值。

  • 比如一个员工条目,有 cn(姓名)、mail(邮箱)、telephoneNumber(手机号)这些属性;

成员的标准属性

自定义通讯录客户端,可不完全遵守该标准,比如增加contacts扩展属性,里面存入联系方式的JSON

标准属性名

全称

含义

必要性

cn

Common Name

通用名(姓名全称)

必填,客户端默认的姓名显示字段

sn

Surname

姓氏

必填,inetOrgPerson 强制要求的属性

uid

User ID

用户唯一标识

协议规定可选填,但是实际必填,用户条目的唯一主键

mail

Mail

邮箱地址

选填

telephoneNumber

Telephone Number

办公 / 手机号码

选填

ou

Organizational Unit

所属部门

选填

displayName

Display Name

显示名

选填

部门的标准属性(自定义通讯录客户端,可不遵守该标准)

标准属性名

全称

含义

说明

ou

Organizational Unit Name

组织单元名称(部门名)

必填

description

Description

部门描述 / 备注

选填

telephoneNumber

Telephone Number

部门联系电话

选填

manager

Manager

部门负责人

选填,值为负责人的完整 DN

departmentNumber

Department Number

部门编号

选填

postalAddress

Postal Address

部门办公地址

选填

facsimileTelephoneNumber

Facsimile Telephone Number

传真号

选填

5. 对象类(ObjectClass)

属性的「模板」,规定了一个条目必须有哪些属性、可以有哪些属性。

  • 比如标准的 inetOrgPerson 对象类,规定了人员条目必须有姓(sn)、通用名(cn),可以有邮箱、电话、职位等;

6. Schema(模式)

所有对象类、属性类型、数据格式的总集合,相当于整个目录的「数据规范手册」,保证所有条目格式统一,不会乱存数据。





LDAP的操作类型

LDAP 协议一共定义了 7 种标准操作,覆盖目录的全生命周期,客户端只能发起这几种请求,服务端按规则响应。

1. Bind(绑定)

所有操作的第一步,相当于「登录认证」。

客户端和服务器建立 TCP 连接后,首先要发 Bind 请求,带上账号(DN)和密码,证明自己的身份。

  • 认证通过,才能执行后续操作;

  • 也支持匿名 Bind,就是不用账号密码,适合公开通讯录场景。

2. Search(查询)

最核心、使用频率最高的操作。

客户端在请求里指定 4 个关键参数,服务端返回匹配的条目:

  1. Base DN:从树的哪个节点开始查(查询起点)

  2. 查询范围:只查这个节点本身 / 只查直接子节点 / 查整个子树

  3. 过滤器:查询条件,比如「姓名姓张、部门是研发部」

  4. 返回属性:要哪些字段,比如只要姓名和邮箱

3. Add(新增)

在指定父节点下添加一个新条目,必须符合 Schema 规则,缺了必填属性会报错。

4. Delete(删除)

删除一个指定条目。注意:如果条目下面还有子节点,必须先删子节点,才能删父节点,和删文件夹的逻辑一样。

5. Modify(修改)

修改条目的属性值:新增属性、删除属性、修改已有属性的值。

6. ModifyDN(重命名/移动)

修改条目的 DN,实现两个功能:

  • 给条目改名(比如把 uid 从 zhangsan 改成 zhangsan01);

  • 把条目移动到树的另一个位置(比如员工从研发部调到产品部)。

7. Unbind(解绑)

断开连接,相当于退出登录、关闭连接。

LDAP查询过滤器语法(是否需要支持分页?)

LDAP 的查询条件有一套固定的语法(过滤器),用的是前缀表达式,服务端需自行转为对应的SQL查询。

LDAP 的查询效果 = Base DN(查询起点) + 查询范围(Scope) + 过滤器,三者共同决定最终结果。


查询起点:ou=5G事业群,dc=huali,dc=com 表示从5G事业群这个部门作为查询起点


**查询范围:**包括 base(当前节点),one(直接子节点),sub(递归查 Base DN 下所有层级的子节点)

过滤器基础规则
  • 最简单的条件:(属性名=值)

  • 与条件(同时满足):(&(条件1)(条件2)(条件3))

  • 或条件(满足一个就行):(|(条件1)(条件2))

  • 非条件(取反):(!(条件))

  • 模糊匹配:用 * 通配符,比如 (cn=张*) 表示姓张

常用例子
  1. 查姓名叫张三的人:(cn=张三)

  2. 查研发部所有员工:(&(objectClass=inetOrgPerson)(ou=研发部))

  3. 查姓张或者手机号138开头的人:(|(cn=张*)(telephoneNumber=138*))

LDAP协议底层
  • 二进制编码:用 ASN.1 BER 标准编码的二进制数据,体积小、解析效率高,必须用专门的库来编解码。

  • 请求-响应一一对应:每个请求都有一个消息ID,响应带着相同的ID回来,和 HTTP 的请求-响应逻辑一致。

Golang服务端库
github.com/jimlambrt/gldap

api文档地址 https://pkg.go.dev/github.com/jimlambrt/gldap


LDAP本身不支持事件通知机制,需要使用webhook或者消息队列实现 事件机制


Golang客户端库

github.com/go-ldap/ldap/v3

api文档地址 https://pkg.go.dev/github.com/go-ldap/ldap/v3




是否需要考虑请求者的权限(包括访问者控制、分机号白名单)?还是全量返回?