docs: 指令名对齐 ipass_* 前缀(sso_iap 保留为插件特有开关)

This commit is contained in:
ssw committed 2026-09-13 18:52:50 +08:00
1 parent 4713071cd0
commit 245e2efc5e
2 files changed
+12 -12

No files matched your search

+2 -2
View File
@@ -110,7 +110,7 @@ bash scripts/run-local-e2e.sh --keep # 保留进程手工排查
| `refs/` | **不入版本库**:`refs/ipass`(来源项目)、`refs/MaxKey`(协议对齐参考) |
容器内路径约定:模块装 `/usr/local/nginx/modules/`,data 默认 `/usr/local/nginx/data`
(`sso_data_dir` 可覆盖)。**别在宿主机上按容器路径找文件。**
(`ipass_data_dir` 可覆盖)。**别在宿主机上按容器路径找文件。**
---
@@ -119,7 +119,7 @@ bash scripts/run-local-e2e.sh --keep # 保留进程手工排查
1. **请求分流靠「location 开关 + 阶段」**。阶段处理器注册在 http 主配置上(全局生效),
**必须靠 location 指令收敛**,否则管理台与静态页也会走认证逻辑:
- **IAP**(access,`sso_iap on`):取 Bearer 或 `sso_sid` cookie → 校验 → 写 `$auth_*` → 放行/401。
- **API/协议**(content,`sso_api on`):**先异步读请求体**再分发(access 阶段拿不到 body)。
- **API/协议**(content,`ipass_api on`):**先异步读请求体**再分发(access 阶段拿不到 body)。
2. **共享内存是运行期真源,JSON 文件只是持久化副本**。所有写操作**同时**写 shm 与文件
(write-through)。**写穿不是优化,是正确性要求**:漏掉 `sync_shm` 等于配置没生效,
+10 -10
View File
@@ -45,7 +45,7 @@
| GET/POST | `/login` | SSO 登录页 + 表单提交(建立 `sso_sid` 会话 cookie) | Public |
| POST | `/oauth/logout` | 注销 SSO 会话(清 cookie + 清共享内存) | Public |
> 所有协议端点走 content 阶段 `sso_api`(与管理/API server 同 location 收敛);
> 所有协议端点走 content 阶段 `ipass_api`(与管理/API server 同 location 收敛);
> IAP 门禁走 access 阶段 `sso_iap`,与协议端点**互不干扰**。
---
@@ -210,9 +210,9 @@
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 登录页
location /oauth/ { ipass_api on; } # 协议端点
location /.well-known/ { ipass_api on; } # discovery
location = /login { ipass_api on; } # SSO 登录页
}
```
@@ -369,7 +369,7 @@ 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` /
生成 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 就绪、跑三套断言、汇总退出码。
@@ -499,16 +499,16 @@ const MAXKEY_CONTEXT_PREFIXES: [&str; 5] = ["/maxkey", "/sign/authz", "/sign", "
归一化只在请求能到达模块时才生效。原先 IdP server 是
```nginx
location /oauth/ { sso_api on; }
location /.well-known/ { sso_api on; }
location = /login { sso_api on; }
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 / { sso_api on; }
location / { ipass_api on; }
```
> 教训:**协议端点的 location 不要逐条枚举**——每加一个别名都要改 nginx 配置 + reload,
@@ -539,7 +539,7 @@ location / { sso_api on; }
| --- | --- |
| `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; }` |
| `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) |
---