Files
sso/CLAUDE.md
T
admin 1e2b117218 refactor(paths): 拆 source/ 包层,顶层与 ipass/ipass 对齐
- 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
2026-09-21 15:44:55 +08:00

23 KiB
Raw Permalink Blame History

CLAUDE.md

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

一句话定位

iPass 统一网关的身份能力:nginx 动态模块(ngx-rust)+ Rust,单进程,无数据库 / Redis / MQ。 代码形态是内核 + 插件(编译期装配,产出单个 .so):

crate 仓库内? 职责
plugin-sso ✅ 本仓库 身份插件:OAuth2.0 / OIDC 授权服务器 + IAP 身份注入
gateway ✅ 本仓库 装配层:module 壳 + 插件注册表 → libsso_gateway.so
ipass-core / plugin-domain / plugin-llm / plugin-apix ⬇️ deps/ipass 子模块 网关内核与通用能力插件(见 ipass/ipass),本仓库不再内置

判据:去掉 SSO,网关还能不能转域名、还能不能代理 LLM? 能 → 那它就不是内核。 内核与通用子系统统一由 deps/ipass git 子模块(ipass/ipass)提供,本仓库只持有 plugin-sso + gateway。

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

为什么是单 .so,而不是「nginx 本来支持的多模块」 nginx 动态模块没有稳定 ABI,Rust 侧更没有(每个 cdylib 各链一份 std,跨模块传 String 就是双重 free)。拆开必撞两个坑:① 共享内存 zone 的 tag 不同 → 启动即 EMERG;② 同名变量(auth_user 等)被后加载者覆盖 get_handler → 行为取决于 load_module 顺序。源码级论证见 docs/plugin-architecture-analysis.md。


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

硬约定: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. 正解:内核与 ngx-rust 放在 deps/ipass git 子模块(指向 ipass/ipass),rust 通过 path 依赖引用它;sso 自己的 Cargo.toml 用 exclude = ["../deps/ipass", "target"] 处理嵌套 workspace,避免重复编译([submodule] deps/ipass 一节见 README「目录结构」)。

为什么要 --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 rust
export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib      # macOS,bindgen 需要
export NGINX_SOURCE_DIR=./build/src/nginx-1.30.4
export NGINX_BUILD_DIR=./build/src/nginx-1.30.4/objs
cargo build --release
# 产物:rust/target/release/libsso_gateway.{dylib,so}

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

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

跑测试

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

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

rust/ 是 Cargo workspace(cargo build 在根跑,产物 target/release/libsso_gateway.dylib):

路径 职责
gateway/src/lib.rs 装配层:指令解析、共享内存建表(state_zone_init,fork 前一次)、PLUGINS 数组、API 的 content 阶段处理器与插件分发、init_process 播种 admin
crates/plugin-sso/src/* 身份插件(本仓库唯一业务 crate):oauth(OAuth2/OIDC 全部逻辑 + IAP 身份解析)/ api(路由表 + handler)/ oauth_clients / oauth_keys(OAuth/IAP 协议常量与共享内存键前缀,原属内核 config)/ oauth_state(OAuthClient 模型 + 注册表/授权码/会话状态,原属内核 state/store)/ rsa(手写 RS256)/ captcha / otp(TOTP 算法 + 账号侧 TOTP,数据存 User.extra)/ scim(SCIM 2.0 身份供给)/ cas(CAS 1.0/2.0 协议端点)/ ldap(LDAP/AD 认证源,零依赖手写 BER)/ sync(钉钉·企微·飞书同步连接器,手动触发)/ reset(自助密码重置)/ geo(登录 IP 归属地)/ portal(终端用户门户「我的应用」)/ compat(内核已移除的 http 辅助 body_object/json_body/send_ct/redirect 的兼容层,避免改子模块)
deps/ipass/rust/crates/ipass-core/src/* 内核(子模块 ipass/ipass):state(通用共享内存原语)/ store(JSON 原子读写)/ users(账号与 Key 的唯一写入口)/ models(仅共性字段 + extra 透传)/ config(仅共性策略常量与键前缀)/ session(管理员会话)/ audit / http / util / plugin(契约)/ loc(location 开关)。不含 OAuth / TOTP 等个性代码
deps/ipass/rust/crates/plugin-domain/src/* 域名插件(子模块 ipass/ipass):keys(sub: 前缀、企业域名 zone、子域名形状与 TTL 常量)/ models(DomainEntry)/ domains(校验、申请/审核/删除、写穿共享内存)/ resolve(access 阶段解析 Host → $proxy_backend_addr)/ api(管理态 + 账号态路由)/ lib(DomainPlugin 装配)

models.rs 的 User 只含共性字段(凭据 / 身份声明 / 锁定);iPass 等插件的个性字段 (llm_* / TOTP 种子等)一律走 User.extra(内核透传、不解释),因此内核不认识也能 直接接管任一边的存量 users.json,且插件加字段不必改内核。

其余:

路径 职责
conf/nginx.conf 生产模板:IdP + 管理台 443、IAP 子域、80→443、含 auth_sub 的日志格式
conf/nginx.test.conf 本机/CI 验证配置(明文 18093-18099:18093/18094 为域名转发回显与转发口),scripts/run-local-e2e.sh 会渲染它
conf/tls/README.md 证书约定、acme.sh 签发、公钥比对校验(ECC 不能用 openssl rsa -modulus)
www/admin.html 管理台单页(五个 tab:账号管理 / OAuth 应用 / 身份同步 / 会话·审计 / 接入指南),纯静态 + fetch;harness 会把模板里的 /usr/local/nginx/www/ 重写到 www/
data-seed/ 种子模板(进版本库):oauth_clients.json + users.json.example
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 (ipass_data_dir 可覆盖)。别在宿主机上按容器路径找文件。


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

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

    • IAP(access,sso_iap on):取 Bearer 或 sso_sid cookie → 校验 → 写 $auth_* → 放行/401。
    • API/协议(content,ipass_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 版)。

  8. 协议扩展端点(SCIM / CAS / 同步 / 密码重置)走「兄弟模块分发」,不改主路由表: api.rs 的 route() 兜底段(_ =>)按 scim → cas → reset → sync → portal 顺序调用各模块的 route(method, uri),命中即用其 (Guard, Handler);各模块自持路径前缀与鉴权级别。 新增同类能力优先照此扩展,不要往主表里逐条塞路径。geo::lookup(ip) 是纯函数, 审计写登录事件时补归属地(内网/中国/海外),无状态。


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

安全与生命周期

  • 不要在 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 里重复实现。同类协议族(SCIM/CAS/…)可放独立模块,在主表兜底段 _ => 分发给它自己的 route()(见「核心机制」第 8 条)。
  • 所有写操作必须同时更新 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,拿到 {} 会报错。
  • 改 rust/ 或 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 或内网拓扑明细。
  • 不要把 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 了。必须用 deps/ipass/rust/vendor/ngx-rust
cargo build 卡住数分钟 0% CPU 又把 ngx 改回 git 依赖了 —— 它挂的 submodule 会去克隆完整 nginx 仓库
链接报 ld: symbol(s) not found 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
新模块读不到 SYNC_* / PASSWORD_RESET_* 等 env nginx 默认剥离全部 env;必须在 nginx.conf/nginx.test.conf main 上下文加 env XXX;,否则 worker 里 std::env::var 恒空
CAS /cas/login?service=… 返回 403 或 serviceValidate 回 INVALID_SERVICE service 不在「应用管理」登记的回调地址里(这是期望行为,防开放重定向/票据外泄)
用户门户 /apps 看不到某个应用 该应用设了可见范围(角色/部门/用户组),当前用户不在内
CAS /cas/login 302 没带 Location http::redirect 发了空 body → create_buffer_from_str("") 返回 None → NGX_ERROR;redirect 的 body 必须非空
e2e 重置类用例把 admin 锁死 别改 admin 种子口令(123456 过不了 8 位策略、无法用重置接口还原);用一次性账号,否则后续套件登录失败会触发 600s 账号锁定
终端用户点邮件里的重置链接报 405 / 空白 链接指向了 POST 端点 POST /api/public/reset-password;必须指向 GET 页面 /reset?token=…(见 reset.rs::send_reset)

常用操作

# ---- 本机 ----
bash scripts/run-local-e2e.sh              # 七套 e2e 全跑
bash scripts/run-local-e2e.sh --keep       # 保留进程手工排查
bash scripts/seed-data.sh                  # 物化 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

bash tests/maxkey-p1p2-e2e.sh http://127.0.0.1:18098   # 单跑第 7 套(SCIM/CAS/重置/同步/LDAP 禁用)

# P1/P2 新增端点(网关在跑时;$JAR 为管理员登录后的 cookie 罐)
curl -s -b "$JAR" http://127.0.0.1:18098/scim/v2/ServiceProviderConfig | python3 -m json.tool
curl -s -b "$JAR" http://127.0.0.1:18098/api/portal/apps | python3 -m json.tool   # 门户:我可见的应用
curl -s http://127.0.0.1:18098/apps            # 门户页面(未登录会 302 到 /login?redirect=…)
curl -s -o/dev/null -w '%{redirect_url}\n' -b "$JAR" 'http://127.0.0.1:18098/cas/login?service=http://app/cb'  # 应见 ?ticket=ST-
curl -s -X POST http://127.0.0.1:18098/api/public/forgot-password --data 'username=alice'   # 自助找回
curl -s -b "$JAR" -X POST http://127.0.0.1:18098/api/admin/sync/dingtalk                    # 手动触发同步(需配 SYNC_*_URL)

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

边界:不要做的事

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

新增一个插件(checklist)

  1. 建 crate:deps/ipass 子模块里的 crates/plugin-xxx,Cargo.toml 里写 ipass-core.workspace = true, 并在根 Cargo.toml 的 members 里登记。
  2. 实现 ipass_core::plugin::Plugin:
    • preconfig —— 注册 nginx 变量(两步缺一不可:ngx_http_add_variable 登记 名字与 handler,ngx_http_get_variable_index 取写入槽位)
    • postconfig —— 注册阶段处理器(ngx::http::add_phase_handler::<T>)
    • dispatch_api —— 管理接口;不归自己处理的路由必须返回 None,否则会抢掉别人的接口
    • zone_load —— fork 前的共享内存预装载(返回条数,仅用于日志)
  3. 在 gateway/src/lib.rs 的 PLUGINS 数组里加一项——数组顺序就是 handler 执行顺序。
  4. location 开关:在 ipass_core::loc::Switch 加枚举项,再改 gateway 的 loc_switch 与 NGX_HTTP_SSO_COMMANDS。 ⚠️ 配置指令只能手工列在 gateway:ngx_module_t.commands 是 null-terminated 连续数组,不同 crate 的 static 数组无法自动拼接。
  5. 需要给账号加字段 → 在 deps/ipass/.../ipass-core/src/models.rs 加 #[serde(default)] 字段。

纪律(违反即失去「共用一份身份」的意义):

  • 插件不得直接写 data/users.json,一律经 ipass_core::users;
  • 插件不得自己实现口令校验 / Key 校验 / 锁定——那是内核的事;
  • 插件之间不互相依赖,共享信息一律经内核状态表或 nginx 变量。