Files
sso/CLAUDE.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

17 KiB
Raw Blame History

CLAUDE.md

给 AI 协作者(Claude Code / WorkBuddy 等)的项目说明。人读文档见 README.md, 设计细节见 docs/design.md,待办见 docs/roadmap.md。

一句话定位

统一认证服务(SSO):nginx 动态模块(ngx-rust)+ Rust,单进程,无数据库 / Redis / MQ。

  • IdP:OAuth2.0 / OIDC 授权服务器 —— 发 token、登录、introspect、discovery。
  • IAP:nginx access 阶段门禁,把身份以 X-Auth-* 注入后端,业务系统零改造。
  • 协议对齐 MaxKey:端点别名 + 扁平响应,照抄 MaxKey 文档的应用可直接对接。

状态 = data/ 下两个 JSON(users.json / oauth_clients.json); 客户端注册表与会话常驻共享内存,热路径零文件 I/O。

定位差异(不要越界):本项目不做动态域名转发、LLM 上游代理、用量计费。 代码由内部网关项目剥离而来(refs/ipass,仅本地参考、不入库)。 因此这里没有 $proxy_backend_addr 这类动态上游变量,proxy_pass 由 nginx 配置写死。


构建与运行(踩过的坑都在这)

硬约定:ngx 必须用 vendored 源码,不能走 crates.io,也不能走 git

  1. crates.io 直接编译失败。ngx = "0.5"(crates.io 0.5.1)只发布了配置阶段接口 HttpModule; 请求阶段 API(add_phase_handler / HttpPhase / HttpRequestHandler)尚未发版, 报 unresolved imports ngx::http::HttpPhase。
  2. git 依赖会永久挂起(最隐蔽的坑)。ngx-rust 挂了一个指向完整 nginx 仓库的 submodule, cargo 解析 git 依赖时会 update_submodules 去克隆几十 MB 的 nginx 仓库。国内网络下卡死 —— 实测 5 分钟 0% CPU、无网络活动、无产物,sample 抓栈停在 GitCheckout::update_submodules → fetch → wait4。
  3. 正解:源码 vendor 到 source/rust/vendor/ngx-rust/(已剥离 .git,103 个文件 / 696K), Cargo.toml 用 path 依赖;[workspace] exclude = ["vendor/ngx-rust"] 处理嵌套 workspace。

为什么要 --with-pcre=<绝对路径>,以及路径不能随便挪

ngx-rust 的 nginx-sys/build/main.rs 会从 objs/Makefile 抽出编译参数去预处理 ngx_core.h, 其中带 -I <pcre>/src/。所以:

  • nginx 的 ./configure --with-pcre=... 路径,与模块编译时的源码树必须同一份;
  • 把源码树 mv 到别处后,必须重新 ./configure && make(只改环境变量不够)。 不重新 configure 的报错形态是模块编译期: fatal error: 'pcre2.h' file not found(-I 还指着旧路径)。

本机构建

cd source/rust
export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib      # macOS,bindgen 需要
export NGINX_SOURCE_DIR=/tmp/sso-build/src/nginx-1.30.4
export NGINX_BUILD_DIR=/tmp/sso-build/src/nginx-1.30.4/objs
cargo build --release
# 产物:source/rust/target/release/libsso_gateway.{dylib,so}

冷编译约 40 秒,增量 1~2 秒。

source/rust/build.rs 不可删:macOS 必须 -undefined dynamic_lookup——动态模块引用的 nginx 运行时符号由主程序在 load_module 时提供,链接时必然未定义。 ngx crate 的 build.rs 也设了,但 rustc-link-arg 只对设置它的 crate 生效、不传给依赖方。

跑测试

bash scripts/run-local-e2e.sh          # 三套 e2e 全跑(自动起停 nginx + demo 系统)
bash scripts/run-local-e2e.sh --keep   # 保留进程手工排查

目录地图(改代码前先看这里)

路径 职责
source/rust/src/lib.rs 模块入口:指令解析、共享内存建表(state_zone_init,fork 前一次)、变量注册、两个阶段处理器(IAP access / API content)、init_process 播种 admin
source/rust/src/api.rs API 统一分发器:路由表(精确匹配)+ 鉴权分流(Guard::Public/User/Admin)+ 全部 handler
source/rust/src/oauth.rs OAuth2 AS 全部逻辑:client/code/token 模型、HS256 JWT 签名/验签、PKCE、端点 handler、IAP 身份解析
source/rust/src/oauth_clients.rs 接入方注册表(reload_shm / get / all / upsert / delete / view)
source/rust/src/users.rs 账号:播种 admin、创建、改密、重置 Key、角色、部门/用户组校验
source/rust/src/session.rs 管理员登录会话(sess: 键 + HttpOnly Cookie,滑动续期)
source/rust/src/state.rs 共享内存:根结构、键值编解码(栈上拼 key)、业务包装函数
source/rust/src/store.rs JSON 原子读写(.tmp + rename)+ 跨 worker 文件锁 + data 目录
source/rust/src/http.rs 请求辅助:参数合并、两段式请求体读取、JSON 响应输出
source/rust/src/util.rs 随机数、SHA-256、口令哈希、常量时间比较、时间格式化、日志
source/rust/src/config.rs 全部策略常量:TTL、长度上限、共享内存键前缀、cookie 名
source/rust/src/models.rs User / OAuthClient 结构;groups 用宽容反序列化(同时接受 ["a"] 与 "a,b")

其余:

路径 职责
source/conf/nginx.conf 生产模板:IdP + 管理台 443、IAP 子域、80→443、含 auth_sub 的日志格式
source/conf/nginx.test.conf 本机/CI 验证配置(明文 18095-18099),scripts/run-local-e2e.sh 会渲染它
source/conf/tls/README.md 证书约定、acme.sh 签发、公钥比对校验(ECC 不能用 openssl rsa -modulus)
source/www/admin.html 管理台单页(三个 tab:账号 / 接入方 / 接入指南),纯静态 + fetch
source/data-seed/ 种子模板(进版本库):oauth_clients.json + users.json.example
source/data/ 运行时数据(不进版本库,含真实口令散列与 API Key)
scripts/seed-data.sh 物化数据目录:data-seed/ → data/,并生成 admin/alice 真实散列
tests/demo-system/ 演示用「简单业务系统」(Python 标准库),验证两种接入姿势
refs/ 不入版本库:refs/ipass(来源项目)、refs/MaxKey(协议对齐参考)

容器内路径约定:模块装 /usr/local/nginx/modules/,data 默认 /usr/local/nginx/data (sso_data_dir 可覆盖)。别在宿主机上按容器路径找文件。


核心机制(理解这几条就够)

  1. 请求分流靠「location 开关 + 阶段」。阶段处理器注册在 http 主配置上(全局生效), 必须靠 location 指令收敛,否则管理台与静态页也会走认证逻辑:

    • IAP(access,sso_iap on):取 Bearer 或 sso_sid cookie → 校验 → 写 $auth_* → 放行/401。
    • API/协议(content,sso_api on):先异步读请求体再分发(access 阶段拿不到 body)。
  2. 共享内存是运行期真源,JSON 文件只是持久化副本。所有写操作同时写 shm 与文件 (write-through)。写穿不是优化,是正确性要求:漏掉 sync_shm 等于配置没生效, 而且没有缓存 TTL 兜底——漏了就一直是错的,直到重启。

    • ⚠️ 语义代价:绕过 API 直接改 data/*.json 不热生效,需重启或走管理接口。
  3. 两套身份、两套会话,别混:

    • 终端用户:共享内存 sso: 前缀 + Cookie sso_sid(OAUTH_SESSION_COOKIE)。
    • 管理员:共享内存 sess: 前缀 + Cookie sso_admin_session(COOKIE_NAME)。 键前缀还有 fail:(登录失败计数)、oac:(授权码)、ocl:(接入方登记)。
  4. nginx 变量注册必须两步,缺一步就读成空:

    • 先 ngx_http_add_variable(登记名字 + get_handler),再 ngx_http_get_variable_index (取写入槽位)。只调后者:变量被推进 cmcf->variables 但 get_handler=NULL, ngx_http_variables_init_vars 会直接 exit() 报「unknown variable」。
    • 只调前者:拿不到 index,r->variables[idx] 没地方写。
    • 注入变量不能标 NGX_HTTP_VAR_NOCACHEABLE,否则 ngx_http_get_flushed_variable 每次读取都清缓存并回调 get_handler,而 handler 拿不到注入值 → 变量读成空。
    • 注册时机在 preconfiguration:request 阶段才 add_variable 时, proxy_pass http://$auth_user 之类早就解析失败了。
  5. IAP 防伪造靠「覆盖」而不是「过滤」。X-Auth-* 是网关断言,由 proxy_set_header 写入,客户端伪造的同名头会被覆盖。新增注入头时必须同时在这两处加: lib.rs 的 AUTH_VAR_NAMES / set_auth_vars,以及每个受保护 location 的 proxy_set_header。

  6. IAP 重签令牌的 aud / scope 有专用常量:IAP_TOKEN_AUDIENCE = "sso-gateway"、 IAP_TOKEN_SCOPE = "openid profile email"。改动会影响所有依赖方,改前先全局搜索。

  7. 口令哈希必须逐位一致:sha256("salt:password") 之后再迭代 HASH_ROUNDS(=1000) 次 sha256(x + salt)。注意第一轮有冒号。 改轮数或拼接顺序会让存量 users.json 全部登录失败 (已用独立 Python 实现逐字节核对;scripts/seed-data.sh 里是同一套算法的 Python 版)。


硬约定(改代码必须遵守)

安全与生命周期

  • 不要在 worker 里 panic。Cargo.toml 设了 panic = "abort"——一次 panic 直接打死整个 worker (不是 500,是 worker 进程消失)。热路径禁止 unwrap() / expect() / 越界索引, 错误一律走 Result + 显式降级。管理接口也照此办理。
  • 不要在 worker 里起子进程或 shell。文件落盘靠 store 的原子写(.tmp + rename)。
  • 热路径禁止同步文件 I/O。users::get 会读文件 + 全表解码,只能用在管理接口, 不要顺手用在 IAP 鉴权(IAP 走共享内存会话)。

改配置/接口时的硬规矩

  • 新增接口三步:① 在 api.rs 写 handler,统一用 http::ok/fail; ② 在 route() 表加一行,Guard 选 Public / User / Admin; ③ 涉及接入方/账号变更的,必须调对应的 sync_shm。鉴权由分发器统一兜底, 不要在单个 handler 里重复实现。
  • 所有写操作必须同时更新 shm 与 JSON 文件。只写一边 = 「重启后回滚」或「改了不生效」。
  • 写共享内存失败必须出声。state::put_* 返回 false(zone 满 / 分配失败)时要 log_err (带对象标识与后果);reload_shm 要核对「期望条数 vs 实际装载」。别丢掉返回值—— 没有回源兜底,写失败就是「刚建好却调不通,日志里什么都没有」,属于最难查的一类形态。
  • env 白名单必须在 nginx.conf main 上下文。缺 env OAUTH_ISSUER; 会导致 discovery 的 issuer 与第三方实际校验的值不一致——这是最容易踩的坑。
  • client_body_buffer_size 必须大于最大 API 请求体,否则超出的部分落到临时文件, 而 collect_body 只读内存 buf → body 被静默截断(表现为 JSON 解析失败)。 当前管理 server 设 1m。
  • JSON 空数组必须序列化成 []。serde_json 对空 Vec 本来就输出 [], 但别用 json!({}) 顶替列表字段——前端直接 .map/.filter,拿到 {} 会报错。
  • 改 source/rust/ 或 source/conf/ 后必须重启 nginx。动态模块在 load_module 时载入, reload 不会重新加载 .so;data/ 是写穿语义,重启后从文件重建。
  • location @name 不能写成 location = @name。带 = 时 nginx 会把它注册成 「精确匹配普通 location」而 clcf->named 仍为 0,于是 error_page 401 = @oauth_login 的内部跳转在 named_locations[] 里找不到该 location → 500。
  • 自建 nginx 不能 --without-http_rewrite_module:return / error_page 内部跳转都来自它。
  • 前端隐藏元素必须靠 [hidden]{display:none!important} 兜底:author 样式的 display 会盖掉 UA 的 display:none。

文档与仓库卫生

  • 不要在文档里写真实口令、API Key 或内网拓扑明细。
  • 不要把 source/data/(含口令散列与全部 Key)提交进版本库;refs/、.workbuddy/、 target/ 已忽略。
  • 改行为后同步更新 docs/design.md 对应小节;待办项写进 docs/roadmap.md,别散在代码注释里。

排障速查

现象 原因 / 处置
改了代码但行为没变 90% 是没重启。动态模块 load_module 时载入,reload 不重载 .so
worker 进程静默消失 / 全站 502 worker 里 panic 了(panic = "abort")。看 error.log 的 panic 栈,多半是热路径 unwrap()
编译报 unresolved imports ngx::http::HttpPhase 又用 crates.io 的 ngx 0.5.1 了。必须用 source/rust/vendor/ngx-rust
cargo build 卡住数分钟 0% CPU 又把 ngx 改回 git 依赖了 —— 它挂的 submodule 会去克隆完整 nginx 仓库
链接报 ld: symbol(s) not found source/rust/build.rs 的 -undefined dynamic_lookup 被删了(macOS 必需)
nginx 启动即报 unknown "auth_user" variable 变量注册漏了 add_variable 那一步(见「核心机制」第 4 条)
proxy_set_header X-Auth-User $auth_user; 注入成了空 变量被标了 NGX_HTTP_VAR_NOCACHEABLE,或注册时机不在 preconfiguration
授权码换发报 invalid_client 接入方注册表没热加载(写操作漏 sync_shm),或回调地址逐字符不一致
管理接口 401 管理员会话 Cookie 缺失/过期(重启会清空会话,属预期)
终端用户 401 但 Cookie 看着在 两套身份别混:终端用户看 sso_sid,管理员看 sso_admin_session
新增客户端「管理台显示已保存,授权时报未知 client_id」 写穿共享内存时把旧值原样写回了。tests/admin-oauth-clients-e2e.sh 第 4 组专门盯这个
429 登录失败次数过多 同一 IP 窗口内失败次数超限(fail: 前缀),等窗口过期或重启
第三方报 issuer mismatch env OAUTH_ISSUER; 缺失,或值与浏览器实际访问的 host 不一致
跨子域登录不生效(每个子域都要重新登录) 没设 OAUTH_COOKIE_DOMAIN(不设 = 主机级 cookie)
证书看着没过期却报 TLS 错 先 openssl s_client -servername <域名> 看链路实际收到的证书;acme.sh 产物在 ~/.acme.sh/,与 conf/tls/ 是两份,续期后必须拷过去再 reload
--with-pcre 源码树挪位置后编译报 pcre2.h not found 见「构建」小节:必须重新 ./configure && make

常用操作

# ---- 本机 ----
bash scripts/run-local-e2e.sh              # 三套 e2e 全跑
bash scripts/run-local-e2e.sh --keep       # 保留进程手工排查
bash scripts/seed-data.sh                  # 物化 source/data/
bash scripts/seed-data.sh --force          # 重建 users.json(丢已有账号)

# 手工打几个关键接口(网关在跑时)
curl -s http://127.0.0.1:18098/.well-known/openid-configuration | python3 -m json.tool
curl -s -D- -o/dev/null -X POST http://127.0.0.1:18098/login \
  --data-urlencode 'username=alice' --data-urlencode 'password=alice123'   # 看 Set-Cookie: sso_sid
curl -s -b 'sso_sid=<值>' http://127.0.0.1:18098/api/v1/me

# ---- 生产 ----
/usr/local/nginx/sbin/nginx -t && /usr/local/nginx/sbin/nginx   # 改完先 -t 再起

边界:不要做的事

  • 不要引入数据库、Redis、消息队列或额外常驻进程 —— 本项目的价值就是单进程、零依赖。
  • 不要把流量层能力搬回来(动态域名转发、LLM 上游代理、用量计费)。这是与来源项目的定位分界。
  • 不要在 source/data/ 里手工改文件后期待热生效 —— 共享内存才是运行期真源,改文件需重启。
  • 不要把 source/data/ 提交进版本库,也不要在 refs/ 里提交参考项目。
  • 不要重写整个 nginx.conf —— 它很短,逐点修改。
  • 不要在未确认需求前动 source/data/users.json,那会直接影响登录。
  • 不要为了「顺手」把 HS256 换成 RS256(或反之):签名算法是给第三方的契约, 切换要走 docs/roadmap.md 里的 v2 计划(新旧并行 + kid 轮换)。
  • 测试不要复用生产 data 目录:用 source/data/ + 非特权端口(18095-18099),不要占用 80/443。