先聊点实际的做Windows桌面开发的朋友早晚会在项目里碰到“对接公司域账号”这种需求。我手头正好维护着一个Delphi写的内部工具客户要求把本地账号密码改成从Active Directory验证——用户在登录框输入域账号程序去域控上校验通过之后还要把他的部门、邮箱、手机号拉回来显示到主界面。折腾了一圈发现Delphi访问AD并不是非要引入重量级第三方组件Windows自带的ADSI和wldap32.dll就能把这件事做得挺干净真正要花心思的反而是把LDAP这条线掰扯明白。这篇文章不打算铺开讲太多理论主要把我在实际项目里验证过的两条技术路线贴出来一种走ADO配合ADSI的OLE DB Provider代码最简单另一种直接调用Windows自带的LDAP C APIwldap32.dll可控性最强。后面还会整理我在登录认证、属性读取、中文乱码和大结果集分页上踩过的坑给同样在Delphi和AD之间折腾的朋友一份能直接抄作业的方案。1. 先把几个概念理顺AD、LDAP和域控的区别很多刚接触这块的同学会直接混着叫说“去AD里查一下”又说“走LDAP连一下”其实这两个词说的是不同层面的东西。Active Directory是微软在Windows Server上实现的目录服务它存储了整个域内的用户、组、计算机、组织单元OU这些对象同时承担身份认证的功能。而LDAPLightweight Directory Access Protocol是访问目录服务的一套标准协议监听在389端口加密走636。AD实现了LDAP协议所以我们可以用LDAP客户端去查询和操作AD里的数据。换句话说LDAP是“怎么问”AD是“去哪儿问、存了什么”。这个区分之所以重要是因为你在Delphi里写代码时选的是“LDAP客户端”还是“AD专用接口”决定了后面代码的移植性和复杂度。如果只是针对微软AD场景直接用ADSIActive Directory Service Interfaces最省事但如果将来要对接OpenLDAP或者其他LDAP目录服务写一套标准的LDAP绑定和查询逻辑才是通用解。AD里几个基础概念也必须心里有数否则后面写过滤器和解析结果时会被绕晕缩写全称含义DCDomain Component域名组成部分比如dcexample,dccomOUOrganizational Unit组织单元相当于文件夹用来归类管理对象CNCommon Name对象的通用名比如用户显示名、组名DNDistinguished Name对象在目录树中的完整路径比如CN张三,OU研发部,DCexample,DCcomsAMAccountNameSecurity Account Manager Account Name用户登录名域内短格式比如zhangsanLDAP的查询过滤器是类SQL的写法不查不知道一查就发现它在字符串拼接上特别考验细心。比如想要查所有正常用户((objectClassuser)(objectCategoryperson))想要进一步限定某个组((objectClassuser)(objectCategoryperson)(memberOfCN开发组,OUGroups,DCexample,DCcom))这个过滤器是纯字符串Delphi与LDAP服务器交互的时候整个过滤器作为一个长字符串传过去。后面讲到代码时你会发现凡是能写成常量、能调试打印的都比直接封装死调用的方案更容易排查问题。2. Delphi访问AD的几条路线怎么选我在刚开始做这个功能时第一反应是去搜“Delphi LDAP组件”确实能找到一些但评估下来发现要么是商业授权要么是太老没有维护要么内部封装得太黑盒。后来静下心梳理了一下Delphi环境下访问AD可以归纳为四条路各有取舍。先说结论我看完对比表之后如果你只是需要快速搞定一个内部工具走ADOADSDSOObject如果你需要精细控制查询过程、高性能遍历大量对象或者有跨平台、通用LDAP目录的潜在需求直接调wldap32.dll更踏实。方案技术本质优点缺点方案一ADO ADSDSOObject通过ADSI的OLE DB Provider暴露为数据源代码量极少像查数据库一样执行查询Delphi里用OleVariant就能操作门槛低查大结果集时内存占用高对过滤器和分页控制粒度粗依赖COM和ADSI环境方案二直接调用wldap32.dll调用Windows自带LDAP C API可控性最强支持分页、异步、SSL/TLS扩展不仅是ADOpenLDAP等也适用异步和性能上限高函数声明比较繁琐需要自己管理内存和指针类型出错信息需要对照LDAP错误码方案三ADSI COM接口IDirectorySearch等使用COM接口获取目录搜索功能保留了ADSI的封装优势又能精细控制搜索选项在Delphi里引用COM接口头文件比较痛苦大多数接口方法用到VARIANT或指针数组声明和调试成本不小方案四第三方LDAP组件封装了LDAP协议或调用底层库用起来最简单很多支持跨平台依赖具体厂商闭源定制难许可证和稳定性需要评估有些老旧组件在Win10/Server 2019上兼容性堪忧我实际选的是方案一和方案二结合用户登录认证和简单的人员信息查询走ADOADSDSOObject因为代码量小而同步组织架构、批量拉取几千个用户时走wldap32.dll因为可以在客户端做分页和字段裁剪内存可控。这里我多说一句如果你的应用最终要部署在纯内网环境域控和客户端都在同一个Windows域里DNS解析通常没问题。但是如果程序要从外网或者非域环境访问AD必须确认你拿到的域控地址能被解析到且389端口在防火墙上放行了。LDAP Bind时最常见的“服务器不可用”错误十次里有八次是网络和端口层面的问题不是代码错。3. 实操用ADO ADSDSOObject快速实现查询这条路线对Delphi老程序员来说最友好因为代码模式跟用ADO连SQL Server很像。核心思路是ADSI给OLE DB提供了一个挨踢Provider名字叫ADSDSOObject你把它当作数据库驱动来用就可以。写代码前有几个前置要点必须初始化COM。Delphi的VCL通常在Application初始化时已经做了但如果你在后台线程或纯控制台项目里记得主动调用CoInitialize。OleVariant变量要声明并通过CreateOleObject(ADODB.Connection)创建ADO连接对象。查询字符串有一套固定语法说白了就是一个“LDAP风格的SQL”。下面是一段完整的示例作用是在域控上查询所有用户并读取几个常用属性uses System.SysUtils, System.Variants, ComObj, ActiveX, Windows; procedure QueryADUsers(const ADServer, Domain, User, Pass: string); var Conn, RS: OleVariant; query: string; displayName, mail, dept: string; begin CoInitialize(nil); try Conn : CreateOleObject(ADODB.Connection); Conn.Provider : ADSDSOObject; // 第一个参数是AD的LDAP根路径第二个是域账号第三个是密码 Conn.Open( Format(LDAP://%s/DCexample,DCcom, [ADServer]), Format(%s\%s, [Domain, User]), Pass ); query : LDAP://DCexample,DCcom; ((objectClassuser)(objectCategoryperson)); sAMAccountName,displayName,mail,department; subtree; RS : Conn.Execute(query); while not RS.EOF do begin // 注意字段可能为空读取前用VarIsNull做保护 if not VarIsNull(RS.Fields[displayName].Value) then displayName : VarToStr(RS.Fields[displayName].Value) else displayName : ; if not VarIsNull(RS.Fields[mail].Value) then mail : VarToStr(RS.Fields[mail].Value) else mail : ; if not VarIsNull(RS.Fields[department].Value) then dept : VarToStr(RS.Fields[department].Value) else dept : ; // 这里把数据塞进你自己的结构或列表里 OutputDebugString(PChar(displayName | mail | dept)); RS.MoveNext; end; RS.Close; Conn.Close; finally CoUninitialize; end; end;这段代码里有几个细节值得单独讲查询字符串的组成。它被分号分割成四段根路径、过滤条件、返回属性、搜索范围。第一段用尖括号包住LDAP根路径这是ADSDSOObject特有的语法要求不是随便写的。搜索范围支持base、onelevel、subtree三种查询整个域的用户的例子必须用subtree否则只能在当前节点这一层生效什么都查不到。字段空值处理。AD里很多对象的属性本来就是空的比如一个没填手机号的用户。用VarIsNull判断之后再转字符串不然一个VarToStr直接打在空Variant上会有异常。这个是我实际测试时踩到的实际报错尤其批量执行时一次异常整段查询就断了。关于连接参数。Conn.Open括号里的第二、第三个参数传的是域账号和密码这里账号格式建议写DOMAIN\user密码就是纯文本。如果你的程序跑在已经加入域的机器上并且当前Windows登录用户有权限Open时可以只传第一个参数后两个留空串走客户端本机凭证。但在服务器或非域环境下还是老老实实传账号密码免得登录态不可用。用ADO方式的局限性在于它拿回的是一个二维结果集所有属性都被展开成列。如果你想读取嵌套属性或者多值属性比如memberOf这种一个用户属于多个组的属性ADO方式处理起来就会有点别扭通常还得回到ADSI的接口层面去逐条取。4. 进阶直接调wldap32.dll的LDAP C API如果业务场景要求批量同步几千上万个用户或者需要自己控制查询的每一层细节我推荐直接用Windows自带的LDAP动态库wldap32.dll。这个库从Windows 2000开始就随系统提供稳定性和兼容性都经历过大量生产环境验证。在Delphi里调用它的方式是需要自己写外部函数声明第一次看着会有点头皮发麻但写熟之后其实就是一套固定模式。下面是我在项目里用的核心声明const LDAP_VERSION3 3; LDAP_OPT_PROTOCOL_VERSION $31; LDAP_AUTH_SIMPLE $80; LDAP_AUTH_NEGOTIATE $400; LDAP_SCOPE_BASE 0; LDAP_SCOPE_ONELEVEL 1; LDAP_SCOPE_SUBTREE 2; type PLDAP Pointer; PLDAPMessage Pointer; TLDAPEntry Pointer; TLDAPValues PPAnsiChar; // 连接与绑定 function ldap_init(HostName: PAnsiChar; PortNumber: Cardinal): PLDAP; stdcall; external wldap32.dll; function ldap_set_option(ld: PLDAP; option: Integer; optdata: Pointer): Cardinal; stdcall; external wldap32.dll; function ldap_bind_s(ld: PLDAP; dn: PAnsiChar; cred: PAnsiChar; method: Cardinal): Cardinal; stdcall; external wldap32.dll; function ldap_unbind(ld: PLDAP): Cardinal; stdcall; external wldap32.dll; // 查询与遍历 function ldap_search_s(ld: PLDAP; base: PAnsiChar; scope: Cardinal; filter: PAnsiChar; attrs: Pointer; attrsonly: Cardinal; res: Pointer): Cardinal; stdcall; external wldap32.dll; function ldap_first_entry(ld: PLDAP; res: PLDAPMessage): TLDAPEntry; stdcall; external wldap32.dll; function ldap_next_entry(ld: PLDAP; entry: TLDAPEntry): TLDAPEntry; stdcall; external wldap32.dll; // 取属性值 function ldap_get_values(ld: PLDAP; entry: TLDAPEntry; attr: PAnsiChar): TLDAPValues; stdcall; external wldap32.dll; function ldap_count_values(vals: TLDAPValues): Cardinal; stdcall; external wldap32.dll; function ldap_msgfree(res: PLDAPMessage): Cardinal; stdcall; external wldap32.dll; function ldap_err2string(err: Cardinal): PAnsiChar; stdcall; external wldap32.dll;声明完之后一个典型的查询流程可以拆成四步初始化会话、设置协议版本、绑定身份、执行搜索。第一步初始化LDAP会话。ldap_init返回一个会话句柄你所有后续操作都基于它var ld: PLDAP; begin ld : ldap_init(PAnsiChar(AnsiString(192.168.1.10)), 389); if ld nil then raise Exception.Create(LDAP初始化失败请检查网络或服务器地址); end;这里有个中文使用者常踩的坑wldap32.dll的传统API是ANSI版Delphi 2009以后默认字符串是Unicode直接传string给PAnsiChar参数时IDE会提示类型不匹配警告甚至编译报错。我建议在传参的地方统一用PAnsiChar(AnsiString(...))包一层确保编码转换是显式的不要依赖隐式转换。如果AD里存了中文姓名等非ASCII字符这种显式转换的位置尤其要检查清楚。第二步设置LDAP协议版本。AD默认要求LDAP v3而wldap32.dll初始化后的默认版本却是V2。不设置这一项后面search十有八九报“协议版本不支持”pascal var version: Cardinal; begin version : LDAP_VERSION3; ldap_set_option(ld, LDAP_OPT_PROTOCOL_VERSION, version); end;ldap_set_option的第三个参数是一个指针指向你设置的整型值。这里不能用常量直接传而是要定义一个变量取地址。第三步绑定身份。绑定在LDAP里就是“登录”的意思告诉服务器我是谁。可以用简单用户名格式也可以用UPN我建议用userexample.com或者DOMAIN\user这两种格式域控都能识别var err: Cardinal; begin err : ldap_bind_s(ld, PAnsiChar(AnsiString(adminexample.com)), PAnsiChar(AnsiString(Password_123)), LDAP_AUTH_SIMPLE); if err 0 then raise Exception.Create(StrPas(ldap_err2string(err))); end;有人会问为什么不直接用用户的DN来做绑定因为DN里往往带CN和OU有中文逗号转义的问题写成userdomain干净得多。AD在LDAP简单绑定时对UPN格式的支持很友好。第四步搜索。ldap_search_s是同步阻塞式搜索从开始查到最后一条结果返回后才结束。相比ADO方式的查询字符串C API的搜索参数更直观基准DN、搜索范围、过滤器、返回属性列表。如果你不需要限制属性数组把attrs参数传nil就行服务器会返回所有属性值var res: PLDAPMessage; entry: TLDAPEntry; vals: TLDAPValues; i: Integer; begin err : ldap_search_s(ld, PAnsiChar(AnsiString(DCexample,DCcom)), LDAP_SCOPE_SUBTREE, PAnsiChar(AnsiString(((objectClassuser)(objectCategoryperson)))), nil, 0, res); if err 0 then raise Exception.Create(StrPas(ldap_err2string(err))); entry : ldap_first_entry(ld, res); while entry nil do begin vals : ldap_get_values(ld, entry, sAMAccountName); if vals nil then begin for i : 0 to ldap_count_values(vals) - 1 do OutputDebugString(PChar(StrPas(vals[i]))); end; entry : ldap_next_entry(ld, entry); end; ldap_msgfree(res); ldap_unbind(ld); end;这里要特别提醒一点ldap_search_s的res参数必须传一个指针的地址res但不能事先初始化。如果重复使用要保证每次搜索前把res变量清空或者在搜索完调用ldap_msgfree释放。我一开始图省事没释放结果集跑了几百次之后内存直线上升后来才发现消息级的内存必须逐次清理。ldap_get_values返回的是PPAnsiChar本质上是一个以nil结尾的字符串数组。取值时先看是否为nil再通过ldap_count_values拿数量最后按数组下标遍历。注意它的下标从0开始遍历上限是数量减一。如果想读二进制属性比如用户头像thumbnailPhotoldap_get_values就不合适了要用ldap_get_values_len拿字节数组。不过日常开发里大多数属性都是字符串用ldap_get_values足够。5. 用户登录认证功能怎么写得既稳又安全做AD对接的项目最核心的功能就是登录认证。我在这个环节里试过几种方案最终选择的是“先用服务账号查询用户DN再用用户DN或UPN做二次绑定校验”的流程。我把这个流程细化一下程序配置里保存一个专用的只读服务账号低权限用它先连上AD。根据用户输入的登录名跑一个搜索找到对应用户的DN或者UPN。用这个用户自己的凭证绑定一次绑定成功说明密码正确。顺手把用户属性取回来。为什么不用“拿用户输入的账号密码直接绑定”这种方式因为如果用户账号本身被禁用、过期、锁定或者属于设定了“下次登录必须修改密码”的状态时直接绑定返回的错误码五花八门很难给用户一个明确的提示。先查再绑可以区分出“用户不存在”“账号被禁用”“密码错误”等不同场景对用户体验更好。用wldap32.dll实现认证过程大概是这样的function VerifyUserCredentials(const Server, UserName, Password: string): Integer; var ld: PLDAP; res: PLDAPMessage; entry: TLDAPEntry; err, bindErr: Cardinal; filter: string; dn: PAnsiChar; version: Cardinal; begin Result : -1; // -1表示内部错误0表示成功其他值参考LDAP错误码 ld : ldap_init(PAnsiChar(AnsiString(Server)), 389); if ld nil then Exit; try version : LDAP_VERSION3; ldap_set_option(ld, LDAP_OPT_PROTOCOL_VERSION, version); // 第一步用服务账号绑定 err : ldap_bind_s(ld, PAnsiChar(AnsiString(svc_readonlyexample.com)), PAnsiChar(AnsiString(ServiceReadOnlyPass)), LDAP_AUTH_SIMPLE); if err 0 then Exit; // 第二步按登录名搜索用户 filter : Format(((objectClassuser)(sAMAccountName%s)), [UserName]); err : ldap_search_s(ld, PAnsiChar(AnsiString(DCexample,DCcom)), LDAP_SCOPE_SUBTREE, PAnsiChar(AnsiString(filter)), nil, 0, res); if err 0 then Exit; entry : ldap_first_entry(ld, res); if entry nil then begin ldap_msgfree(res); Exit; // 用户不存在 end; dn : ldap_get_dn(ld, entry); ldap_msgfree(res); if dn nil then Exit; try // 第三步用用户自己的账号再次绑定 // 注意这里用UPN格式或直接取到的DN都行 bindErr : ldap_bind_s(ld, dn, PAnsiChar(AnsiString(Password)), LDAP_AUTH_SIMPLE); Result : bindErr; finally ldap_memfree(dn); end; finally ldap_unbind(ld); end; end;我不建议把密码以明文形式存在程序配置或数据库里。域账号对接本来就是要复用AD的密码策略再去设计一套自己的密码存储机制完全是给自己挖坑。安全写法是只保留服务账号的只读凭证调用时从加密配置文件或系统凭据管理器读取用户输入的密码只存活在内存变量里用完立即清空。另外如果程序面向公网或者半信任网络必须启用LDAPS636端口或者StartTLS否则用户密码是通过明文在网络上传输的抓个包就泄露了。在wldap32.dll里可以用ldap_sslinit替代ldap_init初始化SSL会话然后把传输模式设置为SSL。分两步设置ldap_sslinit命令连接636端口绑定前用ldap_set_option把LDAP_OPT_SSL或LDAP_OPT_ENCRYPT启用。实际生产环境里一般企业域控默认486端口用于全局编录GC如果要跨域查询所有对象初始化时用3268端口连GC会更快。这个我建议网上再查一下具体参数含义别直接用因为每个企业的域控配置不一定一致。6. 实战中绕不开的坑常见报错与排查记录这一节的内容是我在这个项目里反复调试后才总结出来的几乎每个都对应过真实的报错现场。先列一个速查表再逐个展开聊。现象常见原因排查思路连接超时或“服务器不存在”网络不同、端口未放行、DNS解析失败telnet/DevTool探测389端口确认域名解析到域控IP绑定返回0x51本地错误服务器不可达或账户权限不足换一个简单账户测试确认服务账号有LDAP读取权限绑定返回0x52无法联系服务器离线或防火墙拦截检查域控服务状态测试637/389端口绑定返回0x31凭据错误密码错误、账号过期或者被锁定用其他工具如AD用户和计算机验证账号状态Ldapl_s返回0x0B协议版本不对还在用V2把LDAP_OPT_PROTOCOL_VERSION设置为3中文姓名乱码代码内字符串编码不一致统一用UTF-8传参返回值按UTF-8解码属性明明存在但搜索不到过滤器写错或属性在AD里确实为空先不加过滤条件搜取回原始属性列表核对成员组信息读不出来memberOf可能不存在或权限受限检查服务账号是否有“读取所属组”权限第一个坑绑定时报“无法解译过滤器”。这是最常见的低级错误通常是过滤器的括号不匹配或者属性名写错。LDAP过滤器调试起来特别像正则表达式一个括号错位整条全废。我自己的习惯是先在调试窗口打印出完整过滤器字符串肉眼检查括号配对再复制到自带的LDAP浏览器工具里跑一遍。第二个坑中文乱码。这个项目在中文环境里跑用户姓名、部门名都有中文。用ADO方式读取时OleVariant拿到的BSTR本来就是UnicodeDelphi的string也是Unicode按理不会乱。但我遇到乱码的地方是在wldap32.dll的ANSI接口链路上。因为ldap_get_values返回的是PAnsiChar如果你直接用StrPas()转成stringDelphi会按当前代码页解释字节一旦AD里存的是UTF-8编码的字节串转出来的汉字就全乱了。解决方法是手动按UTF-8解码。我后来写了个小工具函数function Utf8ToStrEx(const Bytes: PAnsiChar): string; begin Result : TEncoding.UTF8.GetString( TBytes(Pointer(Bytes)^) ); end;不过要注意这个函数假设服务器返回的就是合法的UTF-8字节序列而且PBytes(Pointer(Bytes)^)这个写法有越界风险因为拿到的是一个以nil结尾的字符串缓冲区长度未知。实际开发中建议用ldap_get_values配合ldap_count_values先确定字节数再安全转换。如果你在Unicode版的Delphi上跑也可以直接考虑调用wldap32.dll的W系列函数比如ldap_get_valuesW省去编码转换的麻烦。第三个坑大结果集把内存吃爆。刚开始我写了一个搜索所有用户的命令不加任何分页条件测试域里只有2000多人时还不觉得后来跑到生产域数据量涨到几万程序瞬间卡死甚至崩溃。原因不是服务器查不出来而是ldap_search_s会把所有结果一次性带回客户端内存里。解决思路有两条第一条是让AD服务器端分页需要用LDAP_CONTROL_PAGED_RESULTS控件在ldap_search_ext_s时把分页大小和Cookie传进去第二条更简单——在客户端业务侧限制只查必需属性的子集并且按OU分批次查询。我最后用了第二种把组织架构里每个部门作为一个根节点分别搜索既满足了界面加载的分段显示需求又避免了单次大内存消耗。第四个坑AD时间戳属性看着是一串数字。AD里的whenCreated、lastLogon这类属性是Windows的FileTime格式长达18位的Int64值。如果你直接用StrPas去读显示出来就是一串怪异数字需要调用FileTimeToSystemTime转成日期格式。这个不算报错但很容易被忽略。第五个坑memberOf的多值处理。在ADO结果集里memberOf字段看起来可能是一个数组直接VarToStr取不出来完整数据。这是因为用户的所属组不止一个。我建议在取这个属性时走LDAP C API的ldap_get_values遍历返回值拿取每个组的完整DN再在界面上只显示CN部分。第六个坑分页时忘记释放Cookie。如果后来用到LDAP_CONTROL_PAGED_RESULTS搜索完成后必须释放分页Cookie否则服务器端会保留搜索状态占用资源。说实话这个控件在Delphi里的封装代码比普通搜索长不少但如果是大批量同步场景这一步省不掉。7. 一些零零散散的经验补充最后分享几个我在项目里沉淀下来的习惯谈不上深刻但确实能省下不少排查时间。写一个本地的AD查询小工具。我建议你哪怕产品最终没有管理界面也先写一个独立的控制台或窗口程序用来测试AD查询。这个小程序做到三件事输入服务器、账号、密码输入过滤器字符串把原始返回属性和值不带任何格式地打印出来。这个工具成了我后续排查一切问题的起点比直接在业务代码里打日志高效得多。毕竟AD对接问题的源头大多数在服务器端配置或者权限上能快速验证“这个账号到底能不能读到这个属性”比反复改业务代码要快得多。不要把查询逻辑散落在业务代码里。我后来把LDAP相关的连接、绑定、搜索、解析全部装进了一个独立的单元对外只暴露两个方法一个是TADConnection类的Login(UserName, Password)另一个是QueryUsers(Filter, Attribs)。这样如果未来要换第三方的LDAP库或者从ADSI切换到纯LDAP实现业务界面一层基本不用动。配置项要外置。服务器地址、端口、基础DN、服务账号这些放在一个ini或者JSON文件里不要硬编码到代码里。曾经有过一次客户方调整了域控的IP我硬编码在程序里的地址就失效了最后让实施同事改了配置文件手动替换才恢复。配置文件里的敏感字段建议做一层简单加密或者使用Windows凭据管理器虽然谈不上绝对安全但至少比明文强。我在这个项目的最后把整个“Delphi访问基于LDAP的Active Directory”的需求拆成了两层底层用wldap32.dll保证查询能力上层用ADO实现轻量级的快速接入。这么做的根本原因还是前面说的ADO方式写着舒服但控制力弱C API反着来但一旦把封装做好后面加功能几乎不用再动底层。Delphi这么多年过去生态确实不如以前热闹但面对Windows系统级的这些接口依然是宝刀未老原生的调用方式稳定可靠也没有多余依赖。如果你正在做类似的功能希望这篇整理能帮你少踩几个坑。 
长河君 · 2026/10/14 8:16:04 · 阅读 1.2k Delphi访问Active Directory：LDAP与ADSI两条实战路线
先聊点实际的做Windows桌面开发的朋友早晚会在项目里碰到“对接公司域账号”这种需求。我手头正好维护着一个Delphi写的内部工具客户要求把本地账号密码改成从Active Directory验证——用户在登录框输入域账号程序去域控上校验通过之后还要把他的部门、邮箱、手机号拉回来显示到主界面。折腾了一圈发现Delphi访问AD并不是非要引入重量级第三方组件Windows自带的ADSI和wldap32.dll就能把这件事做得挺干净真正要花心思的反而是把LDAP这条线掰扯明白。这篇文章不打算铺开讲太多理论主要把我在实际项目里验证过的两条技术路线贴出来一种走ADO配合ADSI的OLE DB Provider代码最简单另一种直接调用Windows自带的LDAP C APIwldap32.dll可控性最强。后面还会整理我在登录认证、属性读取、中文乱码和大结果集分页上踩过的坑给同样在Delphi和AD之间折腾的朋友一份能直接抄作业的方案。1. 先把几个概念理顺AD、LDAP和域控的区别很多刚接触这块的同学会直接混着叫说“去AD里查一下”又说“走LDAP连一下”其实这两个词说的是不同层面的东西。Active Directory是微软在Windows Server上实现的目录服务它存储了整个域内的用户、组、计算机、组织单元OU这些对象同时承担身份认证的功能。而LDAPLightweight Directory Access Protocol是访问目录服务的一套标准协议监听在389端口加密走636。AD实现了LDAP协议所以我们可以用LDAP客户端去查询和操作AD里的数据。换句话说LDAP是“怎么问”AD是“去哪儿问、存了什么”。这个区分之所以重要是因为你在Delphi里写代码时选的是“LDAP客户端”还是“AD专用接口”决定了后面代码的移植性和复杂度。如果只是针对微软AD场景直接用ADSIActive Directory Service Interfaces最省事但如果将来要对接OpenLDAP或者其他LDAP目录服务写一套标准的LDAP绑定和查询逻辑才是通用解。AD里几个基础概念也必须心里有数否则后面写过滤器和解析结果时会被绕晕缩写全称含义DCDomain Component域名组成部分比如dcexample,dccomOUOrganizational Unit组织单元相当于文件夹用来归类管理对象CNCommon Name对象的通用名比如用户显示名、组名DNDistinguished Name对象在目录树中的完整路径比如CN张三,OU研发部,DCexample,DCcomsAMAccountNameSecurity Account Manager Account Name用户登录名域内短格式比如zhangsanLDAP的查询过滤器是类SQL的写法不查不知道一查就发现它在字符串拼接上特别考验细心。比如想要查所有正常用户((objectClassuser)(objectCategoryperson))想要进一步限定某个组((objectClassuser)(objectCategoryperson)(memberOfCN开发组,OUGroups,DCexample,DCcom))这个过滤器是纯字符串Delphi与LDAP服务器交互的时候整个过滤器作为一个长字符串传过去。后面讲到代码时你会发现凡是能写成常量、能调试打印的都比直接封装死调用的方案更容易排查问题。2. Delphi访问AD的几条路线怎么选我在刚开始做这个功能时第一反应是去搜“Delphi LDAP组件”确实能找到一些但评估下来发现要么是商业授权要么是太老没有维护要么内部封装得太黑盒。后来静下心梳理了一下Delphi环境下访问AD可以归纳为四条路各有取舍。先说结论我看完对比表之后如果你只是需要快速搞定一个内部工具走ADOADSDSOObject如果你需要精细控制查询过程、高性能遍历大量对象或者有跨平台、通用LDAP目录的潜在需求直接调wldap32.dll更踏实。方案技术本质优点缺点方案一ADO ADSDSOObject通过ADSI的OLE DB Provider暴露为数据源代码量极少像查数据库一样执行查询Delphi里用OleVariant就能操作门槛低查大结果集时内存占用高对过滤器和分页控制粒度粗依赖COM和ADSI环境方案二直接调用wldap32.dll调用Windows自带LDAP C API可控性最强支持分页、异步、SSL/TLS扩展不仅是ADOpenLDAP等也适用异步和性能上限高函数声明比较繁琐需要自己管理内存和指针类型出错信息需要对照LDAP错误码方案三ADSI COM接口IDirectorySearch等使用COM接口获取目录搜索功能保留了ADSI的封装优势又能精细控制搜索选项在Delphi里引用COM接口头文件比较痛苦大多数接口方法用到VARIANT或指针数组声明和调试成本不小方案四第三方LDAP组件封装了LDAP协议或调用底层库用起来最简单很多支持跨平台依赖具体厂商闭源定制难许可证和稳定性需要评估有些老旧组件在Win10/Server 2019上兼容性堪忧我实际选的是方案一和方案二结合用户登录认证和简单的人员信息查询走ADOADSDSOObject因为代码量小而同步组织架构、批量拉取几千个用户时走wldap32.dll因为可以在客户端做分页和字段裁剪内存可控。这里我多说一句如果你的应用最终要部署在纯内网环境域控和客户端都在同一个Windows域里DNS解析通常没问题。但是如果程序要从外网或者非域环境访问AD必须确认你拿到的域控地址能被解析到且389端口在防火墙上放行了。LDAP Bind时最常见的“服务器不可用”错误十次里有八次是网络和端口层面的问题不是代码错。3. 实操用ADO ADSDSOObject快速实现查询这条路线对Delphi老程序员来说最友好因为代码模式跟用ADO连SQL Server很像。核心思路是ADSI给OLE DB提供了一个挨踢Provider名字叫ADSDSOObject你把它当作数据库驱动来用就可以。写代码前有几个前置要点必须初始化COM。Delphi的VCL通常在Application初始化时已经做了但如果你在后台线程或纯控制台项目里记得主动调用CoInitialize。OleVariant变量要声明并通过CreateOleObject(ADODB.Connection)创建ADO连接对象。查询字符串有一套固定语法说白了就是一个“LDAP风格的SQL”。下面是一段完整的示例作用是在域控上查询所有用户并读取几个常用属性uses System.SysUtils, System.Variants, ComObj, ActiveX, Windows; procedure QueryADUsers(const ADServer, Domain, User, Pass: string); var Conn, RS: OleVariant; query: string; displayName, mail, dept: string; begin CoInitialize(nil); try Conn : CreateOleObject(ADODB.Connection); Conn.Provider : ADSDSOObject; // 第一个参数是AD的LDAP根路径第二个是域账号第三个是密码 Conn.Open( Format(LDAP://%s/DCexample,DCcom, [ADServer]), Format(%s\%s, [Domain, User]), Pass ); query : LDAP://DCexample,DCcom; ((objectClassuser)(objectCategoryperson)); sAMAccountName,displayName,mail,department; subtree; RS : Conn.Execute(query); while not RS.EOF do begin // 注意字段可能为空读取前用VarIsNull做保护 if not VarIsNull(RS.Fields[displayName].Value) then displayName : VarToStr(RS.Fields[displayName].Value) else displayName : ; if not VarIsNull(RS.Fields[mail].Value) then mail : VarToStr(RS.Fields[mail].Value) else mail : ; if not VarIsNull(RS.Fields[department].Value) then dept : VarToStr(RS.Fields[department].Value) else dept : ; // 这里把数据塞进你自己的结构或列表里 OutputDebugString(PChar(displayName | mail | dept)); RS.MoveNext; end; RS.Close; Conn.Close; finally CoUninitialize; end; end;这段代码里有几个细节值得单独讲查询字符串的组成。它被分号分割成四段根路径、过滤条件、返回属性、搜索范围。第一段用尖括号包住LDAP根路径这是ADSDSOObject特有的语法要求不是随便写的。搜索范围支持base、onelevel、subtree三种查询整个域的用户的例子必须用subtree否则只能在当前节点这一层生效什么都查不到。字段空值处理。AD里很多对象的属性本来就是空的比如一个没填手机号的用户。用VarIsNull判断之后再转字符串不然一个VarToStr直接打在空Variant上会有异常。这个是我实际测试时踩到的实际报错尤其批量执行时一次异常整段查询就断了。关于连接参数。Conn.Open括号里的第二、第三个参数传的是域账号和密码这里账号格式建议写DOMAIN\user密码就是纯文本。如果你的程序跑在已经加入域的机器上并且当前Windows登录用户有权限Open时可以只传第一个参数后两个留空串走客户端本机凭证。但在服务器或非域环境下还是老老实实传账号密码免得登录态不可用。用ADO方式的局限性在于它拿回的是一个二维结果集所有属性都被展开成列。如果你想读取嵌套属性或者多值属性比如memberOf这种一个用户属于多个组的属性ADO方式处理起来就会有点别扭通常还得回到ADSI的接口层面去逐条取。4. 进阶直接调wldap32.dll的LDAP C API如果业务场景要求批量同步几千上万个用户或者需要自己控制查询的每一层细节我推荐直接用Windows自带的LDAP动态库wldap32.dll。这个库从Windows 2000开始就随系统提供稳定性和兼容性都经历过大量生产环境验证。在Delphi里调用它的方式是需要自己写外部函数声明第一次看着会有点头皮发麻但写熟之后其实就是一套固定模式。下面是我在项目里用的核心声明const LDAP_VERSION3 3; LDAP_OPT_PROTOCOL_VERSION $31; LDAP_AUTH_SIMPLE $80; LDAP_AUTH_NEGOTIATE $400; LDAP_SCOPE_BASE 0; LDAP_SCOPE_ONELEVEL 1; LDAP_SCOPE_SUBTREE 2; type PLDAP Pointer; PLDAPMessage Pointer; TLDAPEntry Pointer; TLDAPValues PPAnsiChar; // 连接与绑定 function ldap_init(HostName: PAnsiChar; PortNumber: Cardinal): PLDAP; stdcall; external wldap32.dll; function ldap_set_option(ld: PLDAP; option: Integer; optdata: Pointer): Cardinal; stdcall; external wldap32.dll; function ldap_bind_s(ld: PLDAP; dn: PAnsiChar; cred: PAnsiChar; method: Cardinal): Cardinal; stdcall; external wldap32.dll; function ldap_unbind(ld: PLDAP): Cardinal; stdcall; external wldap32.dll; // 查询与遍历 function ldap_search_s(ld: PLDAP; base: PAnsiChar; scope: Cardinal; filter: PAnsiChar; attrs: Pointer; attrsonly: Cardinal; res: Pointer): Cardinal; stdcall; external wldap32.dll; function ldap_first_entry(ld: PLDAP; res: PLDAPMessage): TLDAPEntry; stdcall; external wldap32.dll; function ldap_next_entry(ld: PLDAP; entry: TLDAPEntry): TLDAPEntry; stdcall; external wldap32.dll; // 取属性值 function ldap_get_values(ld: PLDAP; entry: TLDAPEntry; attr: PAnsiChar): TLDAPValues; stdcall; external wldap32.dll; function ldap_count_values(vals: TLDAPValues): Cardinal; stdcall; external wldap32.dll; function ldap_msgfree(res: PLDAPMessage): Cardinal; stdcall; external wldap32.dll; function ldap_err2string(err: Cardinal): PAnsiChar; stdcall; external wldap32.dll;声明完之后一个典型的查询流程可以拆成四步初始化会话、设置协议版本、绑定身份、执行搜索。第一步初始化LDAP会话。ldap_init返回一个会话句柄你所有后续操作都基于它var ld: PLDAP; begin ld : ldap_init(PAnsiChar(AnsiString(192.168.1.10)), 389); if ld nil then raise Exception.Create(LDAP初始化失败请检查网络或服务器地址); end;这里有个中文使用者常踩的坑wldap32.dll的传统API是ANSI版Delphi 2009以后默认字符串是Unicode直接传string给PAnsiChar参数时IDE会提示类型不匹配警告甚至编译报错。我建议在传参的地方统一用PAnsiChar(AnsiString(...))包一层确保编码转换是显式的不要依赖隐式转换。如果AD里存了中文姓名等非ASCII字符这种显式转换的位置尤其要检查清楚。第二步设置LDAP协议版本。AD默认要求LDAP v3而wldap32.dll初始化后的默认版本却是V2。不设置这一项后面search十有八九报“协议版本不支持”pascal var version: Cardinal; begin version : LDAP_VERSION3; ldap_set_option(ld, LDAP_OPT_PROTOCOL_VERSION, version); end;ldap_set_option的第三个参数是一个指针指向你设置的整型值。这里不能用常量直接传而是要定义一个变量取地址。第三步绑定身份。绑定在LDAP里就是“登录”的意思告诉服务器我是谁。可以用简单用户名格式也可以用UPN我建议用userexample.com或者DOMAIN\user这两种格式域控都能识别var err: Cardinal; begin err : ldap_bind_s(ld, PAnsiChar(AnsiString(adminexample.com)), PAnsiChar(AnsiString(Password_123)), LDAP_AUTH_SIMPLE); if err 0 then raise Exception.Create(StrPas(ldap_err2string(err))); end;有人会问为什么不直接用用户的DN来做绑定因为DN里往往带CN和OU有中文逗号转义的问题写成userdomain干净得多。AD在LDAP简单绑定时对UPN格式的支持很友好。第四步搜索。ldap_search_s是同步阻塞式搜索从开始查到最后一条结果返回后才结束。相比ADO方式的查询字符串C API的搜索参数更直观基准DN、搜索范围、过滤器、返回属性列表。如果你不需要限制属性数组把attrs参数传nil就行服务器会返回所有属性值var res: PLDAPMessage; entry: TLDAPEntry; vals: TLDAPValues; i: Integer; begin err : ldap_search_s(ld, PAnsiChar(AnsiString(DCexample,DCcom)), LDAP_SCOPE_SUBTREE, PAnsiChar(AnsiString(((objectClassuser)(objectCategoryperson)))), nil, 0, res); if err 0 then raise Exception.Create(StrPas(ldap_err2string(err))); entry : ldap_first_entry(ld, res); while entry nil do begin vals : ldap_get_values(ld, entry, sAMAccountName); if vals nil then begin for i : 0 to ldap_count_values(vals) - 1 do OutputDebugString(PChar(StrPas(vals[i]))); end; entry : ldap_next_entry(ld, entry); end; ldap_msgfree(res); ldap_unbind(ld); end;这里要特别提醒一点ldap_search_s的res参数必须传一个指针的地址res但不能事先初始化。如果重复使用要保证每次搜索前把res变量清空或者在搜索完调用ldap_msgfree释放。我一开始图省事没释放结果集跑了几百次之后内存直线上升后来才发现消息级的内存必须逐次清理。ldap_get_values返回的是PPAnsiChar本质上是一个以nil结尾的字符串数组。取值时先看是否为nil再通过ldap_count_values拿数量最后按数组下标遍历。注意它的下标从0开始遍历上限是数量减一。如果想读二进制属性比如用户头像thumbnailPhotoldap_get_values就不合适了要用ldap_get_values_len拿字节数组。不过日常开发里大多数属性都是字符串用ldap_get_values足够。5. 用户登录认证功能怎么写得既稳又安全做AD对接的项目最核心的功能就是登录认证。我在这个环节里试过几种方案最终选择的是“先用服务账号查询用户DN再用用户DN或UPN做二次绑定校验”的流程。我把这个流程细化一下程序配置里保存一个专用的只读服务账号低权限用它先连上AD。根据用户输入的登录名跑一个搜索找到对应用户的DN或者UPN。用这个用户自己的凭证绑定一次绑定成功说明密码正确。顺手把用户属性取回来。为什么不用“拿用户输入的账号密码直接绑定”这种方式因为如果用户账号本身被禁用、过期、锁定或者属于设定了“下次登录必须修改密码”的状态时直接绑定返回的错误码五花八门很难给用户一个明确的提示。先查再绑可以区分出“用户不存在”“账号被禁用”“密码错误”等不同场景对用户体验更好。用wldap32.dll实现认证过程大概是这样的function VerifyUserCredentials(const Server, UserName, Password: string): Integer; var ld: PLDAP; res: PLDAPMessage; entry: TLDAPEntry; err, bindErr: Cardinal; filter: string; dn: PAnsiChar; version: Cardinal; begin Result : -1; // -1表示内部错误0表示成功其他值参考LDAP错误码 ld : ldap_init(PAnsiChar(AnsiString(Server)), 389); if ld nil then Exit; try version : LDAP_VERSION3; ldap_set_option(ld, LDAP_OPT_PROTOCOL_VERSION, version); // 第一步用服务账号绑定 err : ldap_bind_s(ld, PAnsiChar(AnsiString(svc_readonlyexample.com)), PAnsiChar(AnsiString(ServiceReadOnlyPass)), LDAP_AUTH_SIMPLE); if err 0 then Exit; // 第二步按登录名搜索用户 filter : Format(((objectClassuser)(sAMAccountName%s)), [UserName]); err : ldap_search_s(ld, PAnsiChar(AnsiString(DCexample,DCcom)), LDAP_SCOPE_SUBTREE, PAnsiChar(AnsiString(filter)), nil, 0, res); if err 0 then Exit; entry : ldap_first_entry(ld, res); if entry nil then begin ldap_msgfree(res); Exit; // 用户不存在 end; dn : ldap_get_dn(ld, entry); ldap_msgfree(res); if dn nil then Exit; try // 第三步用用户自己的账号再次绑定 // 注意这里用UPN格式或直接取到的DN都行 bindErr : ldap_bind_s(ld, dn, PAnsiChar(AnsiString(Password)), LDAP_AUTH_SIMPLE); Result : bindErr; finally ldap_memfree(dn); end; finally ldap_unbind(ld); end; end;我不建议把密码以明文形式存在程序配置或数据库里。域账号对接本来就是要复用AD的密码策略再去设计一套自己的密码存储机制完全是给自己挖坑。安全写法是只保留服务账号的只读凭证调用时从加密配置文件或系统凭据管理器读取用户输入的密码只存活在内存变量里用完立即清空。另外如果程序面向公网或者半信任网络必须启用LDAPS636端口或者StartTLS否则用户密码是通过明文在网络上传输的抓个包就泄露了。在wldap32.dll里可以用ldap_sslinit替代ldap_init初始化SSL会话然后把传输模式设置为SSL。分两步设置ldap_sslinit命令连接636端口绑定前用ldap_set_option把LDAP_OPT_SSL或LDAP_OPT_ENCRYPT启用。实际生产环境里一般企业域控默认486端口用于全局编录GC如果要跨域查询所有对象初始化时用3268端口连GC会更快。这个我建议网上再查一下具体参数含义别直接用因为每个企业的域控配置不一定一致。6. 实战中绕不开的坑常见报错与排查记录这一节的内容是我在这个项目里反复调试后才总结出来的几乎每个都对应过真实的报错现场。先列一个速查表再逐个展开聊。现象常见原因排查思路连接超时或“服务器不存在”网络不同、端口未放行、DNS解析失败telnet/DevTool探测389端口确认域名解析到域控IP绑定返回0x51本地错误服务器不可达或账户权限不足换一个简单账户测试确认服务账号有LDAP读取权限绑定返回0x52无法联系服务器离线或防火墙拦截检查域控服务状态测试637/389端口绑定返回0x31凭据错误密码错误、账号过期或者被锁定用其他工具如AD用户和计算机验证账号状态Ldapl_s返回0x0B协议版本不对还在用V2把LDAP_OPT_PROTOCOL_VERSION设置为3中文姓名乱码代码内字符串编码不一致统一用UTF-8传参返回值按UTF-8解码属性明明存在但搜索不到过滤器写错或属性在AD里确实为空先不加过滤条件搜取回原始属性列表核对成员组信息读不出来memberOf可能不存在或权限受限检查服务账号是否有“读取所属组”权限第一个坑绑定时报“无法解译过滤器”。这是最常见的低级错误通常是过滤器的括号不匹配或者属性名写错。LDAP过滤器调试起来特别像正则表达式一个括号错位整条全废。我自己的习惯是先在调试窗口打印出完整过滤器字符串肉眼检查括号配对再复制到自带的LDAP浏览器工具里跑一遍。第二个坑中文乱码。这个项目在中文环境里跑用户姓名、部门名都有中文。用ADO方式读取时OleVariant拿到的BSTR本来就是UnicodeDelphi的string也是Unicode按理不会乱。但我遇到乱码的地方是在wldap32.dll的ANSI接口链路上。因为ldap_get_values返回的是PAnsiChar如果你直接用StrPas()转成stringDelphi会按当前代码页解释字节一旦AD里存的是UTF-8编码的字节串转出来的汉字就全乱了。解决方法是手动按UTF-8解码。我后来写了个小工具函数function Utf8ToStrEx(const Bytes: PAnsiChar): string; begin Result : TEncoding.UTF8.GetString( TBytes(Pointer(Bytes)^) ); end;不过要注意这个函数假设服务器返回的就是合法的UTF-8字节序列而且PBytes(Pointer(Bytes)^)这个写法有越界风险因为拿到的是一个以nil结尾的字符串缓冲区长度未知。实际开发中建议用ldap_get_values配合ldap_count_values先确定字节数再安全转换。如果你在Unicode版的Delphi上跑也可以直接考虑调用wldap32.dll的W系列函数比如ldap_get_valuesW省去编码转换的麻烦。第三个坑大结果集把内存吃爆。刚开始我写了一个搜索所有用户的命令不加任何分页条件测试域里只有2000多人时还不觉得后来跑到生产域数据量涨到几万程序瞬间卡死甚至崩溃。原因不是服务器查不出来而是ldap_search_s会把所有结果一次性带回客户端内存里。解决思路有两条第一条是让AD服务器端分页需要用LDAP_CONTROL_PAGED_RESULTS控件在ldap_search_ext_s时把分页大小和Cookie传进去第二条更简单——在客户端业务侧限制只查必需属性的子集并且按OU分批次查询。我最后用了第二种把组织架构里每个部门作为一个根节点分别搜索既满足了界面加载的分段显示需求又避免了单次大内存消耗。第四个坑AD时间戳属性看着是一串数字。AD里的whenCreated、lastLogon这类属性是Windows的FileTime格式长达18位的Int64值。如果你直接用StrPas去读显示出来就是一串怪异数字需要调用FileTimeToSystemTime转成日期格式。这个不算报错但很容易被忽略。第五个坑memberOf的多值处理。在ADO结果集里memberOf字段看起来可能是一个数组直接VarToStr取不出来完整数据。这是因为用户的所属组不止一个。我建议在取这个属性时走LDAP C API的ldap_get_values遍历返回值拿取每个组的完整DN再在界面上只显示CN部分。第六个坑分页时忘记释放Cookie。如果后来用到LDAP_CONTROL_PAGED_RESULTS搜索完成后必须释放分页Cookie否则服务器端会保留搜索状态占用资源。说实话这个控件在Delphi里的封装代码比普通搜索长不少但如果是大批量同步场景这一步省不掉。7. 一些零零散散的经验补充最后分享几个我在项目里沉淀下来的习惯谈不上深刻但确实能省下不少排查时间。写一个本地的AD查询小工具。我建议你哪怕产品最终没有管理界面也先写一个独立的控制台或窗口程序用来测试AD查询。这个小程序做到三件事输入服务器、账号、密码输入过滤器字符串把原始返回属性和值不带任何格式地打印出来。这个工具成了我后续排查一切问题的起点比直接在业务代码里打日志高效得多。毕竟AD对接问题的源头大多数在服务器端配置或者权限上能快速验证“这个账号到底能不能读到这个属性”比反复改业务代码要快得多。不要把查询逻辑散落在业务代码里。我后来把LDAP相关的连接、绑定、搜索、解析全部装进了一个独立的单元对外只暴露两个方法一个是TADConnection类的Login(UserName, Password)另一个是QueryUsers(Filter, Attribs)。这样如果未来要换第三方的LDAP库或者从ADSI切换到纯LDAP实现业务界面一层基本不用动。配置项要外置。服务器地址、端口、基础DN、服务账号这些放在一个ini或者JSON文件里不要硬编码到代码里。曾经有过一次客户方调整了域控的IP我硬编码在程序里的地址就失效了最后让实施同事改了配置文件手动替换才恢复。配置文件里的敏感字段建议做一层简单加密或者使用Windows凭据管理器虽然谈不上绝对安全但至少比明文强。我在这个项目的最后把整个“Delphi访问基于LDAP的Active Directory”的需求拆成了两层底层用wldap32.dll保证查询能力上层用ADO实现轻量级的快速接入。这么做的根本原因还是前面说的ADO方式写着舒服但控制力弱C API反着来但一旦把封装做好后面加功能几乎不用再动底层。Delphi这么多年过去生态确实不如以前热闹但面对Windows系统级的这些接口依然是宝刀未老原生的调用方式稳定可靠也没有多余依赖。如果你正在做类似的功能希望这篇整理能帮你少踩几个坑。