diff --git a/docs/standard-identity-runtime-configuration.md b/docs/standard-identity-runtime-configuration.md new file mode 100644 index 0000000..45865d2 --- /dev/null +++ b/docs/standard-identity-runtime-configuration.md @@ -0,0 +1,52 @@ +# 统一认证运行时配置与标准应用接入 + +## 状态 + +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_*` 构建变量。安全事件作为统一认证能力状态显示,原独立页面只保留运行运维动作。