feat(sso): MaxKey 迁移 P1/P2 —— SCIM/CAS/LDAP/同步连接器/自助密码重置/归属地

- 新增 plugin-sso 模块(零新增 crate):scim.rs(SCIM 2.0)、cas.rs(CAS 1.0/2.0)、

  ldap.rs(LDAP/AD,手写 BER/ASN.1 Simple Bind)、sync.rs(钉钉/企微/飞书手动触发同步)、

  reset.rs(自助密码重置)、geo.rs(登录 IP 归属地)

- api.rs 兜底路由按 scim→cas→reset→sync 分发兄弟模块;h_login 集成 LDAP(未启用零行为变化)

- 修 http::redirect 空 body 触发 NGX_ERROR(CAS 302 无 Location 的根因)

- nginx.conf / nginx.test.conf 补 env SYNC_* / PASSWORD_RESET_*(worker 可见)

- 新增第 7 套 e2e tests/maxkey-p1p2-e2e.sh(21 项),harness 接入 [7/7];七套全绿 rc=0

- 修脚本 $var 紧跟全角字符被并入变量名的 shell 坑(tests + scripts)

- 文档同步:maxkey-migration-analysis(P1/P2 状态) / roadmap(v4) / CLAUDE.md / README.md
This commit is contained in:
ssw committed 2026-09-14 18:51:37 +08:00
1 parent f3aabb3405
commit 4a780a4ce7
20 files changed
+1986 -37

No files matched your search

+32 -10
View File
@@ -15,6 +15,12 @@ MaxKey 值得抄的不是"大而全",而是三类东西:**纯算法与协议
| P2 低优先 | 5 项 | 有价值但当前定位用不上 |
| 不建议迁移 | 6 项 | 重度绑定 Java 生态,或与"身份层"定位冲突 |
> **迁移状态(2026-09-14 更新)**
> P1 第 8–12 项与 P2 第 17 项**已实现**(对应条目已标 `[x]`,落地见文末「落地实现索引」);
> P2 第 13–16 项**已决定跳过**(标 `[skip]`)。
> 边界(已与需求方确认):需外部基建的能力(LDAP/AD、同步连接器、自助密码重置)只做**手动触发端点**,
> 不引入常驻进程;WebAuthn/Passkey、社交/扫码、SAML 2.0、FormBased 四项不做。
---
## P0:建议迁移(纯逻辑,直接补短板)
@@ -53,26 +59,26 @@ MaxKey 值得抄的不是"大而全",而是三类东西:**纯算法与协议
## P1:视需求迁移(先评估成本)
8. **SCIM 2.0 身份供给** — MaxKey:`maxkey-web-apis/maxkey-web-api-scim/`
8. [x] **SCIM 2.0 身份供给** — MaxKey:`maxkey-web-apis/maxkey-web-api-scim/`
(User/Group/EnterpriseUser/ServiceProviderConfig 完整资源模型)。
价值:外部系统(HR、上游 IdP)可用标准协议推送用户进来。资源模型清晰,
就是 CRUD,落 `users.json`/`groups` 现有模型可行;工作量主要在过滤语义
(`userName eq "..."`)与分页。**若确定有上游系统对接需求再做。**
9. **CAS 协议端点(v2/v3 validate)** — 延续 v1"照抄 MaxKey 文档接入方零改造"的思路,
9. [x] **CAS 协议端点(v2/v3 validate)** — 延续 v1"照抄 MaxKey 文档接入方零改造"的思路,
补 `/cas/sso/validate`、`/p3/proxyValidate` 等端点,让 CAS 客户端也能直连。
票据校验是纯逻辑;但 CAS 生态在国内老系统里存量不小,值得排期。
10. **LDAP / AD 认证源** — MaxKey:`realm/ldap`(OpenLDAP/AD)。企业场景刚需,但
10. [x] **LDAP / AD 认证源** — MaxKey:`realm/ldap`(OpenLDAP/AD)。企业场景刚需,但
Rust 侧需要 LDAP 客户端库(`ldap3` 依赖体积不小,且需 vendor)。
替代路径:先用 P1-8 的 SCIM 或 P2-13 的同步连接器"拉取"而非"直连"。
11. **身份同步连接器(钉钉 / 企微 / 飞书 / AD)** — MaxKey:
11. [x] **身份同步连接器(钉钉 / 企微 / 飞书 / AD)** — MaxKey:
`maxkey-synchronizers/maxkey-synchronizer-<name>/`。钉钉/企微/飞书三个就是
HTTP API 调用(分页拉用户+组织),交互协议可直接照抄;AD/LDAP 需 LDAP 库。
适合做成定时任务(本项目无后台进程,可用 nginx timer 或外部 cron curl 管理端点触发)。
12. **自助密码重置(邮箱/短信找回)** — MaxKey:`mxk_register` + 邮件/短信 provider
12. [x] **自助密码重置(邮箱/短信找回)** — MaxKey:`mxk_register` + 邮件/短信 provider
(阿里云/腾讯云/网易云信,`maxkey-starter-sms/`)。依赖外部发信通道;若做,
建议 provider 抽象成配置驱动的 HTTP 调用(与 AIMALL GenericHTTPTool 同思路)。
@@ -80,20 +86,20 @@ MaxKey 值得抄的不是"大而全",而是三类东西:**纯算法与协议
## P2:低优先(有价值,当前定位用不上)
13. **WebAuthn / Passkey** — MaxKey:`maxkey-starter/maxkey-starter-passkey/`
13. [skip] **WebAuthn / Passkey** — MaxKey:`maxkey-starter/maxkey-starter-passkey/`
(含 `mxk_user_passkeys` 表)。方向正确但 Rust 零依赖下验签链很重
(COSE/CTAP2/attestation),且 RSA 大数运算本来就在 v2 才引入。等 v2 落地后再评估。
14. **社交登录 / 扫码登录** — MaxKey 基于 JustAuth + 自研 WeLink/飞书/企微 request。
14. [skip] **社交登录 / 扫码登录** — MaxKey 基于 JustAuth + 自研 WeLink/飞书/企微 request。
本项目作为**企业内部身份层**,社交登录价值有限;若 souyi.net.cn C 端要用,另起服务。
15. **SAML 2.0** — MaxKey 重度绑定 OpenSAML。XML-DSig 签名在 Rust 零依赖下工作量
15. [skip] **SAML 2.0** — MaxKey 重度绑定 OpenSAML。XML-DSig 签名在 Rust 零依赖下工作量
数倍于整个现有 oauth.rs。除非有明确 SAML SP 客户,否则不排期。
16. **FormBased / TokenBased / ExtendApi 协议** — 老式企业代填/票据协议。
16. [skip] **FormBased / TokenBased / ExtendApi 协议** — 老式企业代填/票据协议。
TokenBased 的"票据换会话"语义可作为 IAP 票据机制参考;FormBased 代填不建议。
17. **ip2location 归属地解析** — MaxKey 内置登录 IP 归属地。审计日志做精致了再加。
17. [x] **ip2location 归属地解析** — MaxKey 内置登录 IP 归属地。审计日志做精致了再加。
---
@@ -130,3 +136,19 @@ MaxKey 的 44 张表里,对本项目最有参考价值的三组设计:
- 同步连接器:`maxkey-synchronizers/maxkey-synchronizer-{ad,ldap,jdbc,dingtalk,workwechat,feishu}/`
- OTP 算法:`maxkey-starter/maxkey-starter-otp/`
- 全量表结构:`sql/v4.2.0/maxkey.sql`
---
## 落地实现索引(2026-09-14)
| 能力 | 模块 | 端点 / 要点 | 回归 |
| --- | --- | --- | --- |
| SCIM 2.0 | `plugin-sso/src/scim.rs` | `/scim/v2/{ServiceProviderConfig,Schemas,ResourceTypes,Users,Groups}`(Users 全 CRUD + PATCH;Groups 派生自账号 `groups`) | `tests/maxkey-p1p2-e2e.sh` §A |
| CAS 1.0/2.0 | `plugin-sso/src/cas.rs` | `/cas/login`(302 签发 ST)、`/cas/validate`(纯文本)、`/cas/serviceValidate` + `/cas/proxyValidate`(XML);ST 共享内存 30s、单次有效、绑定 service | §B |
| LDAP / AD | `plugin-sso/src/ldap.rs` | **零新增依赖**:手工 BER/ASN.1 Simple Bind;env:`LDAP_ENABLED`/`LDAP_SERVER`/`LDAP_PORT`/`LDAP_BASE_DN`/`LDAP_USER_DN_TEMPLATE`/`LDAP_AUTO_CREATE`;未启用零行为变化 | §E(禁用回归) |
| 同步连接器 | `plugin-sso/src/sync.rs` | `POST /api/admin/sync/{dingtalk,workwechat,feishu}`(管理员,手动触发);标准库 TcpStream 拉取,归一化 `{users:[...]}` → upsert | §D(钉钉 mock) |
| 自助密码重置 | `plugin-sso/src/reset.rs` | `POST /api/public/forgot-password`、`/reset-password`;token 共享内存、单次有效、防账号枚举;发信可配置(日志 / `PASSWORD_RESET_TOKEN_SINK` 文件 / 生产 SMTP-webhook) | §C |
| ip2location | `plugin-sso/src/geo.rs` | 内嵌代表性 CN IPv4 CIDR 表 + 内网/保留段判定,零依赖粗判「内网/中国/海外」 | 审计日志 |
> 环境变量白名单:nginx 默认剥离全部 env,`nginx.conf` / `nginx.test.conf` 已加
> `env SYNC_*`、`env PASSWORD_RESET_*`(未声明则 worker 读不到)。
+26
View File
@@ -189,3 +189,29 @@
- [x] 单点注销:`/logout`、`/sign/logout` 别名 + `redirect_uri` 302 回跳(client 白名单,未登记 400;302 同时清会话 cookie)
- [x] 管理员重置密码入口统一过 `check_password`(原可绕过插件层 8 位策略)
- [x] e2e:互通套新增 A2b/A2c/A2d/A2e/A8b 六条断言,六套 rc=0
## [x] v4:MaxKey 迁移 P1/P2 补齐(2026-09-14 完成)
> 逐项依据:`docs/maxkey-migration-analysis.md`(P1 第 8–12 项、P2 第 17 项)。
> 边界(已与需求方确认):需外部基建的能力只做**手动触发端点**,不引入常驻进程;
> WebAuthn/Passkey、SAML 2.0、社交/扫码、FormBased/TokenBased 四项**明确跳过**。
- [x] **SCIM 2.0 身份供给**(`plugin-sso/src/scim.rs`):ServiceProviderConfig / Schemas /
ResourceTypes / Users(全 CRUD + PATCH)/ Groups(派生自账号 `groups`)
- [x] **CAS 1.0 / 2.0 端点**(`cas.rs`):`/cas/login`(签发 ST 并 302 回跳)、`/cas/validate`(纯文本)、
`/cas/serviceValidate` + `/cas/proxyValidate`(XML);ST 存共享内存、30s TTL、单次有效、绑定 service
- [x] **LDAP / AD 认证源**(`ldap.rs`):**零新增依赖**——手工 BER/ASN.1 Simple Bind;
env 配置,本地口令失败时兜底尝试、可选自动建号;**未启用零行为变化**(不破坏既有登录)
- [x] **同步连接器(钉钉/企微/飞书)**(`sync.rs`):`POST /api/admin/sync/<provider>` 手动触发,
标准库 `TcpStream` 拉取 + 归一化契约 upsert;由外部 cron 调用,不引入后台进程
- [x] **自助密码重置**(`reset.rs`):`POST /api/public/forgot-password` + `/reset-password`,
token 共享内存、单次有效、防账号枚举;发信可配置(日志 / SINK 文件 / 生产接 SMTP-webhook)
- [x] **ip2location 登录 IP 归属地**(`geo.rs`):内嵌 CN CIDR 精简版,审计记录归属地
- [x] 新增第 7 套 e2e `tests/maxkey-p1p2-e2e.sh`(SCIM / CAS / 密码重置 / 同步 / LDAP 禁用回归,21 项);
**七套全绿 rc=0**
- [x] 修复 `http::redirect` 空 body 触发 `NGX_ERROR`(CAS 302 失效根因);全仓修 `$var` 紧跟全角字符的 shell 坑
> 踩坑留档:① nginx 默认剥离 env,新模块用到的 `SYNC_*` / `PASSWORD_RESET_*` 必须在 conf 里显式 `env`;
> ② 重置类 e2e 不得改 admin 种子口令(`123456` 过不了 8 位策略、无法还原),改用一次性账号闭环;
> ③ 同步 mock 端口避开 nginx 已占用的 18097。