ssw f3aabb3405 test(sso): 给管理台会话管理端点补 e2e 回归(A10)
- mgt 会话管理接口(/api/admin/sessions 列表 + /api/admin/sessions/kick 踢出)
  早已实现且仅缺自动化覆盖,本次补足回归:
  - admin 登录 -> 列表含 alice 的 sso 会话
  - 按 username 强制踢出 alice 全部会话(kicked>=1)
  - 踢出后列表清零
  - 边界:kick 缺参 400、非 admin 读列表 401
- 修正断言信封取值:会话列表响应套 {code,data:{items}},原按顶层 items 取误判
- A10 置于脚本末尾(C5 之后),避免踢掉 alice SSO 会话污染 B/C 组业务测试
- 六套 e2e 全绿(互通 rc=0)
2026-09-14 15:50:09 +08:00

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           待执行任务(v2 RS256+JWKS、用户管理界面)
│   └── 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  管理接口(接入方注册表)
│   └── 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 公钥集合(当前 HS256,返回 404 + 原因,见路线图)
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 自动归一化
分类 路径
会话 login · logout · session
账号 users(列表)· users/create · users/key · users/password · users/display · users/profile(部门/用户组)· users/role · users/delete
接入方 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

测试

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            # 管理接口

客户端密钥不硬编码在脚本里,运行时从 $DATA_DIR/oauth_clients.json 读取。


待执行任务

见 docs/roadmap.md。当前两项:

  1. v2:RS256 签名 + /oauth/jwks —— 让第三方本地验签,不必回源 introspect。
  2. 用户管理界面 —— 管理台「账号管理」目前只管账号与密钥,缺角色 / 部门 / 用户组的可视化维护 (后端接口已可用:users/profile、users/role)。

深入阅读

  • docs/design.md —— 完整设计:token 模型、共享内存布局、防伪造机制、 MaxKey 差异说明、构建踩坑、测试覆盖清单
  • CLAUDE.md —— 给 AI 协作者的项目说明:硬约定、目录地图、排障速查
S
Description
SSO 统一认证服务 —— nginx 动态模块 + Rust(自包含 OAuth2/OIDC IdP + IAP 身份注入)
Readme
5.5 MiB
0 Stars 1 Watchers 0 Forks
Languages
HTML 59.9%
Shell 15.4%
Rust 14.3%
Dockerfile 6%
Python 4.4%