- /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
13 KiB
路线图 / 待执行任务
状态标记:
[ ]待开工 ·[~]进行中 ·[x]已完成 每项都在「为什么 / 做什么 / 验收 / 注意」四段内自洽,可直接开工。
v1(已完成)
- 从内部网关项目剥离出独立 SSO 服务(去掉动态域名转发 / LLM 上游代理 / 用量计费)
- 目录重组:
docs/source/tests/scripts/ - 自包含 IdP:四种 grant + PKCE + discovery + introspect + userinfo
- IAP 身份注入:
X-Auth-*五头,客户端伪造同名头被覆盖 - MaxKey 端点别名与 context-path 归一化
- 管理台:账号管理 + OAuth 接入方管理 + 接入指南
- 三套端到端回归(协议基线 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":[]},避免客户端静默失败)。
做什么
-
密钥对与轮换模型
- 配置:
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 天)。
- 配置:
-
签名算法抽象
- 在
oauth.rs抽出mint/verify的算法分支:HS256(兼容旧密钥)|RS256(默认)。 jwt_verify按 JWT header 的alg选择验签方式;必须白名单校验alg, 禁止none,禁止拿公钥当 HMAC 密钥(alg混淆攻击)。alg决策走配置(OAUTH_JWT_ALG,默认RS256),便于灰度:新旧并行期内 用 HS256 签发的存量令牌仍可验签通过。
- 在
-
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"]。
- 输出标准 JWK:
-
依赖与体积
- RSA 需要大数运算。优先评估 手写(
modpow+ 已有的sha2)还是引入rsa/ring/num-bigint——v1 的硬约定是「零新增依赖 / vendor 离线可编译」, 引入前先确认能否 vendor 进source/rust/vendor/。 - 若用手写:
rsacrate 的 PKCS#1 v1.5 + SHA-256 + RSASSA-PKCS1-v1_5 编码是固定长度填充, 实现量可控;签名的DigestInfoDER 前缀是常量,可直接内联。
- RSA 需要大数运算。优先评估 手写(
验收
GET /.well-known/jwks.json返回可用 JWKS,n/e为 base64url;- 用 JWKS 公钥在不访问本服务的前提下,本地验签通过 access_token 与 id_token(e2e 内嵌纯 Python
pow()验签); alg传none/ 传 HS256 但用公钥当密钥 → 一律拒绝;- 轮换模型落地(
kid= 公钥 SHA-256 前 16 位 hex;from_jwk容忍缺私钥分量,历史公钥仍可验); - 现有三套 e2e 全绿(HS256 存量路径不回归);
- 新增一套 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。
做什么
- 批量维护接口(实现时新增):
POST /api/admin/users/batch,usernames+add_groups/remove_groups/department/role/unlock任意组合, 单次文件锁内原子生效;批量降级同样受「至少保留一个管理员」红线约束; 不存在的账号只跳过(skipped回显)不中断整批。 - 账号表行内编辑(或在侧滑面板里):
role:下拉(admin/user);目标账号是最后一个管理员时禁用降级并给出原因, 与后端校验保持一致的文案,避免「点了才报错」。department:单值,带已有部门的下拉候选 + 允许新建(datalist)。groups:多值标签输入(逗号或回车确认、可删),候选来自列表接口回显的集合。
- 列表里的筛选与批量
- 按角色 / 部门 / 用户组筛选;
- 批量加组 / 移组(按行多选 → 一次提交多条
users/profile)。
- 一致性
- 提交后立即用返回值刷新本地行数据(不做乐观更新后不回读,避免与「最后一个管理员」这类 服务端裁决不一致);
- 错误提示直接透出后端
msg(校验文案已经写得很具体,不要再包一层泛化提示)。
- 顺手补齐(同一批改动内,成本很低)
- 统计卡已有「部门 / 用户组」两个数字,点击应能下钻筛选到对应列表。
验收
- 能给账号改角色、部门、用户组,刷新页面后仍在(角色下拉即改;部门/组点击就地编辑,Enter 保存);
- 最后一个管理员无法被降级(前端 confirm + 失败回滚,后端红线兜底;含批量降级红线,e2e 断言);
- 非法输入(含控制字符 / 超长部门名 / 超组数上限)被拒且提示明确(e2e 断言参数校验);
- 按角色 / 部门 / 用户组(+ 关键字 / 只看已锁定)能筛出正确结果,头部提示「筛选出 n / m 个」;
- 改组后新签令牌经 IAP 注入的
X-Auth-Groups立即反映新组(e2e 断言);并固化语义: Bearer 注入是令牌签发时刻的 claims 快照——改组不影响已签发的旧令牌(到期前), 下游要即时生效就让用户重登/重取令牌,或走 SSO 会话(cookie)路径(e2e 断言双口径); 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 全局共用一份,由内核独占读写,插件只读不写。
- workspace 拆分:
crates/ipass-core+crates/plugin-sso+gateway,产出单个.so - 内核收口:
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) User共性字段 +extra透传:iPass 等插件的个性字段(llm_*/temp_grant_until/ TOTP 种子等) 经extra落盘,全部#[serde(default)];已验证 iPass 存量users.json无字段丢失- 插件契约
Plugin::{preconfig, postconfig, dispatch_api, zone_load}; 装配顺序 =gateway里PLUGINS数组的顺序,显式可控 - 五套 e2e 全绿(rc=0),行为与重构前完全等价
- 六套 e2e 全绿(rc=0),新增
tests/domain-e2e.sh(域名插件:鉴权 / 转发 / 申请审核 / 写穿生效) - 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 执行状态表)。
/sign/api/oauth/v20/me路由别名(MaxKey 真实 userinfo 路径,归一化盲区 404)- scope 逗号+空白切分(authorize 校验与
has_openid同口径;逗号串原先直接 invalid_scope 且吞 id_token) mobile身份字段(User.extra通道,check_mobile 校验,create/set_profile/管理台/claims/me 全链)- me 响应 MaxKey 别名字段:
id/userId/displayName/fullName(uc 按 maxkey_user_id 建档依赖) - 单点注销:
/logout、/sign/logout别名 +redirect_uri302 回跳(client 白名单,未登记 400;302 同时清会话 cookie) - 管理员重置密码入口统一过
check_password(原可绕过插件层 8 位策略) - e2e:互通套新增 A2b/A2c/A2d/A2e/A8b 六条断言,六套 rc=0