Bitzsoft.Integrations.Ldap 1.0.0-alpha.7

Bitzsoft.Integrations.Ldap

LDAP 目录服务集成客户端 — 基于 Novell LDAP SDK，支持 Active Directory。

功能特性

• 连接池管理 — 内置池化连接，自动回收与复用，可配置池大小与超时
• 身份认证 — 支持用户凭据验证（Bind），验证后自动恢复服务账号连接状态
• 搜索操作 — 全量搜索、单条搜索、流式分页搜索（IAsyncEnumerable），内存友好
• 写操作 — 条目增删改、重命名/移动（ModifyDN）
• 密码管理 — AD 管理员重置密码、用户自助修改密码（unicodePwd，需要 SSL 连接）
• 过滤器构建 — 链式 API 构建 RFC 4515 搜索过滤器，自动转义防 LDAP 注入
• 工具函数 — DN 转义/解析、GeneralizedTime 转换、OU 路径构建等
• 结构化异常 — LdapOperationException 携带 LdapErrorCode 枚举，便于精确处理

安装

dotnet add package Bitzsoft.Integrations.Ldap

<PackageReference Include="Bitzsoft.Integrations.Ldap" Version="*" />

配置

{
  "Ldap": {
    "Host": "ad.example.com",
    "Port": 636,
    "UseSsl": true,
    "BaseDn": "DC=example,DC=com",
    "BindDn": "CN=svc_ldap,OU=ServiceAccounts,DC=example,DC=com",
    "BindPassword": "{{LDAP_BIND_PASSWORD}}",
    "ConnectTimeoutMs": 5000,
    "OperationTimeoutMs": 10000,
    "PoolWaitTimeoutMs": 15000,
    "PoolMinSize": 2,
    "PoolMaxSize": 10,
    "PoolRecycleIntervalMs": 300000
  }
}

注册服务

本包不提供 DI 扩展方法。直接创建 LdapFactory 实例即可：

using Bitzsoft.Integrations.Ldap;

var options = new LdapOptions
{
    Host = "ad.example.com",
    Port = 636,
    UseSsl = true,
    BaseDn = "DC=example,DC=com",
    BindDn = "CN=svc_ldap,OU=ServiceAccounts,DC=example,DC=com",
    BindPassword = "your-password"
};

await using var factory = new LdapFactory(options);

如需在 DI 容器中管理生命周期，可自行封装：

using Bitzsoft.Integrations.Ldap;

// 单例注册（按租户一个实例）
services.AddSingleton(sp =>
{
    var config = sp.GetRequiredService<IConfiguration>();
    return new LdapFactory(new LdapOptions
    {
        Host = config["Ldap:Host"]!,
        Port = int.Parse(config["Ldap:Port"]!),
        UseSsl = true,
        BaseDn = config["Ldap:BaseDn"]!,
        BindDn = config["Ldap:BindDn"]!,
        BindPassword = config["Ldap:BindPassword"]!
    });
});

使用示例

验证用户凭据

using Bitzsoft.Integrations.Ldap;

await using var factory = new LdapFactory(options);

var userDn = $"CN={username},OU=Users,DC=example,DC=com";
var isValid = await factory.VerifyCredentialsAsync(userDn, password);
Console.WriteLine(isValid ? "认证成功" : "用户名或密码错误");

搜索用户

using Bitzsoft.Integrations.Ldap;

await using var factory = new LdapFactory(options);

// 使用 LdapFilterBuilder 构建安全的搜索过滤器
var filter = new LdapFilterBuilder()
    .And()
        .ObjectClass("user")
        .Eq("sAMAccountName", "john.doe")
        .Exists("mail")
    .End()
    .ToString();

// 搜索单条
var user = await factory.SearchOneAsync(
    baseDn: "OU=Users,DC=example,DC=com",
    filter: filter,
    attributes: ["cn", "mail", "department", "memberOf"]);

if (user is not null)
{
    Console.WriteLine($"姓名: {user["cn"]}");
    Console.WriteLine($"邮箱: {user["mail"]}");
    Console.WriteLine($"部门: {user["department"]}");
}

// 流式分页搜索（适合大规模数据同步）
var allUsersFilter = new LdapFilterBuilder()
    .And()
        .ObjectClass("user")
        .Exists("mail")
    .End()
    .ToString();

await foreach (var entry in factory.SearchPagedStreamAsync(
    baseDn: "OU=Users,DC=example,DC=com",
    filter: allUsersFilter,
    attributes: ["cn", "mail", "department"],
    pageSize: 500))
{
    // 逐条处理，内存占用恒定
    Console.WriteLine($"{entry["cn"]} - {entry["mail"]}");
}

构建 LDAP 过滤器

using Bitzsoft.Integrations.Ldap;

// 复合条件:
// (&(objectClass=user)(|(department=技术部)(department=产品部))(!(userAccountControl:1.2.840.113556.1.4.803:=2)))
var filter = new LdapFilterBuilder()
    .And()
        .ObjectClass("user")
        .Or()
            .Eq("department", "技术部")
            .Eq("department", "产品部")
        .End()
        .Raw("(userAccountControl:1.2.840.113556.1.4.803:=2)")
        .Not()
        .End()
    .End()
    .ToString();

// 工具函数
var escapedCn = LdapUtility.EscapeDn("Smith, John");       // "Smith\, John"
var cnValues  = LdapUtility.ParseCnValues(                  // ["Lawyers"]
    "CN=Lawyers,OU=RoleGroups,DC=domain,DC=com");
var ouPath    = LdapUtility.BuildOuPath("Roles,Security");  // "OU=Roles,OU=Security,"
var parentDn  = LdapUtility.GetParentDn(                    // "OU=Users,DC=domain,DC=com"
    "CN=John,OU=Users,DC=domain,DC=com");

健康检查与连接池监控

using Bitzsoft.Integrations.Ldap;

await using var factory = new LdapFactory(options);

var isHealthy = await factory.IsHealthyAsync();
var (active, idle) = factory.GetPoolStatistics();
Console.WriteLine($"健康: {isHealthy}, 活跃: {active}, 空闲: {idle}");

依赖

• Bitzsoft.Integrations.Compatibility -- 基础工具库
• Novell.Directory.Ldap.NETStandard -- LDAP 协议客户端 SDK

相关包