- 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
292 lines
15 KiB
Markdown
292 lines
15 KiB
Markdown
# iPass 统一网关 —— 身份插件(nginx 动态模块 + Rust)
|
||
|
||
> 本仓库是 **iPass 统一网关**中 **SSO(单点登录)身份插件**的代码库,形态是**内核 + 插件**(编译期装配,产出单个 `.so`):
|
||
>
|
||
> | crate | 仓库内? | 职责 |
|
||
> | --- | --- | --- |
|
||
> | `plugin-sso` | ✅ 本仓库 | 身份插件(本 README 的主体):OAuth2/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`。
|
||
> 架构论证见 `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 上游代理、用量计费属于**其它插件**,它们与身份插件一同来自
|
||
> `deps/ipass` 子模块(`ipass/ipass`,来源存档见 `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 ./build/src && cd ./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=./build/nginx \
|
||
--with-pcre=./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)"
|
||
|
||
# ③ 拉取内核子模块(首次克隆后只需一次)
|
||
git submodule update --init deps/ipass
|
||
|
||
# ④ 编译 Rust 模块
|
||
cd <本仓库>/rust
|
||
export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib # macOS
|
||
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
|
||
|
||
# ⑤ 一键跑 SSO 端到端(自动播种数据、起 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
|
||
# 页签:账号管理 / OAuth 应用 / 身份同步 / 会话·审计 / 接入指南
|
||
# 演示用户 alice / alice123
|
||
# 终端用户自助找回 http://127.0.0.1:18098/forgot (登录页有「忘记密码?」入口)
|
||
# discovery http://127.0.0.1:18098/.well-known/openid-configuration
|
||
kill <打印出的 pid>
|
||
```
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
sso/
|
||
├── deps/
|
||
│ └── ipass/ # git 子模块 → ipass/ipass:内核 ipass-core + vendor/ngx-rust + 通用插件(plugin-domain/llm/apix) + gateway 装配骨架
|
||
├── docs/
|
||
│ ├── design.md 设计文档:端点、token 模型、共享内存、MaxKey 互通、构建与测试
|
||
│ ├── roadmap.md 路线图(v1–v4 已完成 + 待办)
|
||
│ └── screenshots/ 管理台与登录页截图
|
||
├── rust/ 动态模块源码(本仓库的 Cargo workspace)
|
||
│ ├── Cargo.toml members=[crates/plugin-sso, gateway];ipass-core/ngx-rust 走 deps/ipass 的 path 依赖
|
||
│ ├── crates/plugin-sso/ 身份插件:OAuth2 / OIDC + IAP(本仓库唯一业务 crate)
|
||
│ └── 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/ 测试程序与测试应用(SSO 相关 e2e;域名/LLM 相关见 deps/ipass)
|
||
│ ├── 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 管理接口(账号批量维护)
|
||
│ ├── maxkey-p1p2-e2e.sh MaxKey P1/P2(SCIM/CAS/密码重置/同步/LDAP/应用门户)
|
||
│ └── demo-system/ 演示用「简单业务系统」(Python 标准库)
|
||
├── scripts/
|
||
│ ├── run-local-e2e.sh 本机一键起停 + 跑 SSO 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 会话 |
|
||
| GET | `/forgot` | **找回密码页**(终端用户入口;登录页有「忘记密码?」链接) |
|
||
| GET | `/reset?token=…` | **重置口令页**(凭一次性 token 设置新口令) |
|
||
| POST | `/api/public/forgot-password` | 自助密码找回(发一次性 token;防账号枚举) |
|
||
| POST | `/api/public/reset-password` | 凭 token 重置口令(单次有效) |
|
||
| POST | `/api/admin/sync/{dingtalk,workwechat,feishu}` | 手动触发身份同步(管理员) |
|
||
| GET | `/apps` | **用户门户「我的应用」**(登录后按可见范围列出可访问应用,点击直达) |
|
||
| GET | `/api/portal/apps` | 门户数据的 JSON(未登录 401) |
|
||
|
||
### 管理接口(`/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|enable|disable` · `users/delete` |
|
||
| 同步 | `sync/dingtalk` · `sync/workwechat` · `sync/feishu`(手动触发,需配 `SYNC_*_URL`) |
|
||
| 接入方 | `oauth-clients` · `oauth-clients/save` · `…/rotate` · `…/delete`;字段含 **协议类型**(oauth2/cas)、**访问地址**、**描述**、**图标**、**可见范围**(角色/部门/用户组) |
|
||
| 运维 | `sessions`(在线会话列表)· `sessions/kick`(token / username / all 三种踢法)· `audit`(审计日志,含 IP 归属地) |
|
||
| 接入方 | `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 rust/target/release/libsso_gateway.so /usr/local/nginx/modules/
|
||
|
||
# 2. 配置(按环境改域名与证书路径)
|
||
cp conf/nginx.conf /usr/local/nginx/conf/nginx.conf
|
||
cp -r www /usr/local/nginx/www
|
||
cp -r data-seed /usr/local/nginx/data-seed
|
||
|
||
# 3. 播种账号(生产务必覆盖默认口令)
|
||
DATA_DIR=/usr/local/nginx/data ADMIN_PASSWORD='<强口令>' bash scripts/seed-data.sh
|
||
|
||
# 4. 证书:见 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
|
||
# 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
|
||
bash scripts/run-local-e2e.sh # 本仓库 SSO e2e 全跑(推荐)
|
||
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/maxkey-p1p2-e2e.sh # SCIM / CAS / 密码重置 / 同步 / LDAP
|
||
# 注:域名插件、LLM 上游代理等通用能力插件的 e2e 在 deps/ipass 子模块内运行
|
||
```
|
||
|
||
客户端密钥**不硬编码在脚本里**,运行时从 `$DATA_DIR/oauth_clients.json` 读取。
|
||
|
||
---
|
||
|
||
## 待执行任务
|
||
|
||
见 [`docs/roadmap.md`](docs/roadmap.md)。已完成:v2(RS256 + JWKS)、用户管理界面、
|
||
v3(MaxKey/JNPF/uc 迁移 P0)、v4(MaxKey 迁移 **P1/P2**:SCIM 2.0 · CAS(含 service 白名单)· LDAP/AD · 同步连接器 ·
|
||
自助密码重置 · 登录 IP 归属地 · **应用管理增强与用户门户**)。明确跳过:WebAuthn/Passkey、SAML 2.0、社交/扫码、FormBased。
|
||
明细与依据见 [`docs/maxkey-migration-analysis.md`](docs/maxkey-migration-analysis.md)。
|
||
|
||
---
|
||
|
||
## 深入阅读
|
||
|
||
- [`docs/design.md`](docs/design.md) —— 完整设计:token 模型、共享内存布局、防伪造机制、
|
||
MaxKey 差异说明、构建踩坑、测试覆盖清单
|
||
- [`CLAUDE.md`](CLAUDE.md) —— 给 AI 协作者的项目说明:硬约定、目录地图、排障速查
|