docs(identity): 记录统一认证恢复与重配边界

补充管理员从 Active 禁用到新接入码重配的标准流程，说明 credentials_saved 恢复、SSF 凭据交接、持久清理、Break-glass 与动态 Origin 边界，并明确历史 Revision 仅作审计、当前不支持直接回滚。
2026-07-17 18:32:04 +08:00
parent b179162330
commit 5b8178b703
3 changed files with 70 additions and 15 deletions
@@ -21,10 +21,11 @@ OIDC、JIT 和浏览器会话不读取业务环境变量。管理员在 Auth Cen
 - 浏览器只保存 32 字节随机、`HttpOnly + SameSite=Strict` 的 Session Cookie。新标签页通过该 Cookie 调用 `/api/v1/me` 恢复登录态；Gateway 不签发第二枚 JWT。
 - Access Token 继续保持 5 分钟。认证请求发现剩余时间不超过 60 秒时使用 Refresh Token 自动刷新；多实例通过 PostgreSQL 刷新租约保证同一版本只刷新一次，并原子保存旋转后的 Refresh Token。
 - Session 闲置 30 分钟、绝对最长 8 小时。闲置 5～30 分钟后的首个请求可自动刷新；超过闲置或绝对期限不会刷新，必须重新登录。浏览器不运行定时刷新。
- 所有 Web API 请求使用 `credentials: include`。Cookie 鉴权的 POST、PUT、PATCH、DELETE 必须携带 `CORS_ALLOWED_ORIGIN` 白名单中的 Origin，否则返回结构化 403。
+- 所有 Web API 请求使用 `credentials: include`。Cookie 鉴权请求的 Origin 必须与当前健康 Active Revision 的 Gateway Web 地址精确匹配，否则返回结构化 403；不接受 `*`。
 - Cookie 的 `Secure` 属性由 Revision 中的 Gateway API 公网地址推导：生产地址只允许 HTTPS；本地开发允许 localhost HTTP。可信 Origin 由 Gateway Web 地址精确推导，不接受 `*`。
 - `POST /api/v1/auth/oidc/logout` 校验可信 Origin、删除本地 Session、使用公共 Client ID 撤销 Refresh Token，并跳转 Auth Center 退出地址；`DELETE /api/v1/auth/oidc/session` 保留为幂等的本地删除接口。
- Session Encryption Key 由 Gateway 服务端生成，只以 Secret 引用进入 Revision，不得复用 JWT Secret，也不会进入数据库、响应、日志或浏览器。禁用统一认证会清理现有 BFF Session；回滚后用户需要重新登录。
+- 第一次接入、确认禁用或 Active Runtime 故障恢复时，跨 Origin 管理页面使用部署级精确 bootstrap CORS；生产部署建议由反向代理通过同源 `/gateway-api` 暴露 API。该配置不包含 Issuer、Client 或 Scope。
+- Session Encryption Key 由 Gateway 服务端生成，只以 Secret 引用进入 Revision，不得复用 JWT Secret，也不会进入数据库、响应、日志或浏览器。禁用统一认证会清理现有 BFF Session；重新配对后用户需要重新登录。

 ## 数据和事务语义

@@ -53,8 +54,8 @@ OIDC、JIT 和浏览器会话不读取业务环境变量。管理员在 Auth Cen

 `ErrLocalUserRequired` 仅作为防御性内部错误保留，对外统一转换为结构化 403。

-## 验收与回滚
+## 验收与重新接入

 自动化门禁通过后，依次验证本地真实 OIDC 和 `auth.51easyai.com` Staging 专用测试租户。证据应包含脱敏 Claims、网络截图、本地 Gateway 用户记录、Trace ID、Gateway/Auth Center 审计 ID及 200/401/403/503 负向证据；不得保存 Token、授权码、密码或 Secret。

-JIT 策略变更通过创建并验证新 Revision 后激活；身份配置回滚使用“系统设置 → 统一认证”的回滚操作。激活、回滚和禁用均要求本地 Break-glass Manager 可用，并清理受影响的 BFF Session。已经创建的 `source=oidc` 测试投影保留为惰性数据，不自动删除、迁移或合并。
+Active Revision 可原位重新验证。需要改变远端身份资源时，先确认本地 Break-glass Manager，禁用当前配置，再使用 Auth Center 新接入码创建、验证和激活新 Revision；历史 `superseded` Revision 只用于审计，不能直接回滚或重新激活。已经创建的 `source=oidc` 测试投影保留为惰性数据，不自动删除、迁移或合并。