- 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
23 KiB
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
- crates.io 直接编译失败。
ngx = "0.5"(crates.io 0.5.1)只发布了配置阶段接口HttpModule; 请求阶段 API(add_phase_handler/HttpPhase/HttpRequestHandler)尚未发版, 报unresolved imports ngx::http::HttpPhase。 - git 依赖会永久挂起(最隐蔽的坑)。
ngx-rust挂了一个指向完整 nginx 仓库的 submodule, cargo 解析 git 依赖时会update_submodules去克隆几十 MB 的 nginx 仓库。国内网络下卡死 —— 实测 5 分钟 0% CPU、无网络活动、无产物,sample抓栈停在GitCheckout::update_submodules → fetch → wait4。 - 正解:内核与
ngx-rust放在deps/ipassgit 子模块(指向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时提供,链接时必然未定义。ngxcrate 的 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 可覆盖)。别在宿主机上按容器路径找文件。
核心机制(理解这几条就够)
-
请求分流靠「location 开关 + 阶段」。阶段处理器注册在 http 主配置上(全局生效), 必须靠 location 指令收敛,否则管理台与静态页也会走认证逻辑:
- IAP(access,
sso_iap on):取 Bearer 或sso_sidcookie → 校验 → 写$auth_*→ 放行/401。 - API/协议(content,
ipass_api on):先异步读请求体再分发(access 阶段拿不到 body)。
- IAP(access,
-
共享内存是运行期真源,JSON 文件只是持久化副本。所有写操作同时写 shm 与文件 (write-through)。写穿不是优化,是正确性要求:漏掉
sync_shm等于配置没生效, 而且没有缓存 TTL 兜底——漏了就一直是错的,直到重启。- ⚠️ 语义代价:绕过 API 直接改
data/*.json不热生效,需重启或走管理接口。
- ⚠️ 语义代价:绕过 API 直接改
-
两套身份、两套会话,别混:
- 终端用户:共享内存
sso:前缀 + Cookiesso_sid(OAUTH_SESSION_COOKIE)。 - 管理员:共享内存
sess:前缀 + Cookiesso_admin_session(COOKIE_NAME)。 键前缀还有fail:(登录失败计数)、oac:(授权码)、ocl:(接入方登记)。
- 终端用户:共享内存
-
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之类早就解析失败了。
- 先
-
IAP 防伪造靠「覆盖」而不是「过滤」。
X-Auth-*是网关断言,由proxy_set_header写入,客户端伪造的同名头会被覆盖。新增注入头时必须同时在这两处加:lib.rs的AUTH_VAR_NAMES/set_auth_vars,以及每个受保护 location 的proxy_set_header。 -
IAP 重签令牌的 aud / scope 有专用常量:
IAP_TOKEN_AUDIENCE = "sso-gateway"、IAP_TOKEN_SCOPE = "openid profile email"。改动会影响所有依赖方,改前先全局搜索。 -
口令哈希必须逐位一致:
sha256("salt:password")之后再迭代HASH_ROUNDS(=1000) 次sha256(x + salt)。注意第一轮有冒号。 改轮数或拼接顺序会让存量users.json全部登录失败 (已用独立 Python 实现逐字节核对;scripts/seed-data.sh里是同一套算法的 Python 版)。 -
协议扩展端点(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.confmain 上下文。缺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)
- 建 crate:
deps/ipass子模块里的crates/plugin-xxx,Cargo.toml里写ipass-core.workspace = true, 并在根Cargo.toml的members里登记。 - 实现
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 前的共享内存预装载(返回条数,仅用于日志)
- 在
gateway/src/lib.rs的PLUGINS数组里加一项——数组顺序就是 handler 执行顺序。 - location 开关:在
ipass_core::loc::Switch加枚举项,再改 gateway 的loc_switch与NGX_HTTP_SSO_COMMANDS。 ⚠️ 配置指令只能手工列在 gateway:ngx_module_t.commands是 null-terminated 连续数组,不同 crate 的 static 数组无法自动拼接。 - 需要给账号加字段 → 在
deps/ipass/.../ipass-core/src/models.rs加#[serde(default)]字段。
纪律(违反即失去「共用一份身份」的意义):
- 插件不得直接写
data/users.json,一律经ipass_core::users; - 插件不得自己实现口令校验 / Key 校验 / 锁定——那是内核的事;
- 插件之间不互相依赖,共享信息一律经内核状态表或 nginx 变量。