# 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:视需求迁移(先评估成本) 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. [x] **CAS 协议端点(v2/v3 validate)** — 延续 v1"照抄 MaxKey 文档接入方零改造"的思路, 补 `/cas/sso/validate`、`/p3/proxyValidate` 等端点,让 CAS 客户端也能直连。 票据校验是纯逻辑;但 CAS 生态在国内老系统里存量不小,值得排期。 10. [x] **LDAP / AD 认证源** — MaxKey:`realm/ldap`(OpenLDAP/AD)。企业场景刚需,但 Rust 侧需要 LDAP 客户端库(`ldap3` 依赖体积不小,且需 vendor)。 替代路径:先用 P1-8 的 SCIM 或 P2-13 的同步连接器"拉取"而非"直连"。 11. [x] **身份同步连接器(钉钉 / 企微 / 飞书 / AD)** — MaxKey: `maxkey-synchronizers/maxkey-synchronizer-/`。钉钉/企微/飞书三个就是 HTTP API 调用(分页拉用户+组织),交互协议可直接照抄;AD/LDAP 需 LDAP 库。 适合做成定时任务(本项目无后台进程,可用 nginx timer 或外部 cron curl 管理端点触发)。 12. [x] **自助密码重置(邮箱/短信找回)** — MaxKey:`mxk_register` + 邮件/短信 provider (阿里云/腾讯云/网易云信,`maxkey-starter-sms/`)。依赖外部发信通道;若做, 建议 provider 抽象成配置驱动的 HTTP 调用(与 AIMALL GenericHTTPTool 同思路)。 --- ## P2:低优先(有价值,当前定位用不上) 13. [skip] **WebAuthn / Passkey** — MaxKey:`maxkey-starter/maxkey-starter-passkey/` (含 `mxk_user_passkeys` 表)。方向正确但 Rust 零依赖下验签链很重 (COSE/CTAP2/attestation),且 RSA 大数运算本来就在 v2 才引入。等 v2 落地后再评估。 14. [skip] **社交登录 / 扫码登录** — MaxKey 基于 JustAuth + 自研 WeLink/飞书/企微 request。 本项目作为**企业内部身份层**,社交登录价值有限;若 souyi.net.cn C 端要用,另起服务。 15. [skip] **SAML 2.0** — MaxKey 重度绑定 OpenSAML。XML-DSig 签名在 Rust 零依赖下工作量 数倍于整个现有 oauth.rs。除非有明确 SAML SP 客户,否则不排期。 16. [skip] **FormBased / TokenBased / ExtendApi 协议** — 老式企业代填/票据协议。 TokenBased 的"票据换会话"语义可作为 IAP 票据机制参考;FormBased 代填不建议。 17. [x] **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 表 + 内网/保留段判定,零依赖粗判「内网/中国/海外」 | 审计日志 / 管理台「会话·审计」页 | | **管理台界面** | `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 | | **应用管理增强** | `oauth_state.rs` / `oauth_clients.rs` / `admin.html` | 接入方新增 **协议类型**(oauth2/cas)、**访问地址**、**描述**、**图标**、**可见范围**(角色/部门/用户组,三项全空=全员);管理台表单与列表同步(`#[serde(default)]` 向后兼容存量注册表) | §G | | **CAS service 白名单** | `cas.rs` + `oauth_clients::allows_cas_service` | `service` 必须命中已登记回调地址(精确或忽略 query),否则 login → 403、serviceValidate → `INVALID_SERVICE`。**修复开放重定向 + 票据外泄**:原先任意 service 都会被 302 带票据 | §B | | **用户门户「我的应用」** | `plugin-sso/src/portal.rs` | `GET /apps`(会话态,按可见范围过滤后服务端渲染卡片,CAS 应用直接 `/cas/login?service=…` 直达)+ `GET /api/portal/apps`(JSON)。未登录 302 到 `/login?redirect=<绝对地址>` | §G | > 环境变量白名单:nginx 默认剥离全部 env,`nginx.conf` / `nginx.test.conf` 已加 > `env SYNC_*`、`env PASSWORD_RESET_*`(未声明则 worker 读不到)。