chengcheng
5b8178b703
补充管理员从 Active 禁用到新接入码重配的标准流程，说明 credentials_saved 恢复、SSF 凭据交接、持久清理、Break-glass 与动态 Origin 边界，并明确历史 Revision 仅作审计、当前不支持直接回滚。
81 lines
7.0 KiB
Markdown
81 lines
7.0 KiB
Markdown
# SSF/CAEP 实时会话撤销运行手册
|
||
|
||
Gateway 可选接收 Auth Center 通过 RFC 8935 Push 投递的 RFC 8417 Security Event Token，并处理 OpenID CAEP `session-revoked`。能力由 Active Identity Revision 控制；没有选择会话撤销时保持原有 OIDC、BFF、API Key 和 Legacy JWT 行为。
|
||
|
||
## 用户接入流程
|
||
|
||
首次接入只执行两端各一次操作：
|
||
|
||
1. 在认证中心 Application 的通用“应用接入”向导选择“SSF 会话撤销”。能力依赖会自动包含 Token Introspection 和机器调用；预览确认后创建或复用同用途服务客户端。
|
||
2. 在 Gateway“系统设置 → 统一认证”填写一次性接入码和 Gateway 地址。Gateway 自动领取 Manifest 与机器凭据，并在验证候选 Runtime 时建立 SSF Stream。
|
||
|
||
Gateway 后端先把 Machine Secret 写入 SecretStore，随后自动读取 Discovery、生成并托管 256 bit Push Bearer、创建 paused Stream、完成 Verification、首次启用 Stream，并进入 360 秒 RFC 7662 bootstrap。接入码和 Machine Secret 只从浏览器提交到 Gateway 服务端；Push Bearer 和 Secret 引用始终不可见，数据库、响应和日志不保存明文。管理员不编辑 Secret 文件，也不需要重启 Gateway。
|
||
|
||
环境前置配置只保留 SecretStore 与运行时基础设施参数：
|
||
|
||
- `IDENTITY_SECRET_STORE`、`IDENTITY_SECRET_DIR`，或对应 Kubernetes SecretStore 参数；
|
||
- `IDENTITY_SECURITY_EVENTS_HEARTBEAT_INTERVAL_SECONDS`、`IDENTITY_SECURITY_EVENTS_STALE_AFTER_SECONDS` 和 `IDENTITY_SECURITY_EVENTS_CLOCK_SKEW_SECONDS`。
|
||
|
||
Issuer、Tenant、Gateway 公网地址和机器 Client 均来自 Active Revision，不读取旧 OIDC 环境变量。OIDC fallback、SSF 管理 Token 和 Verification 共用一份托管机器凭据，重启后继续生效。
|
||
|
||
第一版一个 Gateway 部署只允许一个认证中心连接。下游业务服务无需接入 SSF。
|
||
|
||
## SecretStore
|
||
|
||
本地和 Docker 使用 `file` 驱动。服务自动创建目录并强制目录 `0700`、文件 `0600`；Docker Compose 将目录放在持久化 `api_data` 卷中。用户不写入任何 Secret 文件。
|
||
|
||
Kubernetes 使用 `kubernetes` 驱动和一个部署时预创建的空 Secret：
|
||
|
||
```text
|
||
IDENTITY_SECRET_STORE=kubernetes
|
||
IDENTITY_KUBERNETES_NAMESPACE=easyai
|
||
IDENTITY_KUBERNETES_SECRET_NAME=easyai-gateway-identity
|
||
```
|
||
|
||
参考清单见 `deploy/kubernetes/security-events-secret-rbac.yaml`。ServiceAccount 只能对这个固定 Secret 执行 `get/update/patch`，不能创建、删除或读取其他 Secret。数据库、API、浏览器、日志和审计只保存或展示非敏感连接元数据。
|
||
|
||
## 动态运行与状态
|
||
|
||
Receiver 路由始终注册：没有连接时返回无敏感信息的 `404`；存在连接但凭据丢失时返回 `503` 并进入 `introspection_fallback`。OIDC Evaluator 始终挂载但在无连接时无副作用。
|
||
|
||
连接生命周期包括 `connecting`、`verifying`、`bootstrap`、`enabled`、`degraded`、`rotating`、`disconnect_pending` 和 `retiring`。健康时每 60 秒一次 Verification，不随业务请求 QPS 增长；180 秒无匹配 Verification 时切换 RFC 7662。内省也不可用时 OIDC Fail Closed，API Key 继续工作。
|
||
|
||
Verification 成功后仅在首次连接和主动轮换时自动启用 Stream。认证中心管理员之后手工暂停或禁用 Stream，Gateway 的“重新验证”只检查链路，不会擅自恢复远端状态。
|
||
|
||
## 轮换与断开
|
||
|
||
“轮换凭据”由 Gateway 自动完成：生成 next、Receiver 同时接受 current/next、暂停并更新远端 Stream、Verification、重新启用、保留旧值至少 180 秒，最后提升 next 并删除旧值。中途失败保留两个凭据和 `rotating` 状态，可安全重试。
|
||
|
||
“断开连接”先删除远端 Stream，再进入至少 360 秒 `retiring`，期间继续应用撤销水位和 RFC 7662，避免旧 Token 因关闭功能重新有效。远端不可用时保持 `disconnect_pending` 并指数退避重试；不会提前删除 Push Secret。收据、水位和脱敏审计数据不会清表。
|
||
|
||
禁用统一认证也遵循相同顺序：若 Active Revision 开启了 SSF，只有远端 Stream 已删除且本地连接进入 `retiring` 后，Active 才会变为 `superseded`，BFF Session 才会清理。`disconnect_pending` 时禁用返回明确的 retirement pending，数据库 Active 保持不变；即使完整 OIDC Runtime 已 fail closed，Gateway 也会只重建 SSF 管理面完成断开，不要求 Discovery、JIT 或 BFF 先恢复。`retiring` 最终清理由服务生命周期 Worker 托管，Gateway 重启后仍会继续。
|
||
|
||
## 旧连接交接与配对恢复
|
||
|
||
Pairing 停在 `credentials_saved` 时，Manifest 和机器凭据已经保存，但 Stream 可能仍在创建、验证或退役：
|
||
|
||
- 暂时性 Discovery/Transmitter 错误和 `security_event_retirement_pending` 会自动重试。
|
||
- `security_event_connection_conflict` 只允许通过当前 Pairing 的“安全退役现有连接”处理。
|
||
- `security_event_credential_handoff_unsafe` 表示旧连接与新 Issuer/Client 不匹配；系统不会把旧凭据发往新端点。管理员应在原配置下断开，或放弃当前 Pairing。
|
||
- 放弃后等待 `cleanup_status=completed`，再从 Auth Center 生成新接入码重新配对。
|
||
|
||
若旧连接与新配置具备可证明的同一管理边界，Gateway 仍不会直接覆盖 S1：先用新机器凭据 S2 从新 OIDC Issuer 取得管理 Token，再经过认证读取旧 Transmitter；存在 Stream 时精确校验 Stream ID、Issuer、Receiver 和 Audience。证明成功后才原子切换凭据引用并把 S1 交给持久清理队列；失败时 S1/S2 引用和远端连接都保持不变。
|
||
|
||
所有写管理接口要求 Gateway `Manager` 权限、`Idempotency-Key` 和 `If-Match`：
|
||
|
||
```text
|
||
GET /api/admin/system/identity/security-events/connection
|
||
PUT /api/admin/system/identity/security-events/connection
|
||
POST /api/admin/system/identity/security-events/connection/verify
|
||
POST /api/admin/system/identity/security-events/connection/rotate-credential
|
||
DELETE /api/admin/system/identity/security-events/connection
|
||
```
|
||
|
||
## 监控、退役与验收
|
||
|
||
`GET /metrics` 输出接收结果、删除 Session 数、水位拒绝数、Verification 年龄、健康模式、内省结果、JWKS 失败和处理延迟。至少告警 Verification age 超过 120 秒、fallback 超过 5 分钟、内省失败、SET 拒绝增长以及撤销 P99 超过 3 秒。日志只记录脱敏 Trace/Audit ID 和错误类别。
|
||
|
||
当前禁止直接激活历史 `superseded` Revision，因为 Auth Center 会复用并修改远端 OAuth/SSF 资源，旧快照无法证明仍然匹配。恢复配置时先通过 Gateway 安全禁用并退役 Stream，再使用 Auth Center 新接入码重新配对；保留迁移表、水位和审计。Legacy HS256 Token 和 API Key 不在本协议撤销范围内。
|
||
|
||
真实链路只使用明确标记为测试用途的 Application，并且必须在自动化测试后执行。报告包含脱敏 Trace、Claims、截图、Audit ID、投递延迟、fallback 和恢复证据；需要人工或第三方操作时记录 `SKIPPED_HUMAN_OR_THIRD_PARTY_REQUIRED`。
|