Typecho LDAP用户管理插件(含 Windows AD 域控)账号登录,并提供可视化的登录准入管理。

Typecho LDAP用户管理插件(含 Windows AD 域控)账号登录,并提供可视化的登录准入管理。

王忘杰
2026-11-20 / 0 评论 / 8 阅读 / 正在检测是否收录...

mwoacunu.png

mwoad4jq.png

mwoadytw.png

mwoae866.png

mwoaejoo.png

LdapAuth 插件开发细节

类型:Typecho LDAP / AD 统一身份认证插件
版本:1.0.6
代码规模:Plugin.php 约 850 行,另有管理页、说明与排错文档
运行环境:Typecho 1.3.x + PHP ldap 扩展

1. 设计目标

在不修改 Typecho 任何核心文件的前提下,实现:

  1. 用 LDAP(含 AD 域控)账号替换本地密码认证
  2. 后台可视化管理"谁能登录"及其用户组
  3. 保留本地应急入口,避免 LDAP 故障导致后台锁死
  4. 全链路可观测,便于排查认证失败

2. 核心机制:两个钩子

Typecho 的插件系统基于 Typecho\Plugin::factory(handle) 注册回调。

2.1 登录接管

\Typecho\Plugin::factory('Widget\User')->login = __CLASS__ . '::login';

Widget\User::login() 内部用 trigger()+call() 调用该钩子,插件返回非 null 即
完全接管核心验证(var/Widget/User.php)。这是整个插件的入口。

2.2 前台拦截

\Typecho\Plugin::factory('index.php')->begin = __CLASS__ . '::enforceLogin';

挂在路由分发前,未登录访问前台任意页面时 302 到后台登录页,带 referer
参数登录后跳回。后台走独立的 admin/common.php::begin,不经过此钩子,
因此不会被拦截。


3. 认证主流程

login(name, password, temporarily, expire)
  │
  ├─ 1. 本地例外用户?(local_users) ── 是 ─→ 本地密码验证,结束
  │
  ├─ 2. LDAP 未配置 / 无 php-ldap 扩展 ─→ 本地回退(若开启)
  │
  ├─ 3. 构造 DN(三种模式自动识别)
  │       ├─ UPN:user@domain,不拼后缀
  │       ├─ 完整 DN:含 dc=/ou=,不拼后缀
  │       └─ RDN:拼 Base DN + Root DN
  │
  ├─ 4. TCP 端口探测(真实连接测试)
  │
  ├─ 5. LDAPS 证书设置(必须在 connect 之前)
  │
  ├─ 6. ldap_connect → ldap_bind
  │       └─ 失败:errno 49 直接拒绝;其他错误才回退
  │
  ├─ 7. ldap_search 读属性(base 必须是合法 DN,不能用 UPN)
  │
  ├─ 8. 白名单校验(name => group)
  │
  ├─ 9. 建/同步本地影子账号(随机密码)
  │
  └─ 10. User::simpleLogin() 完成登录

4. 关键技术点

4.1 DN 三种模式

模式判定条件是否拼后缀
UPN含 @ 且无 =否
完整 DN含 dc= 或 ou=否
RDN其余拼 Base + Root

用户在登录框直接输完整 UPN 时,用输入值替换模板结果,避免 a@b 变 a@b@b。

关键约束:UPN 只能用于 ldap_bind 认证,不能作为 ldap_search 的 base DN,
否则报 errno 34(DN 语法错误)。属性搜索用独立的 Base+Root DN。

4.2 LDAPS 证书设置时机

LDAP_OPT_X_TLS_REQUIRE_CERT = NEVER(忽略证书)必须在 ldap_connect() 之前
用全局方式设置:

ldap_set_option(null, LDAP_OPT_X_TLS_REQUIRE_CERT, LDAP_OPT_X_TLS_NEVER);
$conn = ldap_connect($server);

若只在 connect 之后对 $conn 设置,对 TLS 握手阶段无效——即使配了"忽略证书"
仍会报 errno -1。代码里做了 connect 前全局 + connect 后连接级双保险。

常量用 defined() 判断,缺失时用数值兜底(REQUIRE_CERT=24582,NEVER=0)。

4.3 端口探测

ldap_connect() 对 URI 只解析不建立 TCP 连接,CONNECT_OK 不代表网络可达。
因此加了 probePort():用 fsockopen 真实连接,超时 3 秒,日志区分
OPEN(网络通,问题在 TLS)和 CLOSED(端口/防火墙问题)。

4.4 登录态设置

User::currentUser 和 User::hasLogin 是 private 属性,外部赋值会触发
Widget::__set() 写进数据行,改不到真实登录状态。必须使用核心提供的
User::simpleLogin()(源码注释明确写"多用于插件等特殊场合"),它内部正确
设置私有属性、写 cookie、触发 simpleLoginSucceed 钩子。

4.5 白名单存储

存于 options 表的自定义行 ldapUsers,格式 用户名 => 用户组 的关联数组。

踩过的坑:Helper::setOption() 内部是 UPDATE options WHERE name=?,
但表里没有 ldapUsers 这一行(Typecho 安装只预置少数键),UPDATE 影响 0 行,
保存静默失败。修复为:先查行是否存在,不存在 INSERT,存在才 UPDATE。
读取也改为直接查库,不依赖 Options 组件缓存单例。

4.6 管理页注册

Helper::addPanel(3, '插件名/manage.php', 'LDAP用户', '管理 LDAP 登录账号', 'administrator');

索引 3 对应"管理"组(Menu.php 的 parentNodes),因此菜单出现在"用户"下方。
admin/extending.php 会根据 panel 参数自动 require 插件目录里的文件。

表单 CSRF 防护用 Security::getToken(固定后缀) 生成 _ 字段自行校验——
注意该类没有 checkToken() 方法,且 getToken() 必须带参数。

4.7 本地例外用户

配置项 local_users(默认 admin,逗号分隔)。login() 最开头检查,命中即
调用 fallbackLocal(..., force=true) 跳过"LDAP 不可用时回退"选项限制。

匹配规则:大小写不敏感、邮箱取 @ 前比较、精确匹配(administrator 不命中 admin)。

4.8 邮箱兜底

Typecho 建号要求 mail 非空且唯一。LDAP 未返回邮箱时:

  • UPN 登录:直接用 user@domain
  • 其他:用 用户名@<Root DN 的 DC 拼接>,无 DC 时用 ldap.local

5. 调试日志系统

配置项 debug_log 开启后写入插件目录 ldap-debug.log,记录时间、IP、步骤、
细节,绝不记录密码。

27 个日志点覆盖全流程,关键标记:

标记阶段
LOGIN_START / LOCAL_EXEMPT入口 / 例外命中
PORT_PROBE真实端口可达性
TLS_GLOBAL / TLS_IGNORE证书设置
DN ... [mode=...]认证 DN 及模式
BIND_OK / BIND_FAIL errno=认证结果
SEARCH / ATTRS属性读取
WHITELIST_OK / REJECT准入判定
CREATE_OK / MAIL_FALLBACK建号 / 邮箱兜底
LOGIN_OK完成

errno 对照:-1 连不上、49 凭据无效、32 对象不存在、34 DN 语法错误。
安全策略:errno 49 一律拒绝,绝不回退本地密码,避免 LDAP 密码错误时用
本地空密码账户登录。


6. 开发过程中修复的问题

#问题修复
1外部写 User 私有属性无效改用 simpleLogin()
2hook 名 loginFailed 写错对齐核心 loginFail
3新用户无 password,形成空密码账户写随机密码哈希
4LDAP 过滤值未转义转义 \ * ( ) 等
5errno==-1 判断连接不可靠改用 bind 返回值
6名单保存后刷新为空setOption 的 UPDATE 无匹配行 → 按存在性 INSERT/UPDATE
7cfg() 方法不存在导致日志 fatal改用 configValues()
8LDAPS 忽略证书不生效设置时机改到 connect 前全局
9CONNECT_OK 是假象新增真实端口探测
10UPN 被当 DN 拼接识别 UPN 跳过后缀
11属性搜索 base 用 UPN 报 34改用合法 Base+Root DN
12读不到邮箱无法建号邮箱兜底
13(后续清理) 服务账号配置项冗余移除三项配置及相关逻辑,filter 改固定值

7. 配置面板结构

分组配置项
连接服务器地址、Root DN、搜索 Base DN、用户 DN 模板、邮箱属性名、显示名属性名
准入LDAP 用户白名单、本地认证例外用户、扩展选项(本地回退)
会话全站前台登录限制
安全LDAP 证书验证
诊断调试日志

8. 已知边界

  • 后台"LDAP用户"名单存在 options 里,站点迁移需一并导出
  • 白名单模式的本地影子账号由登录时自动创建,用户组以名单为准,每次登录同步
  • 移除名单只禁止 LDAP 登录,不删除本地账号及其文章
  • UPN 后缀必须是域的 UPN 后缀,不一定等于 DC
  • 调试日志排查后应关闭,避免日志文件持续增长

LdapAuth 1.0.6

0

评论

博主关闭了所有页面的评论