- 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
240 lines
18 KiB
Markdown
240 lines
18 KiB
Markdown
# 路线图 / 待执行任务
|
||
|
||
> 状态标记:`[ ]` 待开工 · `[~]` 进行中 · `[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`),否则会出现「明明登录了却说未登录」。
|
||
|