SSF/CAEP 实时会话撤销运行手册

Gateway 可选接收 Auth Center 通过 RFC 8935 Push 投递的 RFC 8417 Security Event Token，并处理 OpenID CAEP session-revoked。默认关闭；关闭时不会注册接收路由或启动状态机，也不会改变 OIDC、BFF、API Key 或 Legacy JWT 行为。

启用前提

Auth Center 已创建属于当前 Application/租户的 paused Stream，Audience 为 urn:easyai:ssf:receiver:{application-public-id}。
Gateway OIDC iss、tid 与 Stream 绑定完全一致；Stream ID 为公开 UUID，不使用认证内核 ID。
接收 Bearer、Management Client Secret、RFC 7662 Client Secret 仅从 Git 忽略的 .env、Kubernetes Secret 或 Secret Manager 注入。
OIDC_SECURITY_EVENTS_PUBLIC_ENDPOINT 必须是外部可访问的精确 HTTPS 地址；本地测试环境才允许 localhost HTTP。
Management Client 至少有 ssf.stream.read ssf.stream.verify，不能使用浏览器 PKCE Client。

完整配置键见仓库根目录 .env.example。启用时 OIDC_SECURITY_EVENTS_ENABLED=true，且 RFC 7662 Client ID/Secret 必须同时存在，否则启动失败。

启用顺序

运行数据库迁移，部署仍保持功能关闭。
在 Secret Store 创建接收 Bearer、Management Client Secret 和内省 Client Secret；不要把值放进日志或工单。
启用 Gateway。启动模式为 bootstrap，所有 OIDC Token 都先内省。
在 Auth Center 对 paused Stream 发起 Verification，确认 Gateway 返回空 Body 的 202。
启用 Stream。首次 Verification 成功后仍内省 360 秒，覆盖启用前已签发的最长 300 秒 Token。
观察 easyai_gateway_ssf_mode{mode="push_healthy"} 变为 1，再执行测试用户撤销。

健康时 Gateway 每 60 秒请求一次 Verification，不按业务 QPS 请求 Auth Center。180 秒没有匹配的有效 Verification 会进入 introspection_fallback；只有最近收到的 Stream 状态为 enabled 时，连续两次 Verification 成功才会恢复，paused/disabled 状态下心跳不会错误恢复推送信任。降级期间内省不可用会对 OIDC 返回可审计的 503，API Key 继续工作。

零停机 Bearer 轮换

在 Gateway 写入 OIDC_SECURITY_EVENTS_BEARER_SECRET_NEXT，同时接受 current/next。
更新 Auth Center 的 Stream credential_ref 指向 next。
发起 Verification，并确认投递和状态机健康。
等待至少 180 秒后，将 next 提升为 current 并清空旧值。

Gateway 使用常量时间比较两个值。响应、日志、审计和指标都不得包含 Authorization Header 或原始 SET。

监控与告警

GET /metrics 输出以下低基数指标；生产入口应仅允许监控网络访问该路径：

easyai_gateway_ssf_receipts_total{outcome}：accepted/rejected/duplicate。
easyai_gateway_ssf_sessions_deleted_total：被撤销删除的 BFF Session。
easyai_gateway_ssf_watermark_rejections_total：本地水位拒绝的 Token。
easyai_gateway_ssf_processing_duration_seconds：Receiver 数据库事务处理直方图，用于 P99 告警。
easyai_gateway_ssf_verification_age_seconds 和 easyai_gateway_ssf_mode{mode}。
easyai_gateway_ssf_heartbeat_requests_total{outcome}。
easyai_gateway_oidc_introspection_total{outcome}。
easyai_gateway_jwks_refresh_failures_total{source}：SSF/OIDC JWKS 刷新失败。

至少配置以下告警：Verification age 超过 120 秒、fallback 超过 5 分钟、内省 failed 增长、SET rejected 增长、撤销端到端 P99 超过 3 秒。日志只能携带脱敏 Trace ID、Audit ID 和错误类别。

回滚

先在 Auth Center 暂停 Stream，再保持 Gateway 启用但持续使用 RFC 7662，确认没有遗漏撤销后才关闭接收功能。保留迁移表和 Secret，不做破坏性数据库回滚。Legacy HS256 Token 和 API Key 不在本协议撤销范围内。

验收证据

真实链路验收只能使用明确标记为测试用途的 Application，且必须在自动化测试通过后执行。报告需包含脱敏 Trace、Claims 结构、截图、Audit ID、投递延迟、fallback 与恢复证据。涉及人工、真实设备或第三方操作时记录 SKIPPED_HUMAN_OR_THIRD_PARTY_REQUIRED，Mock、契约和安全测试不得跳过。

4.2 KiB Raw Blame History Unescape Escape