




LdapAuth 插件开发细节
类型:Typecho LDAP / AD 统一身份认证插件
版本:1.0.6
代码规模:Plugin.php 约 850 行,另有管理页、说明与排错文档
运行环境:Typecho 1.3.x + PHP ldap 扩展
1. 设计目标
在不修改 Typecho 任何核心文件的前提下,实现:
- 用 LDAP(含 AD 域控)账号替换本地密码认证
- 后台可视化管理"谁能登录"及其用户组
- 保留本地应急入口,避免 LDAP 故障导致后台锁死
- 全链路可观测,便于排查认证失败
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() |
| 2 | hook 名 loginFailed 写错 | 对齐核心 loginFail |
| 3 | 新用户无 password,形成空密码账户 | 写随机密码哈希 |
| 4 | LDAP 过滤值未转义 | 转义 \ * ( ) 等 |
| 5 | errno==-1 判断连接不可靠 | 改用 bind 返回值 |
| 6 | 名单保存后刷新为空 | setOption 的 UPDATE 无匹配行 → 按存在性 INSERT/UPDATE |
| 7 | cfg() 方法不存在导致日志 fatal | 改用 configValues() |
| 8 | LDAPS 忽略证书不生效 | 设置时机改到 connect 前全局 |
| 9 | CONNECT_OK 是假象 | 新增真实端口探测 |
| 10 | UPN 被当 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
评论