Files
sso/docs/design.md
T
admin 1e2b117218 refactor(paths): 拆 source/ 包层,顶层与 ipass/ipass 对齐
- 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
2026-09-21 15:44:55 +08:00

39 KiB
Raw Blame History

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. 客户端模型(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. 用户模型(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(承载协议端点,明文便于本地启动)

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 的两条硬规则

  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. 代码改动清单(已落地)

文件 改动
rust/src/oauth.rs 新增:OAuth2 AS 全部逻辑(client/code/token 模型、HS256 JWT 签名/验签、PKCE、端点 handler、IAP 身份解析)
rust/src/oauth_clients.rs 新增:客户端注册表模块(reload_shm / get / all / upsert / delete / view)
rust/src/api.rs route() 增加 /oauth/authorize、/oauth/token、/oauth/userinfo、/oauth/introspect、.well-known、/oauth/jwks、/login、/oauth/logout,转发到 oauth::*
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()
rust/src/config.rs 新增 OAuth 常量区(KEY_OAUTH_* 前缀、TTL、cookie、env 名、scopes、challenge 方法)
rust/src/models.rs User 增 email/department/groups + oauth_claims();新增 OAuthClient + OAuthClientTable(allows_scope/allows_redirect/allows_grant)
rust/src/state.rs 新增 oauth_session / oauth_code / oauth_client 共享内存封装;split_value 改用 rposition
rust/src/store.rs 新增 oauth_clients_path / read/write/update_oauth_clients
rust/src/util.rs 新增 url_encode/html_escape;HEX 常量提升为模块级
conf/nginx.conf 新增 IdP server(18098)+ IAP 代理 server(18099)
conf/nginx.test.conf 新增:本地最小验证配置(IdP 18098 + IAP 18099 + 回显后端 18097)
tests/oauth2-e2e.sh 新增:14 项端到端断言(客户端密钥运行时从种子读取,不硬编码)
scripts/run-local-e2e.sh 新增:macOS 本机 nginx + 模块一键起停并跑 e2e
data/users.json 种子用户补充 email/department/groups(数组)
data/oauth_clients.json(及 data-seed/) 新增 OAuth 客户端注册表(grafana / spa-demo / machine)
deps/ipass/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/ 例外,本仓库放行 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=./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)"
# 建 prefix 临时目录(没跑 make install 时 nginx 起不来)
mkdir -p ./build/nginx/{client_body_temp,proxy_temp,fastcgi_temp,uwsgi_temp,scgi_temp,logs,conf}

# ③ 编 Rust 模块(输出 rust/target/release/libsso_gateway.dylib)
cd rust
export LIBCLANG_PATH=/Library/Developer/CommandLineTools/usr/lib
export NGINX_SOURCE_DIR=./build/src/nginx-1.30.4
export NGINX_BUILD_DIR=./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 物化 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       # 保留进程手工排查

生产部署见 conf/nginx.conf + 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
GET /oauth2.0/authorize
authorize 无(纯别名)
GET|POST /oauth/v20/token
GET|POST /oauth2.0/accessToken
token_v20 响应不套 {code,msg,data} 信封,直接返回 {"access_token":…}
GET|POST /oauth/v20/me
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 之后剥一层已知前缀再试一次:

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 代码落点

文件 改动
rust/src/api.rs 别名路由表 + MAXKEY_CONTEXT_PREFIXES / strip_maxkey_ctx,dispatch 在 miss 后归一化重试
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、conf/nginx.test.conf IdP server 整站 location / { ipass_api on; }
data/oauth_clients.json、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、名称、协议类型(OAuth2 / CAS)、机密/公开、密钥、应用访问地址、
描述、图标 URL、可见范围(角色 / 部门 / 用户组)、回调地址(一行一个,CAS 时即 service 白名单)、授权类型勾选、scope
接入方列表 协议徽标 + 类型徽标、可见范围提示、回调地址、授权类型、scope、脱敏密钥 + 复制、重置密钥、编辑、删除

顶部统计卡新增「OAuth 接入方」计数。

管理台 · 应用管理(OAuth 应用)

终端用户门户 GET /apps:登录后按可见范围列出可访问的应用,卡片直接进入 (CAS 应用走 /cas/login?service=…;未配置访问地址的显示为灰底并标注):

用户门户 · 我的应用

登录页重做为与管理台同色系的卡片(登录失败时错误条落在卡片内部):

正常 口令错误
登录页 登录失败

截图取自本机运行实例(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, 数组会被跳过(见 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 与未注册回调的对照断言)、四类参数校验、 公开客户端无密钥且剔除不可用授权类型。