Files
sso/docs/maxkey-migration-analysis.md
T
ssw 20466894fc feat(sso-ui): 补齐 P1/P2 的管理台界面与终端用户找回页
- 管理台 source/www/admin.html:3 页签 → 5 页签

  · 新增「身份同步」:钉钉/企微/飞书手动触发 + 结果表(处理/新建/更新/跳过)

  · 新增「会话 / 审计」:在线会话列表 + 三种踢下线、审计日志含 IP 归属地(geo 的可见出口)

  · 账号行加「双因子」按钮(setup→enable / disable)

  · 接入指南补 CAS 1.0/2.0、SCIM 2.0、LDAP/AD 三段端点与配置说明

  · 以上全部复用既有 API,后端零改动

- 自助密码重置补终端用户页面(reset.rs):GET /forgot、GET /reset?token=

  · 修真实 bug:send_reset 的重置链接原指向 POST 端点,用户点开必然失败 → 改为 GET 页面

  · oauth.rs 登录页加「忘记密码?」入口;页面渲染用占位符 replace(不用 format!,避开 JS 花括号转义)

- e2e:第 7 套新增 [F] 界面段(15 项断言)→ PASS=36 FAIL=0;七套全 rc=0

- 文档:README / CLAUDE.md / maxkey-migration-analysis / roadmap 同步 UI 说明

- 技能 ipass-core-add-plugin 补「UI 层」章节 + 排错 2 行(SIGPIPE 与 [[ ]] 的坑)
2026-09-14 19:15:29 +08:00

11 KiB
Raw Blame History

MaxKey 能力迁移分析(refs/maxkey → 本项目)

分析日期:2026-09-12 参照物:refs/maxkey/(dromara MaxKey,Java/Gradle,44 张表的完整 IAM/IDaas) 本体:本项目(nginx 动态模块 + Rust,OAuth2/OIDC IdP + IAP,文件+共享内存存储,零外部依赖约定)

结论(先看这里)

MaxKey 值得抄的不是"大而全",而是三类东西:纯算法与协议语义(直接可移植)、域模型设计(表结构即最佳实践文档)、安全运营闭环(锁定/审计/策略,本项目完全缺失)。按本项目的硬约束(无 DB、无 Redis、零新增依赖、"身份层不做流量层"),能力分四档:

档位 数量 判断标准
P0 建议迁移 7 项 纯逻辑可 Rust 重写,且补齐 IAP 安全短板
P1 视需求迁移 5 项 有外部依赖或体积成本,先评估再动
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:建议迁移(纯逻辑,直接补短板)

  1. RS256 + JWKS 签发/验签 — 已在 roadmap v2 规划。 MaxKey 实证:maxkey-commons/maxkey-crypto/(JWS/JWE 签发验签、X509/keystore)。 抄它的点:JWKS 输出格式、kid 轮换语义(旧公钥保留至最后一批旧令牌过期)。

  2. 登录失败锁定 — 本项目目前无任何防爆破机制,这是 IAP 场景最大安全缺口。 MaxKey 实证:mxk_history_login + 登录失败计数策略。移植成本极低:users.json 里加 failed_count / locked_until 字段,共享内存同步,无需新表。

  3. 登录历史 / 审计日志 — MaxKey 用 mxk_history_login / mxk_history_login_apps / mxk_history_event 三张分表。本项目可落成 append-only JSONL 文件(data/audit/), 记录:时间、用户、IP、UA、grant 类型、成功/失败。管理台加一个只读列表即可。 这是"真实流量看板"问题的 SSO 侧基础设施。

  4. 密码策略 — MaxKey:mxk_cnf_password_policy(长度/复杂度/有效期/历史密码)。 本项目最小集:长度 ≥ 8 + 重置时强制改密 + 可选复杂度,配置进现有 config.rs。 纯校验逻辑,半天工作量。

  5. TOTP 双因子 — MaxKey:maxkey-starter-otp/(HOTP/TOTP 算法族)。 纯算法(RFC 6238,HMAC-SHA1 + 30s 步长),Rust 用已有 sha2+手写 HMAC 即可, 不新增依赖。用户侧字段:totp_secret + totp_enabled。注意配套要做绑定流程 (otpauth:// URI 展示)与登录时的第二因子校验分支。

  6. 图形验证码 — MaxKey 用魔改 kaptcha(Java 生态绑定,不抄实现)。 本项目直接生成 SVG 验证码(数字/字母干扰线),零依赖可做, 挂在 /oauth/authorize 登录页与找回密码入口。

  7. 在线会话管理 / 踢出 — MaxKey:SessionController(在线会话查看/踢出)。 本项目 session 已在共享内存(session.rs),天然支持:管理台列出活跃会话 + 单条踢出 + 全端下线。改动量小,运维价值高。


P1:视需求迁移(先评估成本)

  1. SCIM 2.0 身份供给 — MaxKey:maxkey-web-apis/maxkey-web-api-scim/ (User/Group/EnterpriseUser/ServiceProviderConfig 完整资源模型)。 价值:外部系统(HR、上游 IdP)可用标准协议推送用户进来。资源模型清晰, 就是 CRUD,落 users.json/groups 现有模型可行;工作量主要在过滤语义 (userName eq "...")与分页。若确定有上游系统对接需求再做。

  2. CAS 协议端点(v2/v3 validate) — 延续 v1"照抄 MaxKey 文档接入方零改造"的思路, 补 /cas/sso/validate、/p3/proxyValidate 等端点,让 CAS 客户端也能直连。 票据校验是纯逻辑;但 CAS 生态在国内老系统里存量不小,值得排期。

  3. LDAP / AD 认证源 — MaxKey:realm/ldap(OpenLDAP/AD)。企业场景刚需,但 Rust 侧需要 LDAP 客户端库(ldap3 依赖体积不小,且需 vendor)。 替代路径:先用 P1-8 的 SCIM 或 P2-13 的同步连接器"拉取"而非"直连"。

  4. 身份同步连接器(钉钉 / 企微 / 飞书 / AD) — MaxKey: maxkey-synchronizers/maxkey-synchronizer-<name>/。钉钉/企微/飞书三个就是 HTTP API 调用(分页拉用户+组织),交互协议可直接照抄;AD/LDAP 需 LDAP 库。 适合做成定时任务(本项目无后台进程,可用 nginx timer 或外部 cron curl 管理端点触发)。

  5. 自助密码重置(邮箱/短信找回) — MaxKey:mxk_register + 邮件/短信 provider (阿里云/腾讯云/网易云信,maxkey-starter-sms/)。依赖外部发信通道;若做, 建议 provider 抽象成配置驱动的 HTTP 调用(与 AIMALL GenericHTTPTool 同思路)。


P2:低优先(有价值,当前定位用不上)

  1. [skip] WebAuthn / Passkey — MaxKey:maxkey-starter/maxkey-starter-passkey/ (含 mxk_user_passkeys 表)。方向正确但 Rust 零依赖下验签链很重 (COSE/CTAP2/attestation),且 RSA 大数运算本来就在 v2 才引入。等 v2 落地后再评估。

  2. [skip] 社交登录 / 扫码登录 — MaxKey 基于 JustAuth + 自研 WeLink/飞书/企微 request。 本项目作为企业内部身份层,社交登录价值有限;若 souyi.net.cn C 端要用,另起服务。

  3. [skip] SAML 2.0 — MaxKey 重度绑定 OpenSAML。XML-DSig 签名在 Rust 零依赖下工作量 数倍于整个现有 oauth.rs。除非有明确 SAML SP 客户,否则不排期。

  4. [skip] FormBased / TokenBased / ExtendApi 协议 — 老式企业代填/票据协议。 TokenBased 的"票据换会话"语义可作为 IAP 票据机制参考;FormBased 代填不建议。

  5. ip2location 归属地解析 — MaxKey 内置登录 IP 归属地。审计日志做精致了再加。


不建议迁移(明确不做)

能力 理由
Kerberos/SPNEGO、Ws-Federation 重度绑定 JAAS/GSSAPI;IAP 场景可用 nginx 层方案替代
Spring Cloud Gateway 网关(maxkey-gataway) 本项目定位就是"身份层不做流量层",直接冲突
多租户(mxk_institutions) 放大全链路复杂度,当前单租户足够
树形组织架构 roadmap 已有明确"不做"决定,维持
MyBatis/JPA 持久层、44 张表整体照搬 只抄域模型设计思路,不抄存储形态(本项目文件+共享内存)
kaptcha、管理台前端(maxkey-web-frontend) Java/前端技术栈绑定,重写无参考价值

域模型参考(照抄设计而非表)

MaxKey 的 44 张表里,对本项目最有参考价值的三组设计:

  • 应用-协议明细分离:mxk_apps + mxk_apps_oauth_client_details/saml_v20_details/ cas_details/…。本项目现有 oauth_clients.rs 已是同构;未来若补 CAS/SCIM, 沿用"应用主表 + 协议明细"的形状,不要往应用主表里塞协议字段。
  • 审计三分表:登录历史 / 应用登录历史 / 事件,按时间append。对应 P0-3。
  • 配置表与业务表分离:mxk_cnf_*(密码策略、短信、邮件、LDAP 上下文)独立成表。 本项目对应物是 config.rs,未来配置项变多时按此分组,不要混进业务数据。

MaxKey 源码证据索引

  • 认证方式总入口:maxkey-authentications/maxkey-authentication-provider/…/authn/provider/impl/
  • OAuth2/OIDC 端点:maxkey-protocols/maxkey-protocol-oauth-2.0/…/endpoint/(discovery 在 wellknown/)
  • SCIM:maxkey-web-apis/maxkey-web-api-scim/
  • 会话管理:maxkey-webs/maxkey-web-mgt/…/web/access/controller/SessionController
  • 同步连接器: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 表 + 内网/保留段判定,零依赖粗判「内网/中国/海外」 审计日志 / 管理台「会话·审计」页
管理台界面 source/www/admin.html 新增「身份同步」(钉钉/企微/飞书手动触发 + 结果)、「会话 / 审计」(在线会话 + 踢下线 + 审计含归属地)两个页签;账号行加「双因子」;接入指南补 CAS / SCIM / LDAP 三段 tests/maxkey-p1p2-e2e.sh §F
终端用户页面 plugin-sso/src/reset.rs(GET /forgot、GET /reset?token=)+ oauth.rs 登录页入口 自助密码重置的可点开入口;send_reset 的重置链接改为指向页面 URL(原来指向 POST 端点,点开必然失败) §F

环境变量白名单:nginx 默认剥离全部 env,nginx.conf / nginx.test.conf 已加 env SYNC_*、env PASSWORD_RESET_*(未声明则 worker 读不到)。