Identité et accès
Modes d’authentification, API keys, priorité des clés, streaming, mTLS, Kerberos, OIDC SSO, SCIM et rôles.
AI-FW authentifie deux types d’appelants : les administrateurs via l’UI et les agents machine via API. Ce guide couvre les deux et les rôles qui limitent l’administration.
Modes d’authentification du gateway#
Settings -> Access Control -> Authentication Mode :
| Mode | Comportement |
|---|---|
| required | Sans Bearer token, HTTP 401. Tous les appelants doivent s’authentifier. |
| optional | Anonymes autorisés ; tout token fourni doit être valide. |
| passthrough | Toute clé Bearer non vide est acceptée et transmise telle quelle upstream. |
Acceptés : Authorization: Bearer et, pour clients Anthropic, x-api-key.
Priorité des clés upstream#
Résolution : règle -> modèle -> global, du plus spécifique au moins spécifique.
- Règle : key mode d’une règle de routage/guardrail correspondante.
- Modèle : key mode dans Model Inventory.
- Global : Settings -> Access Control -> Key Mode, défaut model.
| Mode effectif | En-tête Authorization upstream |
|---|---|
| model | Clé enregistrée du modèle prioritaire ; token client utilisé si aucune clé modèle. |
| client | Bearer du client transmis tel quel ; sans clé, aucun en-tête auth. |
En mode client, le gateway ne garantit plus que seules les clés approuvées atteignent le backend. Activez-le délibérément, par exemple avec passthrough pour BYOK.
Modes streaming#
stream: true suit la priorité règle -> modèle -> global.
| Mode | Comportement |
|---|---|
| buffered (défaut) | Réponse complète stockée et inspectée avant livraison ; violation = HTTP 400. |
| stream | Tokens relayés en direct par scanner à fenêtre glissante ; violation interrompt connexion et termine SSE avec guardrail_violation. |
Sans stream: true, la réponse est toujours buffered.
Authentification des agents#
- API keys : clés administrées avec ID unique pour identité, isolation cache et risque.
- JWT : Bearer JWT validé avec secret configuré ; claim sub identifie l’agent.
- mTLS (RFC 8705) : certificat client sur listener TLS distinct ; SPIFFE URI, subject key identifier ou common name mappé à l’identité.
- Kerberos : comptes Windows joints au domaine via Authorization: Negotiate ; inscription certificat client mTLS possible. UPN et allowlist sous-réseau configurables.
Rôles admin et interface web#
| Rôle | Accès |
|---|---|
| Admin | Accès complet. |
| Read-Only | Consultation totale, mutations bloquées. |
| AI-FW Admin | Surface firewall AI-FW, règles, modèles, settings et audit. |
| Agent-Trust Admin | Inventaire/confiance des agents, sans section AI Firewall. |
Users gère comptes locaux, rôles et réinitialisations de mots de passe.
SSO et provisionnement#
OIDC SSO configure authority, client ID, secret et scopes ; mode local, oidc ou both. Le role map traduit les claims ; claims absentes/inconnues deviennent Read-Only.
SCIM 2.0 provisionne utilisateurs/groupes via bearer secret. userName devient utilisateur local, active l’état actif ; groupes dont le nom correspond à un rôle l’attribuent à leurs membres. Les utilisateurs SCIM sont sans mot de passe et utilisent SSO.