chengcheng 2a73e18123 docs(identity): 定义统一认证运行时配置

记录 Revision 状态机、验证后热切换、Break-glass 与 Secret 边界，明确网页/API 是身份业务配置唯一来源。\n\n验证：git diff --check。

2026-07-17 11:05:48 +08:00

3.2 KiB

Raw Blame History

统一认证运行时配置与标准应用接入

状态

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 状态机

draft -> validated -> active -> superseded
draft | validated -> failed
superseded -> validated -> active
active -> superseded (回滚、替换或禁用)

同一时刻最多一个 Active Revision。Revision 保存非敏感配置与 Secret 引用，不保存机器 Secret 或 Session 加密根。关键身份字段变化时清理旧 BFF Session；回滚后用户重新登录。

激活顺序

从 Draft 和 SecretStore 构建不可变候选 Runtime。
验证 Discovery、Issuer、JWKS、Audience、Tenant、Client、本地租户、Introspection 和可选 SSF Discovery。
确认存在可用的本地 Break-glass Manager。
在数据库事务中把 Revision 原子设为 Active，并把旧版本设为 Superseded。
原子替换进程内 Runtime 引用；在途请求继续使用旧实例。
若内存替换失败，恢复数据库指针并保持旧 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_* 构建变量。安全事件作为统一认证能力状态显示，原独立页面只保留运行运维动作。

3.2 KiB Raw Blame History Unescape Escape