Files
sso/docs/roadmap.md
T
ssw 6409d42817 feat(sso): MaxKey/JNPF/uc 迁移 P0 修复
- /sign/api/oauth/v20/me 归一化盲区:补 /api/oauth/v20/me 路由别名
- scope 逗号+空白切分(authorize 与 has_openid 同口径,避免逗号串吞 id_token)
- mobile 身份字段走 User.extra 全链(check_mobile/create/set_profile/claims/me),
  me 补 MaxKey 别名字段 id/userId/displayName/fullName
- 单点注销:/logout、/sign/logout 别名 + redirect_uri 302 回跳
  (client 白名单,未登记 400;302 同时清会话 cookie)
- 管理员重置密码入口统一过 accounts::check_password
- e2e 互通套新增 A2b/A2c/A2d/A2e/A8b 六条断言,六套回归 rc=0
2026-09-13 22:06:12 +08:00

192 lines
13 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/` `source/` `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 进 `source/rust/vendor/`。
- 若用手写:`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`**,**SSO 是插件之一**(与 `plugin-domain` / `plugin-llm` 平级);
`users.json` **全局共用一份,由内核独占读写**,插件只读不写。
- [x] workspace 拆分:`crates/ipass-core` + `crates/plugin-sso` + `gateway`,产出**单个** `.so`
- [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),新增 `tests/domain-e2e.sh`(域名插件:鉴权 / 转发 / 申请审核 / 写穿生效)
- [x] P2(部分):迁入 `plugin-domain`(域名插件)作为“新增能力插件”的完整示例:crate + `sso_domain` 开关 + 编译装配 + 用例(`tests/domain-e2e.sh`,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