Files
sso/docs/design.md
T

707 lines
38 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 统一认证设计(自包含 IdP + IAP)
> 目标:**直接实现** OAuth2.0 / OIDC 授权服务器能力,**不依赖 MaxKey 运行时**,
> 但协议层面对齐 MaxKey 的 OAuth2.0 实现,使第三方应用可以像对接 MaxKey 一样对接本服务。
> 同时保留 nginx 反向代理的「自动注入认证信息」能力(Identity-Aware Proxy,IAP)。
>
> **定位**:身份层,不是流量层 —— 不做动态域名转发、不做 LLM 上游代理、不做用量计费。
> 本项目由内部网关项目 `refs/ipass` 剥离而来,砍掉全部流量层能力后独立成库。
---
## 1. 角色定位
| 组件 | 职责 |
| --- | --- |
| **sso(本仓库)** | ① OAuth2.0 / OIDC **授权服务器(IdP)**:发 token、登录、introspect、discovery<br>② **Identity-Aware Proxy(IAP)**:在 access 阶段做门禁,并在 `proxy_set_header` 自动注入 `X-Auth-*` 身份头到后端 |
| **后端服务** | 零改造:只读网关注入的 `X-Auth-*` 头,信任网关身份(不自己做 OAuth) |
| **第三方应用** | OAuth2 客户端:`/oauth/authorize` 跳转登录 → 拿 `code` → `/oauth/token` 换 token → 调资源服务器或 `/oauth/introspect` 校验 |
**与 MaxKey 的关系**:仅作为协议对齐参考(端点路径、声明字段、grant 集合),运行时完全不连 MaxKey。
---
## 2. 设计决策
- **自包含 IdP**:自己签发 token、校验密码、维护客户端注册表,不依赖任何外部 IdP。
- **零新增 crate**:HS256 JWT 的签名 / 验签用手写 `HMAC-SHA256`(复用已有 `sha2`)+ 手写 `base64url` 实现,**不引入任何新依赖**,契合 vendor 离线约束。
- **无共享存储验签**:token 自带签名,`iat/exp/jti` 内嵌,任意 worker 本地验签即可,**不回读用户文件 / 不查库**。
- **HS256 对称签名**:签名密钥来自环境变量 `OAUTH_SIGNING_SECRET`。第三方**不应**持有该密钥,统一走 `/oauth/introspect` 自省(标准、无需密钥)。
- **IAP 防伪造**:复用 LLM 槽位「网关断言身份头、覆盖客户端伪造同名头」模型——后端只信网关注入的 `X-Auth-*`。
---
## 3. 端点(对齐 MaxKey discovery 基准)
| 方法 | 路径 | 说明 | Guard |
| --- | --- | --- | --- |
| GET | `/oauth/authorize` | 授权端点(授权码流程入口,未登录则跳登录页) | Public |
| POST | `/oauth/token` | 换 token:`authorization_code` / `refresh_token` / `client_credentials` / `password` | Public(client 鉴权) |
| GET | `/oauth/userinfo` | 返回当前 Bearer token 对应用户声明 | Public(Bearer) |
| POST | `/oauth/introspect` | RFC 7662 token 自省(第三方校验用,需 client 鉴权) | Public(client 鉴权) |
| GET | `/.well-known/openid-configuration` | OIDC discovery | Public |
| GET | `/oauth/jwks` | 公钥(**HS256 无公钥**,返回 404 + 说明) | Public |
| GET/POST | `/login` | SSO 登录页 + 表单提交(建立 `sso_sid` 会话 cookie) | Public |
| POST | `/oauth/logout` | 注销 SSO 会话(清 cookie + 清共享内存) | Public |
> 所有协议端点走 content 阶段 `ipass_api`(与管理/API server 同 location 收敛);
> IAP 门禁走 access 阶段 `sso_iap`,与协议端点**互不干扰**。
---
## 4. Token 模型(零新增依赖、无共享存储验签)
全部 token 均做成 **HS256 签名的 JWT**,由服务器密钥 `OAUTH_SIGNING_SECRET` 签名。
| token | 声明 `token_type` | 有效期(常量) | 备注 |
| --- | --- | --- | --- |
| access_token | `access` | `OAUTH_ACCESS_TTL` = 3600s | 资源服务器 / introspect 校验;`aud=client_id` |
| refresh_token | `refresh` | `OAUTH_REFRESH_TTL` = 30d | 续期用,含 `jti`;`jwt_verify` 校验 `typ=refresh` |
| id_token | (无 typ,OIDC) | `OAUTH_ID_TOKEN_TTL` = 3600s | 仅 scope 含 `openid` 时随 token 响应一并返回;含 `nonce` |
| authorization code | (**非 JWT**,随机 id) | `OAUTH_CODE_TTL` = 60s | 写入共享内存 `oac:` 前缀(值是该码的授权上下文 JSON),**`take_oauth_code` 取一次即删** |
**JWT 头部**:`{"alg":"HS256","typ":"JWT"}`。
**access_token claims 示例**:
```json
{
"iss": "http://localhost:18098",
"sub": "alice",
"aud": "spa-demo",
"client_id": "spa-demo",
"preferred_username": "爱丽丝",
"email": "[email protected]",
"department": "研发部",
"groups": ["rd", "eng"],
"scope": "openid profile email",
"token_type": "access",
"iat": 1768000000,
"exp": 1768003600,
"jti": "a1b2...16hex"
}
```
**第三方本地验证升级路径(v2)**:引入 `rsa`/`pkcs8` + 发布 `/oauth/jwks`,第三方即可本地验签、无需持有密钥。当前 v1 走 introspect。
---
## 5. 客户端模型(`source/data/oauth_clients.json`)
顶层是 `OAuthClient` 数组(与 `users.json` / `domains.json` 同构:文件是唯一真源,启动时全量装载进共享内存 `ocl:` 前缀,热路径只读内存)。
```json
[
{
"client_id": "grafana",
"client_secret": "cs_grafana_demo_secret_0000000000000000",
"name": "Grafana(演示机密客户端)",
"redirect_uris": ["https://grafana.yourdomain.com/login/generic_oauth"],
"grant_types": ["authorization_code", "refresh_token"],
"scopes": ["openid", "profile", "email"],
"confidential": true,
"created_at": 1768000000
},
{
"client_id": "spa-demo",
"client_secret": "",
"name": "单页应用(演示公开客户端,走 PKCE)",
"redirect_uris": ["https://app.yourdomain.com/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"scopes": ["openid", "profile", "email"],
"confidential": false,
"created_at": 1768000000
},
{
"client_id": "machine",
"client_secret": "cs_machine_demo_secret_0000000000000000",
"name": "机器对机器(演示 client_credentials / password)",
"redirect_uris": [],
"grant_types": ["authorization_code", "refresh_token", "client_credentials", "password"],
"scopes": ["openid", "profile", "email"],
"confidential": true,
"created_at": 1768000000
}
]
```
字段语义:
- `confidential`:`true` 必须带 `client_secret`(`client_secret_basic` / `client_secret_post`);`false` 为公开客户端,授权码流程**强制 PKCE**。
- `grant_types`:实际允许的 grant 白名单(`token` 端点会校验 `allows_grant`)。
- `redirect_uris`:授权码回跳白名单(`authorize`/`token` 均校验)。
- `scopes`:该客户端被允许申请的 scope 集合(`allows_scope`)。
**管理**:本期为**静态 JSON + 手动编辑**,修改后**重启 nginx** 即由 `oauth_clients::reload_shm()` 重新装载(在 `state_zone_init` 阶段调用)。管理台 CRUD API(`/api/admin/oauth-clients/*`)为后续增强项,见 §11。
---
## 6. 用户模型(`source/data/users.json` 新增身份字段)
在既有用户结构基础上,`User` 新增三个 `#[serde(default)]` 字段,支撑 token 声明与 IAP 注入:
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `email` | string | 用户邮箱,写入 `email` 声明 |
| `department` | string | 部门,写入 `department` 声明 |
| `groups` | **string 数组**(如 `["rd","eng"]`) | 用户组,写入 `groups` 声明 |
> ⚠️ `groups` 必须是 JSON 数组。若误写成字符串(`"[rd,eng]"`),`serde` 反序列化
> `Vec<String>` 会整表失败 → `users.json` 被当作损坏、读成空表 → **登录一律
> 「账号或密码错误」**。这类错误不会在启动时报错(`store` 读失败回落 default)。
`User::oauth_claims(issuer, now)` 负责把上述字段拼成标准声明。密码仍沿用既有 `salt + sha256(1000 轮)` 哈希,登录走 `/login` 与 `password` grant 共用 `util::verify_password`。
---
## 7. 授权码流程(浏览器 SSO + PKCE)
```
1. 第三方 app 跳转 https://sso/oauth/authorize?
response_type=code&client_id=spa-demo
&redirect_uri=https://app.yourdomain.com/callback
&scope=openid+profile+email&state=xyz
&code_challenge=<S256(verifier)>&code_challenge_method=S256
2. authorize 端点检查 `sso_sid` 会话 cookie:
- 无会话 → 302 → /login?redirect=<原始请求 URL>
- 有会话 → 生成 code(随机 id,60s 内有效;共享内存里存 PKCE 挑战 +
client_id + redirect_uri + scope + nonce 上下文)
→ 302 → redirect_uri?code=...&state=xyz
3. app 后端 POST /oauth/token
grant_type=authorization_code&code=...&code_verifier=...&redirect_uri=...&client_id=spa-demo
(公开客户端不带 client_secret;机密客户端用 Basic 或表单带 secret)
4. token 端点验 code(take_oauth_code 单次失效)+ 验 PKCE + 校验 client/redirect
→ 返回 { access_token, refresh_token, id_token, expires_in, token_type:"Bearer" }
5. app 带 Authorization: Bearer <access_token> 调资源服务器(过本服务的后端)
或调 /oauth/introspect 自省
```
**IAP 门禁(后端被本服务反向代理时)**:
```
客户端请求 受保护域名 → sso_iap access 阶段 IAPHandler:
- 取 Authorization: Bearer <access_token> 或 sso_sid 会话 cookie
- Bearer:本地 jwt_verify → 验签 + exp
- Cookie:取 sso: 共享内存会话 → 平铺身份 → 现场重签一个 access_token(aud=sso-gateway)
- 通过 → 设置 $auth_user/$auth_email/$auth_groups/$auth_sub/$auth_token
→ proxy_set_header X-Auth-* 注入上游
- 未通过且浏览器 → 返回 401 + WWW-Authenticate: Bearer realm="sso"
→ nginx error_page 401 = @oauth_login → 302 /login?redirect=<原始 URL>
- API 客户端 → 直接 401 + WWW-Authenticate
```
> IAP 注入的 `$auth_sub` 与 `$auth_user` 均为用户标识(username);`$auth_token` 为网关重签的 access_token(Cookie 路径)或原始 Bearer(Bearer 路径)。
---
## 8. 其它 grant
- **refresh_token**:`refresh_token`(验 `typ=refresh`)+ client 鉴权 → 重新签发整套 token。
- **client_credentials**:仅 `confidential` 且 `allows_grant("client_credentials")` 的客户端可用;`sub=client_id`、无 `groups`;返回的 access_token `aud=client_id`。
- **password**:client 允许 `password` + 校验资源所有者账号密码 → 签发标准 token 套件。
客户端鉴权(`authenticate_client`):支持 `Authorization: Basic <base64(client_id:client_secret)>` 与表单/JSON 的 `client_id`+`client_secret`;公开客户端仅校验 `client_id` 存在。
---
## 9. nginx 配置(`conf/nginx.conf`)
新增两个 server(与既有管理/LLM/转发 server 同端口 18098 / 独立 18099):
**IdP server(承载协议端点,明文便于本地启动)**
```nginx
server {
listen 18098;
server_name sso.yourdomain.com;
location /oauth/ { ipass_api on; } # 协议端点
location /.well-known/ { ipass_api on; } # discovery
location = /login { ipass_api on; } # SSO 登录页
}
```
**IAP 受保护代理示例 server**
```nginx
server {
listen 18099;
server_name ~^(?<subdomain>.+)\.app\.yourdomain\.com$;
location / {
sso_iap on; # access 阶段门禁 + 设置 $auth_*
proxy_pass http://127.0.0.1:8080; # 后端地址写死(本层不做动态上游)
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# ---- IAP 身份注入:网关断言覆盖客户端伪造同名头 ----
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;
}
# 注意:named location 不能带 `=` 修饰符
location @oauth_login {
return 302 "https://sso.yourdomain.com/login?redirect=$scheme://$host$request_uri";
}
}
```
> ⚠️ **后端地址不做动态解析**。剥离前的网关有 `$proxy_backend_addr` 这类变量(按域名查表 + `resolver`),
> 本层已删除:sso 只管身份,`proxy_pass` 由 nginx 配置写死或由运维按环境生成。
> ⚠️ **`location @name` 不能写成 `location = @name`**。带 `=` 时 nginx 会把它注册成
> 「精确匹配普通 location」而 `clcf->named` 仍为 0,于是 `error_page 401 = @oauth_login`
> 的内部跳转在 `named_locations[]` 里找不到该 location → 500。`return` 指令来自
> rewrite 模块,自建 nginx 时**不能** `--without-http_rewrite_module`。
> 把任意既有业务接入统一认证:仅在其 location 加 `sso_iap on;` + 这组 `proxy_set_header X-Auth-*`,后端即收到标准化身份头,**后端零改造**。
---
## 10. 共享内存与配置常量
| 前缀 / 常量 | 用途 |
| --- | --- |
| `sso:` | SSO 会话(`put/get/remove_oauth_session`),payload 平铺 `<user>\n<email>\n<groups>\n<dept>\n<name>`(分隔符 `\n`,见下方规则) |
| `oac:` | 授权码(`put/take_oauth_code`,单次失效) |
| `ocl:` | OAuth 客户端注册表(`reload_shm` 全量装载,热路径只读) |
| `OAUTH_SIGNING_SECRET`(env `OAUTH_SIGNING_SECRET`) | HS256 签名密钥(**未设置时进程内随机生成**,多 worker 一致但重启即变,生产必须显式设置) |
| `OAUTH_ISSUER`(env `OAUTH_ISSUER`,默认 `http://localhost:18098`) | `iss` 与 discovery 的 issuer |
| `OAUTH_SESSION_COOKIE = "sso_sid"` | SSO 会话 cookie 名 |
| TTL 常量 | `OAUTH_SESSION_TTL=8h` / `OAUTH_CODE_TTL=60` / `OAUTH_ACCESS_TTL=3600` / `OAUTH_REFRESH_TTL=30d` / `OAUTH_ID_TOKEN_TTL=3600` |
| `OAUTH_SCOPES_SUPPORTED` | `["openid","profile","email","address","phone"]` |
| `OAUTH_CODE_CHALLENGE_METHODS` | `["S256","plain"]` |
### 10.1 共享内存 value 的两条硬规则
1. **payload 里不能出现 `VAL_SEP`(`0x1f`)**。共享内存 value 的格式是
`<payload> \x1f <expires_at>`,`state::split_value` 按**最后一个** `0x1f` 切分
(`rposition`,因为到期时刻恒在末尾)。若 payload 内含 `0x1f`,早期用 `position`
(第一个分隔符)实现会把 payload 腰斩、把残段当 expiry 解析而失败——
表现为**刚写入的会话立刻查不到**(`authorize` 永远判定「未登录」)。
故 `sso:` 的身份字段串用 `\n` 分隔,`ukey:` 的身份 payload 同样用 `\n`。
2. **变量名与写入槽位要分别登记**。`$auth_*` 这类「由模块写、nginx 读」的变量必须
两步都做:
- `ngx_http_add_variable()` —— 把名字登记进 `cmcf->variables_keys` **并挂一个
`get_handler`**;否则 `ngx_http_variables_init_vars` 在启动时报
`unknown "auth_user" variable`(EMERG,直接起不来)。
- `ngx_http_get_variable_index()` —— 拿到 `r->variables[]` 的写入下标。
且**不能**给这类变量加 `NGX_HTTP_VAR_NOCACHEABLE`:`ngx_http_get_flushed_variable`
对 NOCACHEABLE 变量每次读取都会清掉 `valid` 并回调 `get_handler`,
而 handler 拿不到注入值 → 变量读出来是空的。`set_auth_vars` 里写入的
`no_cacheable` 也必须为 0,与变量定义保持一致。
(对比:`$proxy_backend_addr` / `$llm_*` 是「读时计算」,所以它们**要** NOCACHEABLE
且 handler 里现算;两种模式不可混用。)
---
## 11. 代码改动清单(已落地)
| 文件 | 改动 |
| --- | --- |
| `source/rust/src/oauth.rs` | **新增**:OAuth2 AS 全部逻辑(client/code/token 模型、HS256 JWT 签名/验签、PKCE、端点 handler、IAP 身份解析) |
| `source/rust/src/oauth_clients.rs` | **新增**:客户端注册表模块(`reload_shm` / `get` / `all` / `upsert` / `delete` / `view`) |
| `source/rust/src/api.rs` | `route()` 增加 `/oauth/authorize`、`/oauth/token`、`/oauth/userinfo`、`/oauth/introspect`、`.well-known`、`/oauth/jwks`、`/login`、`/oauth/logout`,转发到 `oauth::*` |
| `source/rust/src/lib.rs` | 新增 `sso_iap` 指令 + `IapHandler`(access 阶段门禁 + 写 `$auth_*` 变量);`AUTH_VAR_INDEX[5]` + `AUTH_VAR_NAMES`;`register_auth_vars()`(`add_variable` 挂 `auth_var_get` + `get_variable_index`)在 preconfiguration 注册;`state_zone_init` 调 `oauth_clients::reload_shm()` |
| `source/rust/src/config.rs` | 新增 OAuth 常量区(`KEY_OAUTH_*` 前缀、TTL、cookie、env 名、scopes、challenge 方法) |
| `source/rust/src/models.rs` | `User` 增 `email`/`department`/`groups` + `oauth_claims()`;新增 `OAuthClient` + `OAuthClientTable`(`allows_scope/allows_redirect/allows_grant`) |
| `source/rust/src/state.rs` | 新增 `oauth_session` / `oauth_code` / `oauth_client` 共享内存封装;`split_value` 改用 `rposition` |
| `source/rust/src/store.rs` | 新增 `oauth_clients_path` / `read/write/update_oauth_clients` |
| `source/rust/src/util.rs` | 新增 `url_encode`/`html_escape`;`HEX` 常量提升为模块级 |
| `conf/nginx.conf` | 新增 IdP server(18098)+ IAP 代理 server(18099) |
| `source/conf/nginx.test.conf` | **新增**:本地最小验证配置(IdP 18098 + IAP 18099 + 回显后端 18097) |
| `tests/oauth2-e2e.sh` | **新增**:14 项端到端断言(客户端密钥运行时从种子读取,不硬编码) |
| `scripts/run-local-e2e.sh` | **新增**:macOS 本机 nginx + 模块一键起停并跑 e2e |
| `source/data/users.json` | 种子用户补充 `email`/`department`/`groups`(数组) |
| `source/data/oauth_clients.json`(及 `source/data-seed/`) | 新增 OAuth 客户端注册表(grafana / spa-demo / machine) |
| `rust/vendor/ngx-rust/nginx-sys/build/` | **补回**:`main.rs` + `wrapper.h`(官方 0.5.0 crate 的 bindgen 构建脚本,原被 `.gitignore` 的 `build/` 规则吞掉) |
| `.gitignore` | 加 `!rust/vendor/ngx-rust/nginx-sys/build/` 例外,并放行 `source/data/oauth_clients.json` |
---
## 12. 构建与验证
### 12.1 为什么本机可以直编(不必进容器)
nginx 动态模块的本质约束是:模块 `.dylib`/`.so` 必须针对**同一份 nginx 源码 +
相同 configure 参数**的 nginx 二进制编译加载(ngx-rust 的 `nginx-sys` 用 bindgen
读 `NGINX_SOURCE_DIR` / `NGINX_BUILD_DIR` 生成 ABI 绑定)。所以本机自编一份
nginx 1.30.4 即可,无需 Docker:
```bash
# ① 依赖:PCRE2(rewrite 模块必需)+ nginx 源码
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` 指令来自它)
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)"
# 建 prefix 临时目录(没跑 make install 时 nginx 起不来)
mkdir -p /tmp/sso-build/nginx/{client_body_temp,proxy_temp,fastcgi_temp,uwsgi_temp,scgi_temp,logs,conf}
# ③ 编 Rust 模块(输出 source/rust/target/release/libsso_gateway.dylib)
cd source/rust
export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib
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
```
> `--with-pcre=<绝对路径>` 必须与后面编模块时的源码树**同一个路径**:ngx-rust 的
> `build/main.rs` 会从 `objs/Makefile` 抽出编译参数去预处理 `ngx_core.h`,
> 其中带 `-I <pcre>/src/`。把源码树挪位置而不重新 `./configure && make`,
> 模块编译会报 `fatal error: 'pcre2.h' file not found`。
### 12.2 一键跑端到端
```bash
# 起 nginx(IdP 18098 / IAP 18099 / IAP→demo 18095 / 回显后端 18097)
# + 起 demo-system(18096)→ 跑三套 e2e → 全部停掉
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 http://127.0.0.1:18098 http://127.0.0.1:18096 http://127.0.0.1:18095
bash tests/admin-oauth-clients-e2e.sh http://127.0.0.1:18098
```
脚本自动完成:`scripts/seed-data.sh` 物化 `source/data/`(生成 admin/alice 口令散列)、
生成 macOS 本机配置(替换 `load_module` / `mime.types` / `ipass_data_dir` / `pid` /
`error_log`,注释掉 TLS include,regex `server_name` 降级为 `_`)、注入
`OAUTH_SIGNING_SECRET` + `OAUTH_ISSUER`(可选 `OAUTH_COOKIE_DOMAIN`)、
拉起 demo-system 并等 `/healthz`、等 IdP discovery 就绪、跑三套断言、汇总退出码。
> 配置改写用 **python 而非 sed**:BSD sed 对 `/re/{s###;}` 这类块命令 + `#` 分隔符
> 解析很脆(实测报 `bad flag in substitute command: '}'`),逐行替换更确定。
### 12.3 测试覆盖(基线 14 项 + 互通/接入 24 项 + 管理接口 31 项)
**基线(`tests/oauth2-e2e.sh`,14 项)**:discovery 元数据 / 登录下发会话 Cookie /
授权码 + PKCE(公开客户端) / 授权码(机密客户端 Basic 鉴权) / userinfo /
introspect / client_credentials / password / refresh_token / IAP 无身份拦截
(302 跳登录) / IAP Bearer 注入 / IAP Cookie 注入 / IAP 伪造同名头被覆盖。
**互通/接入(`tests/oauth2-maxkey-e2e.sh`,24 项)**:
- A. MaxKey 别名与传参:`/oauth/v20/authorize`、`/maxkey/...`、`/sign/authz/...`、
`/oauth2.0/authorize` 均命中;token 端点别名命中;表单传 `client_id/secret`
换发成功(无 Basic);`/oauth/v20/me?access_token=` 返回 MaxKey 扁平字段且
**账号语义正确**;`/oauth2.0/profile` 命中;标准端点回归。
- B. demo-system 自建客户端:首页登录入口、`/login` 跳 MaxKey 端点、state 防 CSRF、
授权码回调换发、建本地会话、`/api/me` 取到身份、非法 state 被拒。
- C. IAP 零改造接入:无身份拦截、带会话放行、网关注入 `X-Auth-User`、
业务系统按注入头识别身份、**客户端伪造同名头被覆盖**。
**管理接口(`tests/admin-oauth-clients-e2e.sh`,31 项)**:未登录一律 401 /
管理员登录 / 列表含种子客户端与 issuer、MaxKey 端点别名 / 新建机密客户端生成
`cs_` 密钥 / **热生效**(新建完立刻能授权,专盯「写穿共享内存」)/ 未知 client_id
返回 `invalid_client` / 未注册回调地址返回 `invalid_redirect_uri` / 更新时密钥
留空保留原值 / 参数校验(非 http(s)、带 `#fragment`、未知 grant、授权码模式缺回调)
且**校验失败不污染注册表** / 公开客户端不生成密钥并自动剔除
`client_credentials`·`password` / 重置密钥(新密钥不同、公开客户端拒绝、不存在报错)/
删除后授权请求立即失效。
> 客户端密钥**不在测试脚本里硬编码**:运行时从 `$DATA_DIR/oauth_clients.json` 读取,
> 避免密钥散落。
### 12.4 跑法
本仓库**不提供容器编排**:动态模块必须与 nginx 二进制同源编译,容器里那套
「宿主机编模块、镜像里换 nginx」的路径比直接用本机跑更绕。验证统一走
```bash
bash scripts/run-local-e2e.sh # 起服务 + 三套 e2e + 关服务
bash scripts/run-local-e2e.sh --keep # 保留进程手工排查
```
生产部署见 `source/conf/nginx.conf` + `source/conf/tls/README.md`。
---
## 13. 已知限制 / 后续
- **客户端热管理已落地**:管理台「OAuth 应用」tab + `/api/admin/oauth-clients/{save,rotate,delete}`,保存即生效(写穿共享内存)。文件仍是唯一真源,只是在每次写入时同步,不再需要改文件重启。
- **HS256 对称**:第三方无法本地验签,统一走 introspect;v2 升级 RS256 + `/oauth/jwks`。
- **会话为内存态**:`sso:` 存于共享内存,worker 重启即失效(与现有转发映射一致,属预期)。
- **生产 TLS**:IdP/IAP 示例为明文,生产需在前面套 TLS 或收进内网(参见 `conf/tls/` 机制)。
---
## 14. 首次编译 / 联调暴露并修复的缺陷
以下 6 个问题**都是在第一次真正编译 + 端到端跑通时才暴露**的(此前仅静态审阅,
全部漏过)。记录在此,避免重复踩:
| # | 症状 | 根因 | 修复 |
| --- | --- | --- | --- |
| 1 | 启动即 EMERG `unknown "auth_user" variable` | 只调了 `ngx_http_get_variable_index`(给写入槽位),没调 `ngx_http_add_variable`(登记名字+handler);`ngx_http_variables_init_vars` 找不到 handler 就报 EMERG | `register_auth_vars` 改为「先 `add_variable` 挂 `auth_var_get`,再取 index」 |
| 2 | IAP 变量注入后读到空值 | 给变量标了 `NGX_HTTP_VAR_NOCACHEABLE` → `ngx_http_get_flushed_variable` 每次读取都清缓存并回调 handler,而 handler 无从拿到注入值 | 变量不加 NOCACHEABLE,且 `set_auth_vars` 写 `no_cacheable=0` |
| 3 | `authorize` 永远判定「未登录」,登录后仍 302 回登录页 | `sso_payload` 用 `0x1f` 分隔字段,与共享内存 value 的 `payload/expiry` 分隔符撞车;`split_value` 用 `position`(首个)切分 → payload 腰斩、expiry 解析失败 → `get` 返回 None | `split_value` 改 `rposition`;`sso_payload` 改用 `\n` |
| 4 | 登录一律「账号或密码错误」 | 种子 `users.json` 的 `groups` 被写成字符串 `"[rd,eng]"`,`Vec<String>` 反序列化整表失败 → 用户表读成空(静默回落 default) | 种子改为 JSON 数组 `["rd","eng"]`,并加校验脚本 |
| 5 | `error_page 401 = @oauth_login` 跳不过去 | `location = @oauth_login` 的 `=` 使其成为「精确匹配普通 location」,`clcf->named=0`,`named_locations[]` 里查不到 | 改为 `location @oauth_login` |
| 6 | 全新 checkout 编不过:`vendor/.../nginx-sys/build/main.rs` 不存在 | 根 `.gitignore` 的 `build/` 规则把 vendored 依赖的 bindgen 构建脚本一起吞了(本地磁盘有、git 里没有) | 补回官方 crate 的 `build/`,`.gitignore` 加例外 |
---
## 15. MaxKey OAuth2 互通
目标:**照抄 MaxKey 文档写出来的应用/客户端,不改一行代码就能对接本 IdP**;
反之,本 IdP 的标准端点也仍是标准 OIDC。
### 15.1 MaxKey 自己的端点命名并不统一
MaxKey 各版本/各部署的端点路径彼此不同,社区教程里的写法也跟着分叉:
| 来源 | 授权 | 换发 | 用户信息 |
| --- | --- | --- | --- |
| MaxKey 主线 | `/oauth/v20/authorize` | `/oauth/v20/token` | `/oauth/v20/me` |
| 部分部署/衍生文档 | `/oauth2.0/authorize` | `/oauth2.0/accessToken` | `/oauth2.0/profile` |
| 带 context-path | `/maxkey/oauth/v20/authorize` | `/sign/authz/oauth/v20/token` | `/api/oauth/v20/me` |
| 新版(标准 OIDC) | `/oauth/authorize` | `/oauth/token` | `/oauth/userinfo` |
前两族在 §15.2 映射为别名;第三族的 context-path 在 §15.3 归一化。
### 15.2 端点别名映射
| MaxKey 命名 | 映射到 | 与标准端的差异 |
| --- | --- | --- |
| `GET /oauth/v20/authorize`<br>`GET /oauth2.0/authorize` | `authorize` | 无(纯别名) |
| `GET\|POST /oauth/v20/token`<br>`GET\|POST /oauth2.0/accessToken` | `token_v20` | **响应不套 `{code,msg,data}` 信封**,直接返回 `{"access_token":…}` |
| `GET\|POST /oauth/v20/me`<br>`GET\|POST /oauth2.0/profile` | `userinfo_v20` | 令牌可用 `access_token` 查询/表单参数;返回 **MaxKey 扁平字段** |
| `GET /oauth/v20/logout` | `logout` | 无 |
两个「差异」都是必需的,不是顺手加的:
1. **响应形状**。MaxKey 的 `/oauth/v20/token` 返回裸对象,客户端按顶层键取
`access_token`;标准端点了带信封(`{code,msg,data}`)。若别名也带信封,
照抄 MaxKey 文档的客户端会解析失败(实测表现:拿不到令牌 → 后续全挂)。
故别名走 `send_token_body(r, body, bare=true)`,标准端保持 `bare=false`。
2. **令牌位置与客户端鉴权**。MaxKey 把 `access_token` 放查询/表单参数(不是
Bearer 头),把 `client_id`/`client_secret` 放表单(不是 Basic)。
`access_token_of` 与 `authenticate_client` 两种都收,于是同一套实现同时服务两类客户端。
### 15.3 context-path 归一化
应用的配置项常常是照抄文档的**完整 URL**,把 context-path 一起写进端点地址
(`/maxkey/oauth/v20/token`、`/sign/authz/oauth/v20/authorize`、`/api/oauth/v20/me`)。
为此在路由 miss 之后剥一层已知前缀再试一次:
```rust
const MAXKEY_CONTEXT_PREFIXES: [&str; 5] = ["/maxkey", "/sign/authz", "/sign", "/authz", "/api"];
```
只在**精确路由 miss 之后**调用,所以不会遮蔽真实存在的 `/api/v1/*`、`/api/admin/*`。
### 15.4 配套的 nginx 侧要求
归一化只在请求能到达模块时才生效。原先 IdP server 是
```nginx
location /oauth/ { ipass_api on; }
location /.well-known/ { ipass_api on; }
location = /login { ipass_api on; }
```
`/maxkey/oauth/v20/authorize`、`/oauth2.0/authorize` **不匹配 `/oauth/` 前缀**,
直接吃 nginx 的 HTML 404(模组里的归一化根本没机会跑)。故 IdP server 改为整站交给模块:
```nginx
location / { ipass_api on; }
```
> 教训:**协议端点的 location 不要逐条枚举**——每加一个别名都要改 nginx 配置 + reload,
> 且漏掉时表现为「nginx 404」而不是「接口不存在」的 JSON 404,容易误判为模块 bug。
### 15.5 声明语义(互通里最隐蔽的一条)
`preferred_username` 一度被写成**显示名**(`爱丽丝`),而 `sub` 是登录账号(`alice`)。
字段名齐全、数据也都在,但第三方系统(Grafana 等)普遍用 `preferred_username`
做**账号绑定与查找**,拿到显示名就匹配不上本地账号。
修正为:
| 声明 | 含义 |
| --- | --- |
| `sub` | 登录账号(`alice`) |
| `preferred_username` | 登录账号,便于第三方直接绑定 |
| `name` | 显示名(`爱丽丝`) |
| `username` / `userid`(仅 MaxKey `/me`) | 登录账号 |
| `realname`(仅 MaxKey `/me`) | 显示名 |
`models.rs::User::oauth_claims` 原本就是正确语义,但令牌签发走的是
`oauth.rs::mint_access_token`,两条路径不一致才漏出去 —— 已统一。
### 15.6 代码落点
| 文件 | 改动 |
| --- | --- |
| `source/rust/src/api.rs` | 别名路由表 + `MAXKEY_CONTEXT_PREFIXES` / `strip_maxkey_ctx`,`dispatch` 在 miss 后归一化重试 |
| `source/rust/src/oauth.rs` | `access_token_of`(Bearer → `access_token` 参数回退);`userinfo_v20`(MaxKey 扁平字段);`token_v20` + `send_token_body(bare)`;`mint_access_token` 声明语义修正 |
| `conf/nginx.conf`、`source/conf/nginx.test.conf` | IdP server 整站 `location / { ipass_api on; }` |
| `source/data/oauth_clients.json`、`source/data-seed/` | 新增 `demo-system`(机密)、`demo-spa`(公开 + PKCE) |
---
## 16. 把一个业务系统接进来(demo-system,两种模式)
样例应用在 `examples/demo-system/app.py`(**仅 Python 标准库**,无第三方依赖),
演示同一个业务系统的两种接入姿势。
### 16.1 模式 A:应用自己做 OAuth2 客户端(RP)
```
浏览器 → /login → IdP /authorize → 用户登录 → 302 redirect_uri?code&state
→ 应用 /oauth2/callback:code 换 token → 取 userinfo → 建本地会话 → 首页
```
- `DEMO_STYLE=maxkey`:端点用 `/oauth/v20/*`,`client_id/secret` 走表单,`/me` 用 `access_token` 参数;
- `DEMO_STYLE=standard`:端点用 `/oauth/*`,Basic 鉴权 + Bearer;
- 未配置 `client_secret` 时自动启用 **PKCE(S256)**,按公开客户端走。
适合:有自己会话体系、需要拿到令牌代用户调后端 API 的系统。
### 16.2 模式 B:前置 IAP,业务系统零改造
```nginx
server {
listen 18095;
location / {
sso_iap on; # access 阶段门禁
proxy_pass http://127.0.0.1:18096; # 业务系统
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_demo; # 未登录 → 跳 IdP 登录并回跳
}
location @oauth_login_demo {
return 302 "https://sso.yourdomain.com/login?redirect=$scheme://$host$request_uri";
}
}
```
业务系统不写一行 OAuth 代码,只读 `X-Auth-*`(见 `/api/me` 的 `source=iap` 分支)。
未登录请求在网关就被拦下,**根本不会到达业务系统**;客户端伪造的同名头由网关覆盖。
适合:既有系统改造代价大、或后端是异构技术栈的场景。
> ⚠️ **模式 B 的前提**:业务系统端口**不可被客户端直达**。它无条件信任
> `X-Auth-*`,一旦能直连(如样例里同时暴露 18096 供模式 A 演示),就等于把
> 身份伪造口子敞开。生产上要 `listen 127.0.0.1` / 防火墙白名单 / 只走网关。
> 本样例的 `DEMO_BIND` 默认即 `127.0.0.1`。
### 16.3 环境变量
| 变量 | 默认 | 说明 |
| --- | --- | --- |
| `DEMO_PORT` | `18096` | 监听端口 |
| `DEMO_BIND` | `127.0.0.1` | 绑定地址(见上方安全提示) |
| `DEMO_STYLE` | `maxkey` | `maxkey` \| `standard`,决定端点与传参风格 |
| `DEMO_IDP_BASE` | `http://127.0.0.1:18098` | IdP 地址 |
| `DEMO_CLIENT_ID` | `demo-system` | 客户端 ID |
| `DEMO_CLIENT_SECRET` | 空 | 机密客户端密钥;为空则自动用 PKCE |
| `DEMO_REDIRECT_URI` | `http://127.0.0.1:<port>/oauth2/callback` | 须与注册的 `redirect_uris` **逐字符一致** |
| `DEMO_TRUST_IAP` | `1` | 是否信任 `X-Auth-*`(模式 B) |
端点:`/`(首页)、`/login`、`/oauth2/callback`、`/api/me`、`/api/echo`(回显收到的
`X-Auth-*`,用于验证注入)、`/healthz`、`/logout`。
### 16.4 单独起
```bash
python3 examples/demo-system/app.py # 用默认:maxkey + 18096 + 本地 IdP
# 或
DEMO_STYLE=standard DEMO_CLIENT_ID=demo-spa DEMO_PORT=18096 python3 examples/demo-system/app.py
```
一键端到端(含本文件 §12.2)由 `scripts/run-local-e2e.sh` 覆盖。
---
## 17. 管理台与接入方热管理
### 17.1 界面落在哪
管理台是**单页静态文件** `www/admin.html`(nginx `location = /admin` 直出),
数据全部通过 `/api/admin/*` 拉取,所以:
- 加一个功能 = 加一个 tab(section)+ 一段渲染函数 + 接口调用,无需构建工具链;
- 页面里没有内联密钥/口令,刷新即重新拉取,权限只在后端(`Guard::Admin`)。
本次新增「**OAuth 应用**」tab(在「账号管理」与「LLM 上游」之间),包含三块:
| 区块 | 作用 |
| --- | --- |
| 统一认证端点 | 列出 Discovery / 授权 / 令牌 / 用户信息 的标准端点与 MaxKey 别名,各带「复制」 |
| 新建 / 更新接入方 | client_id、名称、机密/公开、密钥、回调地址(一行一个)、授权类型勾选、scope |
| 接入方列表 | 类型徽标、回调地址、授权类型、scope、脱敏密钥 + 复制、重置密钥、编辑、删除 |
顶部统计卡新增「OAuth 接入方」计数。
![管理台 · OAuth 应用](screenshots/admin-oauth-apps.png)
登录页重做为与管理台同色系的卡片(登录失败时错误条落在卡片内部):
| 正常 | 口令错误 |
| --- | --- |
| ![登录页](screenshots/sso-login.png) | ![登录失败](screenshots/sso-login-error.png) |
截图取自本机运行实例(`scripts/run-local-e2e.sh` 起服务后访问
`http://127.0.0.1:18098/admin`),用系统 Chrome 无头 + CDP 抓取,非设计稿。
### 17.2 管理接口
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/admin/oauth-clients` | 列表 + `issuer` + `endpoints`(含 MaxKey 别名) |
| POST | `/api/admin/oauth-clients/save` | 新建或更新;`client_secret` 缺省 = 保留原值,新建时自动生成 |
| POST | `/api/admin/oauth-clients/rotate` | 重置密钥,返回新密钥明文(旧密钥立即失效) |
| POST | `/api/admin/oauth-clients/delete` | 删除 |
列表类字段(`redirect_uris` / `grant_types` / `scopes`)**传字符串**即可:逗号、顿号、
分号、空格、换行都是分隔符——前端 textarea 一行一个回调地址的自然写法直接可用。
之所以不传 JSON 数组:`http::params` 解析 JSON body 时只收 String/Number/Bool,
数组会被跳过(见 `source/rust/src/http.rs`)。
### 17.3 校验规则(写死在 `oauth_clients::upsert`)
拒绝而不是静默纠正,避免「配了但不生效」的幽灵配置:
- `client_id` 非空;授权类型必须在白名单(`authorization_code` / `refresh_token` /
`client_credentials` / `password`)内;
- 用授权码模式时至少一个回调地址;
- 回调地址必须是 `http(s)://` 绝对地址且不带 `#fragment`——它会被原样用于 302,
白名单里混进 `javascript:` 就等于把授权码送给任意站点;
- **公开客户端不持有密钥**:不生成、改成公开时清掉旧的,并剔除
`client_credentials` / `password`(这两者都要用密钥证明身份)。
### 17.4 热生效与「写穿共享内存」
管理台保存后立刻能授权,靠的是把新值写进 `ocl:` 前缀的共享内存。这里有一个
**曾经踩过的坑**(本次才暴露):
```rust
// ✗ 错:get() 读的就是共享内存,等于把旧值原样写回
if let Some(c) = get(&out.client_id) { state::put_oauth_client(&c.client_id, &payload(&c)); }
// ✓ 对:写本次落盘后的新值
state::put_oauth_client(&out.client_id, &client_payload(&out));
```
症状是「管理台显示已保存,但拿着 client_id 去授权仍报 `invalid_client`」,而重启
网关后又一切正常——因为启动时 `reload_shm()` 从文件全量装载。凡是「文件是唯一真源 +
内存是热路径」的结构,写穿时必须写**新值**,不能读回来再写。
写失败必须出声(项目硬规矩):`put_oauth_client` / `remove_oauth_client` 返回
`false` 时打 error 日志并说明「需重载才生效」,不静默吞掉。
### 17.5 验证
`tests/admin-oauth-clients-e2e.sh`(并入 `scripts/run-local-e2e.sh` 第 3 套,
20 项)覆盖:未登录 401、列表/新建/更新/重置/删除、**新建后立刻可授权**
(热生效,含未知 client_id 与未注册回调的对照断言)、四类参数校验、
公开客户端无密钥且剔除不可用授权类型。