身份与访问控制
认证模式、API key、密钥优先级、streaming、mTLS、Kerberos、OIDC SSO、SCIM 和角色。
AI-FW 认证两类调用方：通过 Web UI 的管理员和通过 Gateway API 的 Agent。本指南说明两类身份及管理员角色。
Gateway 认证模式#
Settings -> Access Control -> Authentication Mode 控制 API 调用方要求：
| 模式 | 行为 |
|---|---|
| required | 无 Bearer token 返回 401；所有调用方必须认证。 |
| optional | 允许匿名；如果提供 token，必须有效。 |
| passthrough | 只检查 Bearer key 非空，并原样转发 upstream。 |
支持 Authorization: Bearer；Anthropic 客户端也可用 x-api-key。
Upstream key 优先级#
发给模型 backend 的 key 按规则 -> 模型 -> 全局解析，最具体者优先。
- 规则级：匹配的路由/guardrail 规则 key mode。
- 模型级：Model Inventory 中该模型的 key mode。
- 全局：Settings -> Access Control -> Key Mode，默认 model。
| 生效模式 | Upstream Authorization |
|---|---|
| model | 优先使用模型注册 key；模型无 key 才用客户端 token。 |
| client | 原样转发客户端 Bearer；没有 client key 时不设置 auth 标头。 |
启用 client key mode 前请评估
client 模式不再保证只有批准的 key 到达 backend。应有意识启用，例如与 passthrough 配合支持 BYOK。
Streaming 模式#
stream: true 同样按规则 -> 模型 -> 全局决定：
| 模式 | 行为 |
|---|---|
| buffered（默认） | 完整响应检查后才交付 token；违规在交付前返回 HTTP 400。 |
| stream | token 经滑动窗口扫描后实时转发；中途违规会终止连接和 SSE，并返回 guardrail_violation。 |
没有 stream: true 时始终采用 buffered。
Agent 认证#
Agent 可用四种方式证明身份：
- API key：管理员签发，唯一 key ID 用于身份、缓存隔离和风险。
- JWT：用配置的签名 secret 验证 Bearer JWT；sub claim 是 Agent 身份。
- mTLS (RFC 8705)：单独 TLS listener 上的客户端证书；SPIFFE URI、subject key identifier 或 common name 映射到 Agent 身份。
- Kerberos：域加入的 Windows 服务账户通过 Authorization: Negotiate 认证，并可申请 mTLS 客户端证书。可配置 UPN 和来源子网 allow-list。
管理员角色和 Web UI#
| 角色 | 权限 |
|---|---|
| Admin | 完全访问。 |
| Read-Only | 查看整个 UI，禁止修改。 |
| AI-FW Admin | 仅管理 AI firewall、规则、模型、设置和审计。 |
| Agent-Trust Admin | 仅管理 Agent 清单与信任，不能访问 AI Firewall 区域。 |
Users 页面管理本地用户、角色和密码重置。
SSO 与配置#
OIDC SSO 设置 authority、client ID、secret、scopes；登录模式 local、oidc 或 both。角色映射把身份提供方 claims 转为 AI-FW 角色；未知/缺失 claims 默认 Read-Only。
SCIM 2.0 通过 bearer secret 从身份提供方配置用户和组。userName 映射本地用户名，active 映射启用状态，名称匹配角色的组会分配角色。SCIM 用户无本地密码，使用 SSO 登录。