Files
sso/README.md
T
ssw 8e9becaad7 docs: 插件化架构分析与迁移/任务文档,同步 CLAUDE.md 与路线图
新增
  docs/plugin-architecture-analysis.md  内核/插件边界分析、P 阶段拆分与装配契约
  docs/maxkey-migration-analysis.md     MaxKey 端点别名与 context-path 归一化对齐
  docs/task-plan.md                     阶段任务清单与验收口径

同步
  CLAUDE.md    crate 清单与目录地图:plugin-domain 标为「已迁入示例」,
               plugin-llm 明确「不迁入」(LLM 上游代理与配额计费属流量层,
               与本服务「身份层」的定位分界不变,半成品已从 workspace 移除);
               回归口径五套 → 六套;测试配置端口范围 18093-18099
  README.md    结构树补 plugin-domain,端口范围同步
  roadmap.md   P2 标记为已完成(部分)并写明 plugin-llm 不迁入的理由
2026-09-13 10:25:48 +08:00

243 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 协作者的项目说明:硬约定、目录地图、排障速查