Identidad y acceso
Modos de autenticación, API keys, precedencia de claves, streaming, mTLS, Kerberos, OIDC SSO, SCIM y roles.
AI-FW autentica dos tipos de llamadores: personas administradoras mediante UI y agentes de máquina mediante API. Esta guía cubre ambos y los roles que limitan la superficie administrativa.
Modos de autenticación del gateway#
Settings -> Access Control -> Authentication Mode define lo que se exige a clientes API:
| Modo | Comportamiento |
|---|---|
| required | Sin Bearer token devuelve 401. Todos deben autenticarse. |
| optional | Permite anónimos, pero valida cualquier token enviado. |
| passthrough | Acepta cualquier Bearer no vacío por presencia y lo reenvía intacto upstream. |
Se aceptan Authorization: Bearer y, para clientes Anthropic, x-api-key.
Precedencia de clave upstream#
La clave enviada al backend se resuelve por especificidad: regla -> modelo -> global.
- Regla: key mode de regla coincidente.
- Modelo: key mode en Model Inventory.
- Global: Settings -> Access Control -> Key Mode, predeterminado model.
| Modo efectivo | Authorization upstream |
|---|---|
| model | Gana la clave registrada del modelo; el token cliente solo se usa si el modelo no tiene clave. |
| client | Reenvía Bearer del cliente; sin clave no se envía encabezado de autenticación. |
Con client, el gateway ya no garantiza que solo claves aprobadas lleguen al backend. Úselo de forma deliberada, por ejemplo con passthrough para BYOK.
Modos de streaming#
Para stream: true, el modo efectivo también sigue regla -> modelo -> global:
| Modo | Comportamiento |
|---|---|
| buffered (predeterminado) | Almacena y analiza la respuesta completa antes de entregar tokens; una infracción devuelve HTTP 400. |
| stream | Reenvía tokens en vivo mediante scanner de ventana móvil; una infracción interrumpe la conexión y finaliza SSE con guardrail_violation. |
Sin stream: true, las respuestas siempre se almacenan y analizan primero.
Autenticación de agentes#
Agentes pueden demostrar identidad con:
- API keys administradas, con ID único para identidad, aislamiento de caché y riesgo.
- JWT, validado con el secreto configurado; claim sub define la identidad.
- mTLS (RFC 8705), con certificado cliente en listener TLS independiente; SPIFFE URI, subject key identifier o common name se asignan a identidad de agente.
- Kerberos, para cuentas de servicio Windows unidas al dominio mediante Authorization: Negotiate; permite inscribirse para certificado cliente mTLS. UPN y subred de origen pueden limitarse.
Roles de administración y UI#
| Rol | Acceso |
|---|---|
| Admin | Acceso completo. |
| Read-Only | Ve toda la UI, sin cambios. |
| AI-FW Admin | Administra solo firewall AI-FW, reglas, modelos, settings y auditoría. |
| Agent-Trust Admin | Administra inventario y confianza de agentes, sin acceso a sección AI Firewall. |
Users administra cuentas locales, roles y restablecimiento de contraseñas.
SSO y aprovisionamiento#
OIDC SSO configura authority, client ID, secreto y scopes. Modo de inicio: local, oidc o both. Un mapa de roles traduce claims; claims desconocidas o ausentes se asignan a Read-Only.
SCIM 2.0 aprovisiona usuarios y grupos desde el proveedor con Bearer secret. userName se mapea al usuario local, active al estado habilitado y grupos cuyo nombre coincide con un rol asignan ese rol. Usuarios SCIM no tienen contraseña local y usan SSO.