Files
sso/docs/roadmap.md
T
admin 1e2b117218 refactor(paths): 拆 source/ 包层,顶层与 ipass/ipass 对齐
- source/rust   → rust/
- source/conf   → conf/
- source/www    → www/
- source/data-seed → data-seed/
- source/data   → data/
- scripts/ 保留(语义不对应 ipass deploy/)
- /build/ 加入 .gitignore(本机 nginx 源码树)
- README.md 目录树同步 + build 路径 /tmp/sso-build → ./build
- Cargo.toml path 依赖 '../../deps/ipass' → '../deps/ipass'
- CLAUDE.md 同步路径示例

cargo check 通过(52s);release build 通过(1m26s),产物 libsso_gateway.dylib
2026-09-21 15:44:55 +08:00

240 lines
18 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.
# 路线图 / 待执行任务
> 状态标记:`[ ]` 待开工 · `[~]` 进行中 · `[x]` 已完成
> 每项都在「为什么 / 做什么 / 验收 / 注意」四段内自洽,可直接开工。
---
## v1(已完成)
- [x] 从内部网关项目剥离出独立 SSO 服务(去掉动态域名转发 / LLM 上游代理 / 用量计费)
- [x] 目录重组:`docs/` `rust/` `conf/` `www/` `data/` `data-seed/` `tests/` `scripts/`
- [x] 自包含 IdP:四种 grant + PKCE + discovery + introspect + userinfo
- [x] IAP 身份注入:`X-Auth-*` 五头,客户端伪造同名头被覆盖
- [x] MaxKey 端点别名与 context-path 归一化
- [x] 管理台:账号管理 + OAuth 接入方管理 + 接入指南
- [x] 三套端到端回归(协议基线 14 · 互通/接入 24 · 管理接口 31)
---
## [x] v2:升级 RS256 签名 + `/oauth/jwks`,让第三方本地验签(2026-09-13 完成)
### 为什么
当前 access_token / id_token 用 **HS256(对称密钥)** 签名,密钥即 `OAUTH_SIGNING_SECRET`。
对称密钥的根本问题是**不能给第三方**——给了就等于把签发能力也给了。所以现状是:
- 第三方拿到令牌后**无法本地验签**,只能每请求回源 `POST /oauth/introspect`;
- 每个业务系统都要经一次网络往返 + 本服务的可用性依赖,横向扩展时自省成为热点;
- OIDC 生态里的标准库(各类 `jwks` 缓存实现)**用不上**——它们默认 RS256 + JWKS。
`GET /oauth/jwks` 与 `/.well-known/jwks.json` 路由**已在 v1 占位**,当前行为是
「显式 404 + 说明原因」(不返回空 `{"keys":[]}`,避免客户端静默失败)。
### 做什么
1. **密钥对与轮换模型**
- 配置:`OAUTH_JWK_DIR`(默认 `$data_dir/jwks`)下放 `active.pem` + 可选的历史公钥。
- 启动时(`state_zone_init`,fork 前)载入私钥;缺私钥则**首次启动自动生成** 2048-bit RSA
(`openssl` 命令行不可用,需纯 Rust 生成——见「注意」)。
- 支持 `kid`:每把密钥一个稳定 `kid`(如公钥 SHA-256 前 16 位 hex),签发时写进 JWT header。
- 轮换:把新密钥设为 active,旧私钥移出签名集但**公钥保留在 JWKS**,直到最后一批旧令牌过期
(≥ `OAUTH_REFRESH_TTL` = 30 天)。
2. **签名算法抽象**
- 在 `oauth.rs` 抽出 `mint` / `verify` 的算法分支:`HS256`(兼容旧密钥)| `RS256`(默认)。
- `jwt_verify` 按 JWT header 的 `alg` 选择验签方式;**必须白名单校验 `alg`**,
禁止 `none`,禁止拿公钥当 HMAC 密钥(`alg` 混淆攻击)。
- `alg` 决策走配置(`OAUTH_JWT_ALG`,默认 `RS256`),便于灰度:新旧并行期内
用 HS256 签发的存量令牌仍可验签通过。
3. **JWKS 端点**
- 输出标准 JWK:`{"keys":[{"kty":"RSA","use":"sig","alg":"RS256","kid":...,"n":...,"e":...}]}`。
- `n`/`e` 用 **base64url 无填充**(不是标准 base64)。
- 加 `Cache-Control`(如 `public, max-age=3600`),并保证轮换后客户端能及时刷新。
- discovery 的 `jwks_uri` 指向 `/.well-known/jwks.json`,`id_token_signing_alg_values_supported`
改为 `["RS256","HS256"]`。
4. **依赖与体积**
- RSA 需要大数运算。优先评估 **手写**(`modpow` + 已有的 `sha2`)还是引入
`rsa` / `ring` / `num-bigint`——v1 的硬约定是「零新增依赖 / vendor 离线可编译」,
引入前先确认能否 vendor 进 `deps/ipass/rust/vendor/`(内核与 `ngx-rust` 同处子模块)。
- 若用手写:`rsa` crate 的 PKCS#1 v1.5 + SHA-256 + RSASSA-PKCS1-v1_5 编码是固定长度填充,
实现量可控;签名的 `DigestInfo` DER 前缀是常量,可直接内联。
### 验收
- [x] `GET /.well-known/jwks.json` 返回可用 JWKS,`n`/`e` 为 base64url;
- [x] 用 JWKS 公钥在**不访问本服务**的前提下,本地验签通过 access_token 与 id_token(e2e 内嵌纯 Python `pow()` 验签);
- [x] `alg` 传 `none` / 传 HS256 但用公钥当密钥 → 一律拒绝;
- [x] 轮换模型落地(`kid` = 公钥 SHA-256 前 16 位 hex;`from_jwk` 容忍缺私钥分量,历史公钥仍可验);
- [x] 现有三套 e2e 全绿(HS256 存量路径不回归);
- [x] 新增一套 e2e(`tests/rs256-jwks-e2e.sh`:discovery→JWKS→签发→本地验签→篡改/伪造拒绝→introspect)。
### 注意
- **`iss` 一致性**是历史上最容易踩的坑:`OAUTH_ISSUER` 必须与浏览器实际访问的 host 一致。
第三方本地验签会把 `iss` 与 discovery 的 `issuer` 逐字符比对,不一致直接失败。
- **实现落点(2026-09-13)**:RSA 全手写(`src/rsa.rs`:Miller-Rabin、扩展欧几里得模逆、
Montgomery CIOS、CRT、PKCS#1 v1.5 EMSA),零新增 crates 依赖;私钥存
`OAUTH_JWK_DIR/active.jwk.json`(JWK 分量 JSON,非 PEM)。
- 私钥**绝对不进版本库**(`.gitignore` 放行规则要写对,别把 `jwks/` 加进白名单)。
- 不要返回空 JWKS:客户端会缓存住「无密钥」状态,问题排查时表现为「一直验签失败、日志无异常」。
---
## [x] 用户管理界面:角色 / 部门 / 用户组的可视化维护(2026-09-13 完成)
### 为什么
管理台的「账号管理」现在只能建账号、改显示名、重置口令/密钥、删除,
**角色 / 部门 / 用户组三个字段是只读展示**(表格里注明「接口已可用,界面待做」)。
但这三个字段恰恰是 IAP 的实际价值所在:后端收到 `X-Auth-Groups` 后要据此做本地鉴权,
若只能改 `users.json` 文件(还不热生效,必须重启),等于「有分组机制但没法运营」。
**后端接口在 v1 已经就绪且已测**:
| 接口 | 作用 | 校验 |
| --- | --- | --- |
| `POST /api/admin/users/role` | 改角色 | 不允许降级最后一个管理员 |
| `POST /api/admin/users/profile` | 改部门 / 用户组 | 均禁控制字符;部门长度 ≤ `DEPARTMENT_MAX_LEN`;组数 ≤ `GROUPS_MAX`,单组名 ≤ `GROUP_NAME_MAX_LEN` |
| `GET /api/admin/users` | 列表 | 已回显 `departments` / `groups` 取值集合(供前端做候选提示) |
所以本项**纯前端 + 少量交互打磨**,不需要动 Rust。
### 做什么
0. **批量维护接口**(实现时新增):`POST /api/admin/users/batch`,
`usernames` + `add_groups` / `remove_groups` / `department` / `role` / `unlock` 任意组合,
单次文件锁内原子生效;批量降级同样受「至少保留一个管理员」红线约束;
不存在的账号只跳过(`skipped` 回显)不中断整批。
1. **账号表行内编辑**(或在侧滑面板里):
- `role`:下拉(`admin` / `user`);目标账号是最后一个管理员时**禁用降级**并给出原因,
与后端校验保持一致的文案,避免「点了才报错」。
- `department`:单值,带已有部门的下拉候选 + 允许新建(datalist)。
- `groups`:多值标签输入(逗号或回车确认、可删),候选来自列表接口回显的集合。
2. **列表里的筛选与批量**
- 按角色 / 部门 / 用户组筛选;
- 批量加组 / 移组(按行多选 → 一次提交多条 `users/profile`)。
3. **一致性**
- 提交后立即用返回值刷新本地行数据(不做乐观更新后不回读,避免与「最后一个管理员」这类
服务端裁决不一致);
- 错误提示直接透出后端 `msg`(校验文案已经写得很具体,不要再包一层泛化提示)。
4. **顺手补齐**(同一批改动内,成本很低)
- 统计卡已有「部门 / 用户组」两个数字,点击应能下钻筛选到对应列表。
### 验收
- [x] 能给账号改角色、部门、用户组,刷新页面后仍在(角色下拉即改;部门/组点击就地编辑,Enter 保存);
- [x] 最后一个管理员无法被降级(前端 confirm + 失败回滚,后端红线兜底;含批量降级红线,e2e 断言);
- [x] 非法输入(含控制字符 / 超长部门名 / 超组数上限)被拒且提示明确(e2e 断言参数校验);
- [x] 按角色 / 部门 / 用户组(+ 关键字 / 只看已锁定)能筛出正确结果,头部提示「筛选出 n / m 个」;
- [x] 改组后新签令牌经 IAP 注入的 `X-Auth-Groups` 立即反映新组(e2e 断言);并固化语义:
**Bearer 注入是令牌签发时刻的 claims 快照**——改组不影响已签发的旧令牌(到期前),
下游要即时生效就让用户重登/重取令牌,或走 SSO 会话(cookie)路径(e2e 断言双口径);
- [x] `admin.html` 内无内联 `onclick`,无未清理的全局状态(沿用 v1 的写法约定)。
### 注意
- 前端**不能**把 `salt` / `pwd_hash` 带到任何请求或日志里:列表接口刻意不返回它们。
- 用户组名会进 HTTP 头(`X-Auth-Groups`)。后端 `check_groups` 把
`,` `、` `;` 换行/制表/空格**当分隔符切开**(而不是报错),所以组名里永远不可能含逗号——
前端的标签输入要与之一致:用户敲 `a,b` 应得到两个标签「a」「b」,不是一个标签「a,b」;
否则「界面显示一个组、实际存了两个」会很难查。
- 改角色 / 部门 / 组都是**写穿共享内存 + 写文件**,写完即生效(无需重启);
若发现「改完不生效」,先查是不是漏了 `sync_shm` 而不是去重启。
---
## 备注:不建议做的事
- **不要为分组引入树形 / 多级组织架构**。当前模型是「部门(单值)+ 用户组(多值平铺)」,
足以支撑 IAP 的 header 注入与后端本地鉴权;升级成组织树会同时放大前端、校验与同步三处复杂度,
且与本服务「身份层」的定位不符。确有需要时,让下游业务系统用 `X-Auth-Groups` 自己做映射。
- **不要把 OIDC 的 scope / claim 自定义能力做成界面配置**。claim 形状是第三方客户端的契约,
改动需要双方同步,属于「按需改代码」而不是「运营自助」。
---
## 插件化改造(2026-09-13)
架构定稿:内核是 **`ipass-core`**(现由 `deps/ipass` 子模块提供),**SSO 是插件之一**(与 `plugin-domain` / `plugin-llm` 平级);
`users.json` **全局共用一份,由内核独占读写**,插件只读不写。
- [x] workspace 拆分:本仓库 `crates/plugin-sso` + `gateway`,产出**单个** `.so`;内核 `ipass-core` 与通用插件(`plugin-domain` / `plugin-llm`)迁入 `deps/ipass` 子模块
- [x] 内核收口:`config`(仅共性)/ `models`(仅共性 + `extra` 透传)/ `store` / `state`(仅通用原语)/ `session` / `users` / `audit` / `http` / `util`(个性能力 TOTP 归 `plugin-sso` 的 `otp.rs`;OAuth 协议常量/键前缀归 `oauth_keys.rs`、OAuthClient 模型与注册表/授权码/会话状态归 `oauth_state.rs`,均原属内核 `config`/`state`/`store`)
- [x] `User` 共性字段 + `extra` 透传:iPass 等插件的个性字段(`llm_*` / `temp_grant_until` / TOTP 种子等)
经 `extra` 落盘,全部 `#[serde(default)]`;已验证 iPass 存量 `users.json` **无字段丢失**
- [x] 插件契约 `Plugin::{preconfig, postconfig, dispatch_api, zone_load}`;
装配顺序 = `gateway` 里 `PLUGINS` 数组的顺序,**显式可控**
- [x] 五套 e2e 全绿(rc=0),行为与重构前完全等价
- [x] 六套 e2e 全绿(rc=0);域名插件 e2e(`tests/domain-e2e.sh`)随 `plugin-domain` 迁入 `deps/ipass` 子模块(本仓库不再内置)
- [x] P2(部分):`plugin-domain`(域名插件)作为“新增能力插件”的完整示例,已迁入 `deps/ipass` 子模块:crate + `sso_domain` 开关 + 编译装配 + 用例(43 项)。
**`plugin-llm` 明确不迁入**:LLM 上游代理与配额计费属流量层,与本服务定位分界不变(已从 workspace 移除)。
- [ ] 仓库归属:是否新建 `ssw/ipass` 仓库(当前仍在 `ssw/sso`)
> 顺带的收益:iPass 与 SSO 原先各有一份 `oauth.rs`(差异 425 行)、`users.rs`(525 行)、
> `models.rs`(234 行),内核化后只保留一份。
> 架构论证(为什么不拆多 .so)见 `docs/plugin-architecture-analysis.md`。
## [x] v3:MaxKey/JNPF/uc 迁移 P0 补齐(2026-09-13 完成)
> 背景与逐项依据:`docs/maxkey-to-ipass-migration-gap.md`(§0.5 执行状态表)。
- [x] `/sign/api/oauth/v20/me` 路由别名(MaxKey 真实 userinfo 路径,归一化盲区 404)
- [x] scope 逗号+空白切分(authorize 校验与 `has_openid` 同口径;逗号串原先直接 invalid_scope 且吞 id_token)
- [x] `mobile` 身份字段(`User.extra` 通道,check_mobile 校验,create/set_profile/管理台/claims/me 全链)
- [x] me 响应 MaxKey 别名字段:`id`/`userId`/`displayName`/`fullName`(uc 按 maxkey_user_id 建档依赖)
- [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] **管理台界面补齐**(`www/admin.html`):新增「身份同步」页签(钉钉/企微/飞书手动触发 + 结果表)、
「会话 / 审计」页签(在线会话列表 + 踢下线、审计日志含 IP 归属地);账号行加「双因子」按钮;
接入指南补 CAS 1.0/2.0、SCIM 2.0、LDAP/AD 三段端点与配置说明。接入方/Session/审计均复用既有 API,后端零改动。
- [x] **自助密码重置的终端用户页面**:新增 `GET /forgot`(找回)与 `GET /reset?token=…`(设新口令)两个 HTML 页,
登录页加「忘记密码?」入口;并修正 `send_reset` 的链接——原本指向 **POST** 端点,用户点开必然失败。
- [x] **应用管理增强 + 用户门户**(2026-09-14 追加):
· 接入方新增 **协议类型**(oauth2/cas)、**应用访问地址**、**描述**、**图标 URL**、
**可见范围**(角色 / 部门 / 用户组,三项全空 = 全员可见);管理台表单与列表同步,
存量 `oauth_clients.json` 靠 `#[serde(default)]` 向后兼容。
· **CAS `service` 白名单**:`service` 必须命中某个已登记应用的 `redirect_uris`
(精确或忽略 query),否则 login → 403、serviceValidate → `INVALID_SERVICE`。
修掉一个真实的**开放重定向 + 票据外泄**:原先任意 `service` 都会被 302 带上 `ST-…`。
· **用户门户 `GET /apps`**(`portal.rs`):登录后按可见范围列出可访问应用,
卡片直接进入(CAS 应用走 `/cas/login?service=…`);另有 `GET /api/portal/apps` 供前端调用。
· `oauth::current_user()` 统一登录态:管理台会话与终端用户 SSO 会话都认;
`is_safe_redirect` 把 `127.0.0.1` / `[::1]` 与 localhost 同待遇(本地才能走完回跳链路)。
- [x] 修复 `http::redirect` 空 body 触发 `NGX_ERROR`(CAS 302 失效根因);全仓修 `$var` 紧跟全角字符的 shell 坑
> 踩坑留档:① nginx 默认剥离 env,新模块用到的 `SYNC_*` / `PASSWORD_RESET_*` 必须在 conf 里显式 `env`;
> ② 重置类 e2e 不得改 admin 种子口令(`123456` 过不了 8 位策略、无法还原),改用一次性账号闭环;
> ③ 同步 mock 端口避开 nginx 已占用的 18097;
> ④ **页面里 JS 花括号别用 `format!` 拼**——Rust 侧改用「占位符 `replace`」(见 `reset.rs` 的 `FORGOT_PAGE`/`RESET_PAGE`、
> `portal.rs` 的 `APPS_PAGE`),否则每个 `{` 都得写成 `{{`,改一次错一次。
> ⑤ **协议端点别只做「能跑通」**:CAS 的首版就没做 `service` 白名单,等于给任何站点发门票。
> 协议规范里的安全约束(service 白名单、state 校验、PKCE)都要落地,并写进 e2e 断言。
> ⑥ 登录态有两套(管理台会话 / 终端用户 `sso_sid`),面向浏览器的端点必须**两套都认**
> (见 `oauth::current_user`),否则会出现「明明登录了却说未登录」。