38 KiB
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 ② 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 示例:
{
"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: 前缀,热路径只读内存)。
[
{
"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_tokenaud=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(承载协议端点,明文便于本地启动)
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
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 的两条硬规则
-
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。 -
变量名与写入槽位要分别登记。
$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:
# ① 依赖: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 一键跑端到端
# 起 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 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/authorizeGET /oauth2.0/authorize |
authorize |
无(纯别名) |
GET|POST /oauth/v20/tokenGET|POST /oauth2.0/accessToken |
token_v20 |
响应不套 {code,msg,data} 信封,直接返回 {"access_token":…} |
GET|POST /oauth/v20/meGET|POST /oauth2.0/profile |
userinfo_v20 |
令牌可用 access_token 查询/表单参数;返回 MaxKey 扁平字段 |
GET /oauth/v20/logout |
logout |
无 |
两个「差异」都是必需的,不是顺手加的:
- 响应形状。MaxKey 的
/oauth/v20/token返回裸对象,客户端按顶层键取access_token;标准端点了带信封({code,msg,data})。若别名也带信封, 照抄 MaxKey 文档的客户端会解析失败(实测表现:拿不到令牌 → 后续全挂)。 故别名走send_token_body(r, body, bare=true),标准端保持bare=false。 - 令牌位置与客户端鉴权。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 之后剥一层已知前缀再试一次:
const MAXKEY_CONTEXT_PREFIXES: [&str; 5] = ["/maxkey", "/sign/authz", "/sign", "/authz", "/api"];
只在精确路由 miss 之后调用,所以不会遮蔽真实存在的 /api/v1/*、/api/admin/*。
15.4 配套的 nginx 侧要求
归一化只在请求能到达模块时才生效。原先 IdP server 是
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 改为整站交给模块:
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,业务系统零改造
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 单独起
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 接入方」计数。
登录页重做为与管理台同色系的卡片(登录失败时错误条落在卡片内部):
| 正常 | 口令错误 |
|---|---|
![]() |
![]() |
截图取自本机运行实例(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: 前缀的共享内存。这里有一个
曾经踩过的坑(本次才暴露):
// ✗ 错: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 与未注册回调的对照断言)、四类参数校验、
公开客户端无密钥且剔除不可用授权类型。


