From 245e2efc5e1079b67bed6b73b096b96f05035c06 Mon Sep 17 00:00:00 2001 From: ssw Date: Sun, 13 Sep 2026 18:52:50 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=8C=87=E4=BB=A4=E5=90=8D=E5=AF=B9?= =?UTF-8?q?=E9=BD=90=20ipass=5F*=20=E5=89=8D=E7=BC=80=EF=BC=88sso=5Fiap=20?= =?UTF-8?q?=E4=BF=9D=E7=95=99=E4=B8=BA=E6=8F=92=E4=BB=B6=E7=89=B9=E6=9C=89?= =?UTF-8?q?=E5=BC=80=E5=85=B3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 4 ++-- docs/design.md | 20 ++++++++++---------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1dcc358..fbb0bce 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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` 等于配置没生效, diff --git a/docs/design.md b/docs/design.md index 193e769..2fa6071 100644 --- a/docs/design.md +++ b/docs/design.md @@ -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) | ---