Files
sso/docs/roadmap.md
T
ssw c8a02b8c49 feat: 从网关项目剥离为独立 SSO 统一认证服务
定位:身份层(IdP + IAP),不含动态域名转发 / LLM 上游代理 / 用量计费。

代码(source/rust,nginx 动态模块 + Rust,单进程零外部依赖)
- IdP:authorization_code(含 PKCE)/ refresh_token / client_credentials / password
  四种 grant,含 discovery / introspect / userinfo / jwks 占位
- IAP:access 阶段门禁,注入 X-Auth-* 到后端,客户端伪造同名头被覆盖
- MaxKey 互通:/oauth/v20/* 与 /oauth2.0/* 别名 + context-path 归一化 + 扁平字段
- 管理接口:账号(含角色/部门/用户组)与 OAuth 接入方注册表,热写穿共享内存
- 模块改名 ngx_http_sso_module,指令 sso_state / sso_data_dir / sso_api / sso_iap,
  Cookie sso_sid(终端用户)与 sso_admin_session(管理员)两套身份两套会话

配置(source/conf)
- nginx.conf 生产模板(TLS、IAP 子域、含 auth_sub 的日志格式)
- nginx.test.conf 本机验证配置(明文 18095-18099)
- tls/README.md 证书约定与公钥比对校验

前端(source/www/admin.html)
- 三 tab:账号管理 / 接入方 / 接入指南;去掉审核队列、域名、LLM 上游、用量统计

测试与脚本
- tests/ 三套端到端:协议基线 14 项 · MaxKey 互通与接入 24 项 · 管理接口 31 项,全绿
- tests/demo-system 演示业务系统(Python 标准库),覆盖应用自建客户端与 IAP 零改造两种姿势
- scripts/run-local-e2e.sh 本机一键起停;scripts/seed-data.sh 物化运行时数据目录

文档
- README.md 概览与快速开始;CLAUDE.md 硬约定与排障速查
- docs/design.md 完整设计;docs/roadmap.md 待执行任务(v2 RS256+JWKS、用户管理界面)
2026-09-12 21:42:06 +08:00

149 lines
8.7 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)
---
## [ ] v2:升级 RS256 签名 + `/oauth/jwks`,让第三方本地验签
### 为什么
当前 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 前缀是常量,可直接内联。
### 验收
- [ ] `GET /.well-known/jwks.json` 返回可用 JWKS,`n`/`e` 为 base64url;
- [ ] 用 JWKS 公钥在**不访问本服务**的前提下,本地验签通过 access_token 与 id_token;
- [ ] `alg` 传 `none` / 传 HS256 但用公钥当密钥 → 一律拒绝;
- [ ] 轮换后:新令牌带新 `kid`,旧令牌仍能验签直到过期;
- [ ] 现有三套 e2e 全绿(HS256 存量路径不回归);
- [ ] 新增一套 e2e:抓 JWKS → 本地验签 → 断言 `iss`/`aud`/`exp`。
### 注意
- **`iss` 一致性**是历史上最容易踩的坑:`OAUTH_ISSUER` 必须与浏览器实际访问的 host 一致。
第三方本地验签会把 `iss` 与 discovery 的 `issuer` 逐字符比对,不一致直接失败。
- 私钥**绝对不进版本库**(`.gitignore` 放行规则要写对,别把 `jwks/` 加进白名单)。
- 不要返回空 JWKS:客户端会缓存住「无密钥」状态,问题排查时表现为「一直验签失败、日志无异常」。
---
## [ ] 用户管理界面:角色 / 部门 / 用户组的可视化维护
### 为什么
管理台的「账号管理」现在只能建账号、改显示名、重置口令/密钥、删除,
**角色 / 部门 / 用户组三个字段是只读展示**(表格里注明「接口已可用,界面待做」)。
但这三个字段恰恰是 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。
### 做什么
1. **账号表行内编辑**(或在侧滑面板里):
- `role`:下拉(`admin` / `user`);目标账号是最后一个管理员时**禁用降级**并给出原因,
与后端校验保持一致的文案,避免「点了才报错」。
- `department`:单值,带已有部门的下拉候选 + 允许新建(datalist)。
- `groups`:多值标签输入(逗号或回车确认、可删),候选来自列表接口回显的集合。
2. **列表里的筛选与批量**
- 按角色 / 部门 / 用户组筛选;
- 批量加组 / 移组(按行多选 → 一次提交多条 `users/profile`)。
3. **一致性**
- 提交后立即用返回值刷新本地行数据(不做乐观更新后不回读,避免与「最后一个管理员」这类
服务端裁决不一致);
- 错误提示直接透出后端 `msg`(校验文案已经写得很具体,不要再包一层泛化提示)。
4. **顺手补齐**(同一批改动内,成本很低)
- 统计卡已有「部门 / 用户组」两个数字,点击应能下钻筛选到对应列表。
### 验收
- [ ] 能给账号改角色、部门、用户组,刷新页面后仍在;
- [ ] 最后一个管理员无法被降级(前端禁用 + 后端兜底都生效);
- [ ] 非法输入(含控制字符 / 超长部门名 / 超组数上限)被拒且提示明确;
- [ ] 按角色 / 部门 / 用户组能筛出正确结果;
- [ ] 改完用户组后,经 IAP 访问后端拿到的 `X-Auth-Groups` 同步变化
(端到端验证:改组 → 带会话请求 demo 系统的 `/api/echo` → 断言头部);
- [ ] `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 形状是第三方客户端的契约,
改动需要双方同步,属于「按需改代码」而不是「运营自助」。