chengcheng
2a73e18123
记录 Revision 状态机、验证后热切换、Break-glass 与 Secret 边界，明确网页/API 是身份业务配置唯一来源。\n\n验证：git diff --check。
53 lines
3.2 KiB
Markdown
53 lines
3.2 KiB
Markdown
# 统一认证运行时配置与标准应用接入
|
||
|
||
## 状态
|
||
|
||
Accepted，2026-07-17。
|
||
|
||
## 决策
|
||
|
||
Gateway 是标准应用接入协议的首个消费方。认证中心保持消费方无关；“统一认证”页面、Gateway 本地租户映射、Legacy JWT 兼容和 Session 策略均属于 Gateway 自己的管理边界。
|
||
|
||
OIDC、JIT、Introspection、BFF 和 SSF 的业务配置以 Gateway 管理 API/数据库为唯一来源。数据库、SecretStore、Session 加密根、Bootstrap 管理凭据、TLS 与 RBAC 仍由部署环境提供。开发阶段不读取或迁移旧 `OIDC_*`、`VITE_OIDC_*` 业务变量，升级后由管理员重新配对。
|
||
|
||
## Revision 状态机
|
||
|
||
```text
|
||
draft -> validated -> active -> superseded
|
||
draft | validated -> failed
|
||
superseded -> validated -> active
|
||
active -> superseded (回滚、替换或禁用)
|
||
```
|
||
|
||
同一时刻最多一个 Active Revision。Revision 保存非敏感配置与 Secret 引用，不保存机器 Secret 或 Session 加密根。关键身份字段变化时清理旧 BFF Session；回滚后用户重新登录。
|
||
|
||
## 激活顺序
|
||
|
||
1. 从 Draft 和 SecretStore 构建不可变候选 Runtime。
|
||
2. 验证 Discovery、Issuer、JWKS、Audience、Tenant、Client、本地租户、Introspection 和可选 SSF Discovery。
|
||
3. 确认存在可用的本地 Break-glass Manager。
|
||
4. 在数据库事务中把 Revision 原子设为 Active，并把旧版本设为 Superseded。
|
||
5. 原子替换进程内 Runtime 引用；在途请求继续使用旧实例。
|
||
6. 若内存替换失败，恢复数据库指针并保持旧 Runtime；不得部分启用。
|
||
|
||
验证失败不会修改当前 Active Runtime；首次配置失败时统一认证保持关闭，本地管理登录继续可用。
|
||
|
||
## 配对与 Secret 边界
|
||
|
||
管理员只填写认证中心地址、一次性接入码、Gateway API/Web 公网地址、本地租户映射和 Legacy JWT 开关。Gateway 后端领取接入码、提交精确 URI、轮询资源状态、获取 Manifest 与一次性机器凭据，并先写入 SecretStore 再确认 Exchange 完成。
|
||
|
||
接入码、Exchange Token、机器 Secret 不进入 URL、数据库、日志、审计、指标或浏览器持久存储。SecretStore 写入失败时请求认证中心轮换，旧 Secret 立即失效。
|
||
|
||
## 威胁模型摘要
|
||
|
||
- 伪造/越权：所有管理写操作要求 Manager、`Idempotency-Key`、`If-Match` 和审计；Exchange Token 仅授权一个 Exchange。
|
||
- 篡改：Manifest 使用严格 schema_version 和字段白名单；Issuer 与 Discovery issuer 必须精确相等。
|
||
- 信息泄露：公开运行时接口只返回启用状态、登录/退出入口和脱敏健康状态。
|
||
- SSRF：认证中心地址必须通过协议与地址策略校验，禁止 userinfo、重定向和非开发 HTTP；Discovery/Token/Introspection 请求使用超时与响应大小上限。
|
||
- 锁死：激活、禁用与回滚前确认本地 Break-glass Manager 可用。
|
||
- 降级：OIDC 校验 fail closed；Introspection/SSF 不可用时遵循已有降级窗口，不绕过身份校验。
|
||
|
||
## 前端运行时配置
|
||
|
||
Web 前端启动后读取公开只读统一认证状态，不使用 `VITE_OIDC_*` 构建变量。安全事件作为统一认证能力状态显示，原独立页面只保留运行运维动作。
|