Files
sso/docs/roadmap.md
T
ssw d63beeb15d feat(sso): 应用管理补强 —— CAS service 白名单 / 应用元数据 / 可见范围 / 用户门户
安全修复(重要):CAS 首版未校验 service 白名单,/cas/login?service=https://evil 会把

已登录用户连同 ST-… 一起 302 出去,攻击者可据此换出用户名(开放重定向 + 票据外泄)。

现要求 service 命中某接入方登记的 redirect_uris(精确或忽略 query;绝不做前缀/通配):

login 不过 → 403;validate → no;serviceValidate → INVALID_SERVICE(不复用 INVALID_TICKET)。

校验在签发票据之前;白名单复用「应用管理」注册表,不另开配置。

- 注册表增强:接入方新增 protocol(oauth2/cas) / description / logo_url / home_url /

  visible_roles·depts·groups(三项全空=全员可见),全部 #[serde(default)] 兼容存量 JSON;

  元数据收进 AppMeta 并做归一化校验(访问地址必须 http(s),防 javascript:)

- 用户门户(新建 portal.rs):GET /apps(按可见范围渲染卡片,CAS 应用直达 /cas/login?service=…)

  + GET /api/portal/apps(JSON);未登录 302 到 /login?redirect=<绝对地址>

- oauth::current_user():管理台会话与终端用户 SSO 会话都认;is_safe_redirect 把 127.0.0.1/[::1]

  与 localhost 同待遇(本地才能走完登录回跳)

- 管理台:应用管理表单补齐新字段,列表显示协议徽标 + 可见范围提示

- e2e:第 7 套 [B] 改为先登记 CAS 应用,新增白名单断言;新增 [G] 门户段;[F] 补字段断言

  → PASS=52 FAIL=0,七套全 rc=0

- 文档:README / CLAUDE.md / maxkey-migration-analysis / roadmap / design.md;技能补「必踩点 4、5」

  与「给应用管理加字段的套路」;截图更新(应用管理 + 用户门户)
2026-09-14 19:54:16 +08:00

17 KiB
Raw Blame History

路线图 / 待执行任务

状态标记:[ ] 待开工 · [~] 进行中 · [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":[]},避免客户端静默失败)。

做什么

  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(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。

做什么

  1. 批量维护接口(实现时新增):POST /api/admin/users/batch, usernames + add_groups / remove_groups / department / role / unlock 任意组合, 单次文件锁内原子生效;批量降级同样受「至少保留一个管理员」红线约束; 不存在的账号只跳过(skipped 回显)不中断整批。
  2. 账号表行内编辑(或在侧滑面板里):
    • role:下拉(admin / user);目标账号是最后一个管理员时禁用降级并给出原因, 与后端校验保持一致的文案,避免「点了才报错」。
    • department:单值,带已有部门的下拉候选 + 允许新建(datalist)。
    • groups:多值标签输入(逗号或回车确认、可删),候选来自列表接口回显的集合。
  3. 列表里的筛选与批量
    • 按角色 / 部门 / 用户组筛选;
    • 批量加组 / 移组(按行多选 → 一次提交多条 users/profile)。
  4. 一致性
    • 提交后立即用返回值刷新本地行数据(不做乐观更新后不回读,避免与「最后一个管理员」这类 服务端裁决不一致);
    • 错误提示直接透出后端 msg(校验文案已经写得很具体,不要再包一层泛化提示)。
  5. 顺手补齐(同一批改动内,成本很低)
    • 统计卡已有「部门 / 用户组」两个数字,点击应能下钻筛选到对应列表。

验收

  • 能给账号改角色、部门、用户组,刷新页面后仍在(角色下拉即改;部门/组点击就地编辑,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_uri 302 回跳(client 白名单,未登记 400;302 同时清会话 cookie)
  • 管理员重置密码入口统一过 check_password(原可绕过插件层 8 位策略)
  • 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 四项明确跳过。

  • SCIM 2.0 身份供给(plugin-sso/src/scim.rs):ServiceProviderConfig / Schemas / ResourceTypes / Users(全 CRUD + PATCH)/ Groups(派生自账号 groups)
  • CAS 1.0 / 2.0 端点(cas.rs):/cas/login(签发 ST 并 302 回跳)、/cas/validate(纯文本)、 /cas/serviceValidate + /cas/proxyValidate(XML);ST 存共享内存、30s TTL、单次有效、绑定 service
  • LDAP / AD 认证源(ldap.rs):零新增依赖——手工 BER/ASN.1 Simple Bind; env 配置,本地口令失败时兜底尝试、可选自动建号;未启用零行为变化(不破坏既有登录)
  • 同步连接器(钉钉/企微/飞书)(sync.rs):POST /api/admin/sync/<provider> 手动触发, 标准库 TcpStream 拉取 + 归一化契约 upsert;由外部 cron 调用,不引入后台进程
  • 自助密码重置(reset.rs):POST /api/public/forgot-password + /reset-password, token 共享内存、单次有效、防账号枚举;发信可配置(日志 / SINK 文件 / 生产接 SMTP-webhook)
  • ip2location 登录 IP 归属地(geo.rs):内嵌 CN CIDR 精简版,审计记录归属地
  • 新增第 7 套 e2e tests/maxkey-p1p2-e2e.sh(SCIM / CAS / 密码重置 / 同步 / LDAP 禁用回归,21 项); 七套全绿 rc=0
  • 管理台界面补齐(source/www/admin.html):新增「身份同步」页签(钉钉/企微/飞书手动触发 + 结果表)、 「会话 / 审计」页签(在线会话列表 + 踢下线、审计日志含 IP 归属地);账号行加「双因子」按钮; 接入指南补 CAS 1.0/2.0、SCIM 2.0、LDAP/AD 三段端点与配置说明。接入方/Session/审计均复用既有 API,后端零改动。
  • 自助密码重置的终端用户页面:新增 GET /forgot(找回)与 GET /reset?token=…(设新口令)两个 HTML 页, 登录页加「忘记密码?」入口;并修正 send_reset 的链接——原本指向 POST 端点,用户点开必然失败。
  • 应用管理增强 + 用户门户(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 同待遇(本地才能走完回跳链路)。
  • 修复 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),否则会出现「明明登录了却说未登录」。