# 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) ```bash # ① 准备 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 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 自动归一化 | ### 管理接口(`/api/admin/*`,需管理员会话 Cookie) | 分类 | 路径 | | --- | --- | | 会话 | `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 上加两段配置即可: ```nginx 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` 打开。 --- ## 生产部署 ```bash # 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 上下文里必须有: ```nginx env ADMIN_INIT_PASSWORD; # 缺了这行模块读到的初始口令恒为空 env OAUTH_SIGNING_SECRET; # 令牌签名密钥(HS256 对称密钥) env OAUTH_ISSUER; # 必须与浏览器实际访问的 host 一致,否则第三方校验 issuer 失败 env OAUTH_COOKIE_DOMAIN; # 跨子域 SSO 才需要;不设 = 主机级 cookie ``` --- ## 测试 ```bash 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`](docs/roadmap.md)。当前两项: 1. **v2:RS256 签名 + `/oauth/jwks`** —— 让第三方本地验签,不必回源 introspect。 2. **用户管理界面** —— 管理台「账号管理」目前只管账号与密钥,缺**角色 / 部门 / 用户组**的可视化维护 (后端接口已可用:`users/profile`、`users/role`)。 --- ## 深入阅读 - [`docs/design.md`](docs/design.md) —— 完整设计:token 模型、共享内存布局、防伪造机制、 MaxKey 差异说明、构建踩坑、测试覆盖清单 - [`CLAUDE.md`](CLAUDE.md) —— 给 AI 协作者的项目说明:硬约定、目录地图、排障速查