- 新增「协议扩展端点族」章节:兄弟模块 route() 兜底分发、零新增 crate(手写 BER / TcpStream) - 三条实测坑:新模块 env 白名单、302 空 body→NGX_ERROR、重置类 e2e 勿动 admin 种子口令(锁定级联) - 步骤 6 补 env 白名单铁律;排错表 +3 行;套数更新为七套;删除重复的「基准约定」段
iPass 统一网关 —— 身份插件(nginx 动态模块 + Rust)
本仓库是 iPass 统一网关的代码库,形态是内核 + 插件(编译期装配,产出单个
.so):
crate 职责 ipass-core内核:共享内存状态、 users.json与 API Key 的唯一读写者plugin-sso身份插件(本 README 的主体):OAuth2/OIDC + IAP plugin-domain域名插件:企业域名「子域名 → 后端」转发(新增能力插件的完整示例) 判据:去掉 SSO,网关仍能转域名、仍能代理 LLM → 所以内核不是身份,身份只是插件之一。 架构论证见
docs/plugin-architecture-analysis.md。
自包含的 OAuth2.0 / OIDC 身份提供者(IdP) 与 身份感知代理(IAP), 以 nginx 动态模块形式运行:加载进 nginx,不引入数据库、Redis、消息队列或任何额外常驻进程。
- IdP:签发 access / refresh / id_token,支持
authorization_code(含 PKCE)、refresh_token、client_credentials、password四种 grant,附带 discovery / introspect / userinfo。 - IAP:在 nginx
access阶段做门禁,把身份以X-Auth-*请求头注入到后端, 既有业务系统改一行 nginx 配置即可接入,业务代码零改造。 - 协议兼容 MaxKey:提供
/oauth/v20/*、/oauth2.0/*端点别名与 context-path 归一化, 照抄 MaxKey 文档的第三方应用不用改一行代码。
身份与流量分离:
plugin-sso只回答「你是谁」与「把这个身份告诉后端」。 动态域名转发、LLM 上游代理、用量计费属于其它插件(来源存档见refs/ipass), 与身份插件共用同一份users.json、同一把 API Key——由ipass-core统一读写。
快速开始
依赖
- 一棵已
./configure过的 nginx 1.30.4 源码树(模块须与 nginx 二进制同源编译) - Rust 工具链 +
libclang(bindgen 用) curl、python3(只用于测试脚本与种子生成)
本机跑通端到端(不依赖 Docker)
# ① 准备 nginx 源码树(只需 configure,一次即可)
mkdir -p /tmp/sso-build/src && cd /tmp/sso-build/src
curl -fsSL https://nginx.org/download/nginx-1.30.4.tar.gz -o nginx.tar.gz && tar xzf nginx.tar.gz
curl -fsSL https://github.com/PCRE2Project/pcre2/releases/download/pcre2-10.44/pcre2-10.44.tar.gz -o pcre2.tar.gz && tar xzf pcre2.tar.gz
# ② 编译 nginx(必须含 rewrite 模块:`return` / `error_page` 内部跳转都靠它)
cd nginx-1.30.4
./configure --prefix=/tmp/sso-build/nginx \
--with-pcre=/tmp/sso-build/src/pcre2-10.44 --with-http_realip_module \
--without-http_gzip_module --without-http_ssi_module --without-http_userid_module \
--without-http_autoindex_module --without-http_geo_module \
--without-http_split_clients_module --without-http_referer_module \
--without-http_uwsgi_module --without-http_scgi_module --without-http_grpc_module \
&& make -j"$(sysctl -n hw.ncpu)"
# ③ 编译 Rust 模块
cd <本仓库>/source/rust
export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib # macOS
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
# ④ 一键跑七套端到端(自动播种数据、起 nginx + demo 系统、跑完自动清理)
cd <本仓库> && bash scripts/run-local-e2e.sh
手工观察 IdP / 管理台
bash scripts/run-local-e2e.sh --keep # 保留进程不清理
# 管理台 http://127.0.0.1:18098/admin 账号 admin / 123456
# 演示用户 alice / alice123
# discovery http://127.0.0.1:18098/.well-known/openid-configuration
kill <打印出的 pid>
目录结构
sso/
├── docs/
│ ├── design.md 设计文档:端点、token 模型、共享内存、MaxKey 互通、构建与测试
│ ├── roadmap.md 路线图(v1–v4 已完成 + 待办)
│ └── screenshots/ 管理台与登录页截图
├── source/ 可部署产物(代码 + 配置 + 静态页)
│ ├── rust/ 动态模块源码(Cargo workspace,vendor 了 ngx-rust)
│ │ ├── crates/ipass-core/ 内核:状态 / 账号 / Key 的唯一读写者 / 插件契约
│ │ ├── crates/plugin-sso/ 身份插件:OAuth2 / OIDC + IAP
│ ├── crates/plugin-domain/ 域名插件:企业域名子域名转发(插件示例)
│ │ └── gateway/ 装配层:module 壳 + 插件注册表 → libsso_gateway.so
│ ├── conf/
│ │ ├── nginx.conf 生产模板(TLS、IAP 子域、日志字段)
│ │ ├── nginx.test.conf 本机/CI 验证配置(明文端口 18093-18099)
│ │ └── tls/README.md 证书约定、acme.sh 签发与校验
│ ├── www/admin.html 管理台单页(纯静态 + fetch)
│ ├── data-seed/ 种子模板(进版本库)
│ └── data/ 运行时数据(**不进版本库**,由 scripts/seed-data.sh 生成)
├── tests/ 测试程序与测试应用
│ ├── oauth2-e2e.sh 协议基线(discovery/grant/token/IAP 注入)
│ ├── oauth2-maxkey-e2e.sh MaxKey 互通 + demo 系统接入
│ ├── admin-oauth-clients-e2e.sh 管理接口(接入方注册表)
│ ├── rs256-jwks-e2e.sh RS256 + JWKS 本地验签
│ ├── admin-users-batch-e2e.sh 管理接口(账号批量维护)
│ ├── domain-e2e.sh 域名插件(申请/审核/转发)
│ ├── maxkey-p1p2-e2e.sh MaxKey P1/P2(SCIM/CAS/密码重置/同步/LDAP)
│ └── demo-system/ 演示用「简单业务系统」(Python 标准库)
├── scripts/
│ ├── run-local-e2e.sh 本机一键起停 + 跑七套 e2e
│ └── seed-data.sh 物化运行时数据目录
└── refs/ 参考资料(**不进版本库**):ipass 来源项目、MaxKey
端点一览
认证协议端点
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /oauth/authorize |
授权端点(未登录跳登录页) |
| POST | /oauth/token |
换发令牌(四种 grant) |
| GET/POST | /oauth/userinfo |
当前令牌对应用户声明 |
| POST | /oauth/introspect |
RFC 7662 令牌自省(第三方校验,需客户端鉴权) |
| GET | /.well-known/openid-configuration |
OIDC discovery |
| GET | /oauth/jwks · /.well-known/jwks.json |
公钥集合(RS256,kid 轮换;第三方本地验签,无需回源 introspect) |
| GET/POST | /login |
登录页与表单提交(建立 sso_sid 会话) |
| GET/POST | /oauth/logout |
注销会话 |
MaxKey 兼容别名
| 别名 | 说明 |
|---|---|
/oauth/v20/authorize · /oauth2.0/authorize |
授权端点 |
/oauth/v20/token · /oauth2.0/accessToken |
换发(裸对象响应,不套 {code,msg,data}) |
/oauth/v20/me |
扁平字段 username/userid/realname/email/mobile,令牌走 access_token 参数 |
/oauth2.0/profile · /oauth/v20/logout |
同上 |
/maxkey/... · /sign/authz/... · /sign/... · /authz/... · /api/... 前缀 |
context-path 自动归一化 |
P1/P2 扩展端点(2026-09-14)
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /scim/v2/ServiceProviderConfig · /Schemas · /ResourceTypes |
SCIM 2.0 元数据 |
| GET/POST | /scim/v2/Users |
列表 / 创建(201) |
| GET/PATCH/DELETE | /scim/v2/Users/{id} |
查询 / 增量改 / 删除(204) |
| GET | /scim/v2/Groups |
用户组(派生自账号 groups) |
| GET | /cas/login?service=URL |
已登录签发 ST 并 302 回跳 ?ticket=ST- |
| GET | /cas/validate |
CAS 1.0 纯文本(yes\n<user> / no) |
| GET | /cas/serviceValidate · /cas/proxyValidate |
CAS 2.0 XML |
| GET | /cas/logout |
注销 CAS 会话 |
| POST | /api/public/forgot-password |
自助密码找回(发一次性 token;防账号枚举) |
| POST | /api/public/reset-password |
凭 token 重置口令(单次有效) |
| POST | /api/admin/sync/{dingtalk,workwechat,feishu} |
手动触发身份同步(管理员) |
管理接口(/api/admin/*,需管理员会话 Cookie)
| 分类 | 路径 |
|---|---|
| 会话 | login · logout · session |
| 账号 | users(列表)· users/create · users/key · users/password · users/display · users/profile(部门/用户组)· users/role · users/unlock · users/batch · `users/totp/setup |
| 同步 | sync/dingtalk · sync/workwechat · sync/feishu(手动触发,需配 SYNC_*_URL) |
| 接入方 | oauth-clients(列表)· oauth-clients/save · oauth-clients/rotate · oauth-clients/delete |
账号态 API:GET /api/v1/me(X-API-Key 或 Bearer 鉴权)。
两种接入姿势
方式一:应用自己当 OAuth2 客户端 —— 应用实现授权码流程,拿到令牌代用户调用 API。
适合需要令牌的场景(示例见 tests/demo-system/app.py,支持 maxkey / standard 两种端点风格)。
方式二:前置 IAP,零改造 —— 在业务 location 上加两段配置即可:
location / {
sso_iap on; # access 阶段门禁
proxy_pass http://127.0.0.1:8080;
# ⚠️ 这组 header 由网关断言覆盖,客户端伪造同名头会被盖掉
proxy_set_header X-Auth-User $auth_user;
proxy_set_header X-Auth-Email $auth_email;
proxy_set_header X-Auth-Groups $auth_groups;
proxy_set_header X-Auth-Sub $auth_sub;
proxy_set_header X-Auth-Token $auth_token;
error_page 401 = @oauth_login; # 未登录 → 跳登录页并回跳
}
location @oauth_login { # 注意:named location 不能写 `location = @name`
return 302 "https://sso.yourdomain.com/login?redirect=$scheme://$host$request_uri";
}
后端只读 X-Auth-*,不接触令牌。跨子域 SSO 用 OAUTH_COOKIE_DOMAIN=.yourdomain.com 打开。
生产部署
# 1. 模块装到 nginx
install -m 755 source/rust/target/release/libsso_gateway.so /usr/local/nginx/modules/
# 2. 配置(按环境改域名与证书路径)
cp source/conf/nginx.conf /usr/local/nginx/conf/nginx.conf
cp -r source/www /usr/local/nginx/www
cp -r source/data-seed /usr/local/nginx/data-seed
# 3. 播种账号(生产务必覆盖默认口令)
DATA_DIR=/usr/local/nginx/data ADMIN_PASSWORD='<强口令>' bash scripts/seed-data.sh
# 4. 证书:见 source/conf/tls/README.md(acme.sh 签发 + 公钥比对校验)
# 5. 启动/重载
/usr/local/nginx/sbin/nginx -t && /usr/local/nginx/sbin/nginx
改代码后必须重启,不能 reload —— 动态模块在 load_module 时载入,reload 不会重新读取 .so。
必须显式声明的环境变量
nginx 默认剥离所有环境变量,nginx.conf 的 main 上下文里必须有:
env ADMIN_INIT_PASSWORD; # 缺了这行模块读到的初始口令恒为空
env OAUTH_SIGNING_SECRET; # 令牌签名密钥(HS256 对称密钥)
env OAUTH_ISSUER; # 必须与浏览器实际访问的 host 一致,否则第三方校验 issuer 失败
env OAUTH_COOKIE_DOMAIN; # 跨子域 SSO 才需要;不设 = 主机级 cookie
# P1/P2 新增模块用到的(缺了则 worker 里读不到)
env SYNC_DINGTALK_URL; # 同步连接器:钉钉用户目录源
env SYNC_WORKWECHAT_URL; # 同步连接器:企业微信用户目录源
env SYNC_FEISHU_URL; # 同步连接器:飞书用户目录源
env PASSWORD_RESET_TOKEN_SINK;# 自助密码重置:token 落盘路径(生产可改接 SMTP)
env PASSWORD_RESET_TTL; # 自助密码重置:token 有效期秒(缺省 1800)
# LDAP/AD 认证源(未设置 = 关闭,既有登录行为不变):
env LDAP_ENABLED; # 1 = 启用 LDAP 兜底认证
env LDAP_SERVER; # 如 ldap://127.0.0.1
env LDAP_PORT; # 缺省 389
env LDAP_BASE_DN; # 如 dc=example,dc=com
env LDAP_USER_DN_TEMPLATE; # 如 uid={user},ou=people,dc=example,dc=com
env LDAP_AUTO_CREATE; # 1 = LDAP 认证成功但本地无账号时自动建号
测试
bash scripts/run-local-e2e.sh # 七套全跑(推荐)
bash tests/oauth2-e2e.sh http://127.0.0.1:18098 http://127.0.0.1:18099 # 协议基线
bash tests/oauth2-maxkey-e2e.sh # MaxKey 互通 + demo 接入
bash tests/admin-oauth-clients-e2e.sh # 管理接口(接入方)
bash tests/rs256-jwks-e2e.sh # RS256 + JWKS 验签
bash tests/admin-users-batch-e2e.sh # 管理接口(账号批量)
bash tests/domain-e2e.sh # 域名插件
bash tests/maxkey-p1p2-e2e.sh # SCIM / CAS / 密码重置 / 同步 / LDAP
客户端密钥不硬编码在脚本里,运行时从 $DATA_DIR/oauth_clients.json 读取。
待执行任务
见 docs/roadmap.md。已完成:v2(RS256 + JWKS)、用户管理界面、
v3(MaxKey/JNPF/uc 迁移 P0)、v4(MaxKey 迁移 P1/P2:SCIM 2.0 · CAS · LDAP/AD · 同步连接器 ·
自助密码重置 · 登录 IP 归属地)。明确跳过:WebAuthn/Passkey、SAML 2.0、社交/扫码、FormBased。
明细与依据见 docs/maxkey-migration-analysis.md。
深入阅读
docs/design.md—— 完整设计:token 模型、共享内存布局、防伪造机制、 MaxKey 差异说明、构建踩坑、测试覆盖清单CLAUDE.md—— 给 AI 协作者的项目说明:硬约定、目录地图、排障速查