Files
sso/README.md
T
ssw c8a02b8c49 feat: 从网关项目剥离为独立 SSO 统一认证服务
定位:身份层(IdP + IAP),不含动态域名转发 / LLM 上游代理 / 用量计费。

代码(source/rust,nginx 动态模块 + Rust,单进程零外部依赖)
- IdP:authorization_code(含 PKCE)/ refresh_token / client_credentials / password
  四种 grant,含 discovery / introspect / userinfo / jwks 占位
- IAP:access 阶段门禁,注入 X-Auth-* 到后端,客户端伪造同名头被覆盖
- MaxKey 互通:/oauth/v20/* 与 /oauth2.0/* 别名 + context-path 归一化 + 扁平字段
- 管理接口:账号(含角色/部门/用户组)与 OAuth 接入方注册表,热写穿共享内存
- 模块改名 ngx_http_sso_module,指令 sso_state / sso_data_dir / sso_api / sso_iap,
  Cookie sso_sid(终端用户)与 sso_admin_session(管理员)两套身份两套会话

配置(source/conf)
- nginx.conf 生产模板(TLS、IAP 子域、含 auth_sub 的日志格式)
- nginx.test.conf 本机验证配置(明文 18095-18099)
- tls/README.md 证书约定与公钥比对校验

前端(source/www/admin.html)
- 三 tab:账号管理 / 接入方 / 接入指南;去掉审核队列、域名、LLM 上游、用量统计

测试与脚本
- tests/ 三套端到端:协议基线 14 项 · MaxKey 互通与接入 24 项 · 管理接口 31 项,全绿
- tests/demo-system 演示业务系统(Python 标准库),覆盖应用自建客户端与 IAP 零改造两种姿势
- scripts/run-local-e2e.sh 本机一键起停;scripts/seed-data.sh 物化运行时数据目录

文档
- README.md 概览与快速开始;CLAUDE.md 硬约定与排障速查
- docs/design.md 完整设计;docs/roadmap.md 待执行任务(v2 RS256+JWKS、用户管理界面)
2026-09-12 21:42:06 +08:00

227 lines
10 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.
# SSO —— 统一认证服务(nginx 动态模块 + Rust)
自包含的 **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 文档的第三方应用不用改一行代码。
> **定位**:身份层,不是流量层。本服务**不做**动态域名转发、LLM 上游代理、用量计费。
> 代码由内部网关项目剥离而来(来源存档见 `refs/ipass`,不入版本库)。
---
## 快速开始
### 依赖
- 一棵已 `./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)
│ ├── conf/
│ │ ├── nginx.conf 生产模板(TLS、IAP 子域、日志字段)
│ │ ├── nginx.test.conf 本机/CI 验证配置(明文端口 18095-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 协作者的项目说明:硬约定、目录地图、排障速查