定位:身份层(IdP + IAP),不含动态域名转发 / LLM 上游代理 / 用量计费。 代码(source/rust,nginx 动态模块 + Rust,单进程零外部依赖) - IdP:authorization_code(含 PKCE)/ refresh_token / client_credentials / password 四种 grant,含 discovery / introspect / userinfo / jwks 占位 - IAP:access 阶段门禁,注入 X-Auth-* 到后端,客户端伪造同名头被覆盖 - MaxKey 互通:/oauth/v20/* 与 /oauth2.0/* 别名 + context-path 归一化 + 扁平字段 - 管理接口:账号(含角色/部门/用户组)与 OAuth 接入方注册表,热写穿共享内存 - 模块改名 ngx_http_sso_module,指令 sso_state / sso_data_dir / sso_api / sso_iap, Cookie sso_sid(终端用户)与 sso_admin_session(管理员)两套身份两套会话 配置(source/conf) - nginx.conf 生产模板(TLS、IAP 子域、含 auth_sub 的日志格式) - nginx.test.conf 本机验证配置(明文 18095-18099) - tls/README.md 证书约定与公钥比对校验 前端(source/www/admin.html) - 三 tab:账号管理 / 接入方 / 接入指南;去掉审核队列、域名、LLM 上游、用量统计 测试与脚本 - tests/ 三套端到端:协议基线 14 项 · MaxKey 互通与接入 24 项 · 管理接口 31 项,全绿 - tests/demo-system 演示业务系统(Python 标准库),覆盖应用自建客户端与 IAP 零改造两种姿势 - scripts/run-local-e2e.sh 本机一键起停;scripts/seed-data.sh 物化运行时数据目录 文档 - README.md 概览与快速开始;CLAUDE.md 硬约定与排障速查 - docs/design.md 完整设计;docs/roadmap.md 待执行任务(v2 RS256+JWKS、用户管理界面)
707 lines
38 KiB
Markdown
707 lines
38 KiB
Markdown
# 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 阶段 `sso_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/ { sso_api on; } # 协议端点
|
||
location /.well-known/ { sso_api on; } # discovery
|
||
location = /login { sso_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` / `sso_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/ { sso_api on; }
|
||
location /.well-known/ { sso_api on; }
|
||
location = /login { sso_api on; }
|
||
```
|
||
|
||
`/maxkey/oauth/v20/authorize`、`/oauth2.0/authorize` **不匹配 `/oauth/` 前缀**,
|
||
直接吃 nginx 的 HTML 404(模组里的归一化根本没机会跑)。故 IdP server 改为整站交给模块:
|
||
|
||
```nginx
|
||
location / { sso_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 / { sso_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 接入方」计数。
|
||
|
||

|
||
|
||
登录页重做为与管理台同色系的卡片(登录失败时错误条落在卡片内部):
|
||
|
||
| 正常 | 口令错误 |
|
||
| --- | --- |
|
||
|  |  |
|
||
|
||
截图取自本机运行实例(`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 与未注册回调的对照断言)、四类参数校验、
|
||
公开客户端无密钥且剔除不可用授权类型。
|