Files
sso/docs/maxkey-migration-analysis.md
T
ssw d63beeb15d feat(sso): 应用管理补强 —— CAS service 白名单 / 应用元数据 / 可见范围 / 用户门户
安全修复(重要):CAS 首版未校验 service 白名单,/cas/login?service=https://evil 会把

已登录用户连同 ST-… 一起 302 出去,攻击者可据此换出用户名(开放重定向 + 票据外泄)。

现要求 service 命中某接入方登记的 redirect_uris(精确或忽略 query;绝不做前缀/通配):

login 不过 → 403;validate → no;serviceValidate → INVALID_SERVICE(不复用 INVALID_TICKET)。

校验在签发票据之前;白名单复用「应用管理」注册表,不另开配置。

- 注册表增强:接入方新增 protocol(oauth2/cas) / description / logo_url / home_url /

  visible_roles·depts·groups(三项全空=全员可见),全部 #[serde(default)] 兼容存量 JSON;

  元数据收进 AppMeta 并做归一化校验(访问地址必须 http(s),防 javascript:)

- 用户门户(新建 portal.rs):GET /apps(按可见范围渲染卡片,CAS 应用直达 /cas/login?service=…)

  + GET /api/portal/apps(JSON);未登录 302 到 /login?redirect=<绝对地址>

- oauth::current_user():管理台会话与终端用户 SSO 会话都认;is_safe_redirect 把 127.0.0.1/[::1]

  与 localhost 同待遇(本地才能走完登录回跳)

- 管理台:应用管理表单补齐新字段,列表显示协议徽标 + 可见范围提示

- e2e:第 7 套 [B] 改为先登记 CAS 应用,新增白名单断言;新增 [G] 门户段;[F] 补字段断言

  → PASS=52 FAIL=0,七套全 rc=0

- 文档:README / CLAUDE.md / maxkey-migration-analysis / roadmap / design.md;技能补「必踩点 4、5」

  与「给应用管理加字段的套路」;截图更新(应用管理 + 用户门户)
2026-09-14 19:54:16 +08:00

160 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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-<name>/`。钉钉/企微/飞书三个就是
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 表 + 内网/保留段判定,零依赖粗判「内网/中国/海外」 | 审计日志 / 管理台「会话·审计」页 |
| **管理台界面** | `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 |
| **应用管理增强** | `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 读不到)。