# 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 示例**: ```json { "iss": "http://localhost:18098", "sub": "alice", "aud": "spa-demo", "client_id": "spa-demo", "preferred_username": "爱丽丝", "email": "alice@yourdomain.com", "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` 会整表失败 → `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=&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 调资源服务器(过本服务的后端) 或调 /oauth/introspect 自省 ``` **IAP 门禁(后端被本服务反向代理时)**: ``` 客户端请求 受保护域名 → sso_iap access 阶段 IAPHandler: - 取 Authorization: Bearer 或 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 ` 与表单/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 ~^(?.+)\.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 平铺 `\n\n\n\n`(分隔符 `\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 的格式是 ` \x1f `,`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 /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` 反序列化整表失败 → 用户表读成空(静默回落 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 之后剥一层已知前缀再试一次: ```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:/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、名称、协议类型(OAuth2 / CAS)、机密/公开、密钥、**应用访问地址**、 **描述**、**图标 URL**、**可见范围**(角色 / 部门 / 用户组)、回调地址(一行一个,CAS 时即 service 白名单)、授权类型勾选、scope | | 接入方列表 | 协议徽标 + 类型徽标、可见范围提示、回调地址、授权类型、scope、脱敏密钥 + 复制、重置密钥、编辑、删除 | 顶部统计卡新增「OAuth 接入方」计数。 ![管理台 · 应用管理(OAuth 应用)](screenshots/admin-oauth-app-management.png) 终端用户门户 `GET /apps`:登录后按**可见范围**列出可访问的应用,卡片直接进入 (CAS 应用走 `/cas/login?service=…`;未配置访问地址的显示为灰底并标注): ![用户门户 · 我的应用](screenshots/portal-my-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 与未注册回调的对照断言)、四类参数校验、 公开客户端无密钥且剔除不可用授权类型。