Modello di autorizzazione per Agent IA: identità utente, permessi degli strumenti, audit log e isolamento dei secret

Un team passa lo stesso token amministratore a un Agent, pensando: “tanto è tutto interno”. Poi l’utente A invia una query e l’Agent, usando l’identità amministratore, legge il record CRM dell’utente B. Permessi fuori controllo sono più pericolosi dell’assenza di un Agent.

Non è uno scenario inventato. MCP Security Best Practices indica token passthrough come anti-pattern: aggira i controlli di sicurezza, rompe l’audit trail e supera i trust boundary. Anche OWASP AI Agent Security Cheat Sheet considera abuso degli strumenti ed escalation dei privilegi tra i rischi principali.

Il problema si riduce a tre domande: chi rappresenta l’Agent, con quale base può chiamare, e a cosa può accedere. Qui trovi il modello completo: tabella di mapping dell’identità, elenco dei campi di permesso per gli strumenti, passaggi chiave del Secret Vault, schema di audit log con regole di mascheramento, tabella decisionale, checklist di troubleshooting e passi di implementazione.

Mapping dell’identità: chi rappresenta l’Agent?

Quando un Agent chiama uno strumento, log e sistema di autorizzazione devono rispondere prima a una domanda: chi ha avviato la chiamata e per conto di chi viene eseguita l’operazione? Le due entità possono coincidere oppure no. Confonderle porta a permessi fuori controllo e audit difficili da ricostruire.

Tabella dei tipi di identità

Tipo	actor	subject	Scenario	Confine dei permessi
user identity	Utente A	Utente A	Interazione diretta dell’utente	Eredita i permessi dell’utente
service account	system_bot	null	Job in background, attività pianificate	Permessi di sistema, indipendenti dall’utente
delegated token	workflow_123	Utente A	Workflow automatizzato autorizzato dall’utente	Scope del workflow, limitato dall’autorizzazione dell’utente
tenant context	agent_456	tenant_B	Sistema multi-tenant	Isolamento del tenant, niente accesso cross-tenant

Definizione dei campi: actor è l’entità che avvia la chiamata, cioè utente, Agent, workflow o sistema. Il log registra l’ID dell’actor. subject è l’entità rappresentata, un utente o null. Nell’interazione diretta actor=subject. Quando un account di sistema esegue un job in background, subject=null. delegatedBy indica quale utente ha autorizzato il workflow. tenantId identifica il tenant e serve a isolare i dati nei sistemi multi-tenant.

Secondo la specifica MCP Authorization, i MCP servers devono verificare che l’access token sia stato emesso per loro come intended audience. Il campo audience del token deve puntare all’identificatore di risorsa di quel MCP server. Il token non dovrebbe stare nell’URI query string, perché gli URI possono finire nei log, nella cronologia del browser e nelle cache dei proxy.

OWASP Access Control Cheat Sheet sottolinea deny by default, least privilege e controlli a ogni richiesta. Il mapping dell’identità è il primo passo: actor, subject e tenantId determinano la decisione di autorizzazione successiva.

Permessi degli strumenti: cosa può chiamare l’Agent?

Registrare uno strumento non significa solo definire name, description e input_schema. La reference degli strumenti nell’OpenAI Agents SDK include campi per autorizzazione e controllo dell’esecuzione.

Tabella decisionale dei permessi degli strumenti

Controllo dei permessi	Scenario	Implementazione	Rischio
per-tool permission	Ogni strumento ha autorizzazione separata	Impostare permission_level alla registrazione, per esempio read/write/admin	Configurazione più complessa, matrice dei permessi da mantenere
scope minimization	Privilegio minimo progressivo	Scope iniziale con sole operazioni a basso rischio, privilegi elevati tramite scope challenge	Gestione degli scope più costosa e spesso dinamica
whitelist	Lista consentita di strumenti	Consentire solo combinazioni specifiche, come read_customer + summarize	Costo di manutenzione e minore flessibilità
approval	Approvazione umana	Gli strumenti needs_approval=true si fermano prima dell’esecuzione e attendono approvazione	L’approvazione aggiunge latenza e incide sull’esperienza utente

I campi degli strumenti nell’OpenAI Agents SDK includono is_enabled per il controllo a runtime. Uno strumento può essere disattivato dinamicamente in base a ruolo utente, tenant o workflow context. needs_approval indica se serve approvazione umana. Dopo l’approvazione, tool_input_guardrails viene comunque eseguito. tool_input_guardrails valida gli input, come rilevamento PII o limiti dei parametri. tool_output_guardrails valida gli output, per esempio con filtri di contenuto.

MCP Security Best Practices consiglia il privilegio minimo progressivo per scope minimization: lo scope iniziale dovrebbe includere solo operazioni di discovery o lettura a basso rischio, come read:metadata e list:resources. Le operazioni ad alto privilegio vanno aggiunte tramite scope challenge precisi. Evita wildcard/full-access scopes.

OWASP AI Agent Security Cheat Sheet raccomanda per-tool permission scoping: usare tool sets diversi per trust level diversi, richiedere autorizzazione esplicita per operazioni sensibili e applicare fail closed quando il controllo dei permessi fallisce.

Isolamento dei secret: come l’Agent usa le chiavi?

Un Agent non dovrebbe possedere direttamente API key lunghe in chiaro. OWASP Secrets Management Cheat Sheet raccomanda gestione centralizzata e standardizzata dei secret. Anche il sistema di gestione dei secret deve supportare Authentication, Authorization, Accounting e lifecycle.

Tabella dei pattern di accesso ai secret

Pattern	Rischio	Scenario	Esempio
Possesso diretto, come .env in chiaro	Alto rischio di fuga, nessuna tracciabilità, nessuna revoca	Non consigliato	API key hardcoded
Variabili d’ambiente	Rischio di fuga nei log, tracciabilità e revoca ancora deboli	Deploy su singola macchina	process.env.API_KEY
secret vault	Gestione centralizzata, storage cifrato, audit trail, revoca	Produzione	AWS Secrets Manager, HashiCorp Vault
secret reference	L’Agent conserva una reference e ottiene un token breve al momento dell’esecuzione	Multi-tenant, scenari ad alta sicurezza	vault.get(secretRef)

Il lifecycle di un secret ha quattro fasi: creation genera token brevi invece di key lunghe; rotation ruota periodicamente, per esempio ogni 30 giorni, con un processo automatico che aggiorna il secret e notifica i sistemi collegati; revocation fornisce una revoca d’emergenza per disattivare subito un secret in caso di fuga; expiration imposta una scadenza dopo la quale il secret non funziona più.

MCP Security Best Practices afferma chiaramente che token passthrough è un anti-pattern: passare direttamente all’Agent il token OAuth dell’utente aggira i controlli di sicurezza, rompe l’audit trail e supera i trust boundary. Il modo corretto è emettere un delegated token quando l’utente autorizza l’Agent: breve, limitato nello scope e con audience esplicita.

I principi di OWASP Secrets Management sono centralize, least privilege, automate e auditing. L’accesso ai secret deve seguire il privilegio minimo. La manutenzione manuale aumenta rischio di fuga ed errore; rotation, revocation ed expiration fanno parte del lifecycle.

Audit log: chi ha chiamato cosa e quando?

L’audit log deve poter ricostruire “chi ha chiamato quale strumento per conto di chi, quale oggetto ha toccato e con quale risultato”, mascherando allo stesso tempo parametri e secret.

Audit Log Schema

Campo	Descrizione	Regola di mascheramento
traceId	ID della catena di chiamate, riusa il concetto trace/runId di N156	Non mascherare
timestamp	Ora della chiamata, ISO 8601	Non mascherare
actor	Entità che avvia la chiamata	Non mascherare
subject	Entità rappresentata	Non mascherare
tool	Nome dello strumento	Non mascherare
action	Tipo di operazione, come read/write/delete	Non mascherare
resource	Oggetto dell’operazione	Mascherare: customer_id → cust_***
outcome	Risultato, come success/failure/denied	Non mascherare

Regole di mascheramento: non registrare token, secret, password, email, phone o PII. Registra who/what/when/where/outcome. Esempi: customer_id=12345 diventa cust_; email=[email protected] diventa e@***.com; token=Bearer xxx diventa Bearer ***; password=secret123 non viene registrata.

Secondo OWASP Logging Cheat Sheet, i log di sicurezza devono supportare indagine, audit e monitoraggio, ma non devono registrare password, session id, access token o dati personali sensibili. Devono invece registrare informazioni tracciabili come who/what/when/where/outcome.

La famiglia audit and accountability di NIST SP 800-53 ricorda che gli audit log sono l’ultima linea di difesa di un sistema di permessi. Quando un controllo fallisce, il log deve registrare il motivo: actor senza permesso, subject senza permesso sul target, scope insufficiente.

Tabella decisionale del modello di autorizzazione: scegliere la combinazione giusta

Mapping dell’identità, permessi degli strumenti, isolamento dei Secret e audit log non sono controlli indipendenti. Sono vincoli che si combinano. Ecco le combinazioni per scenari diversi.

Scenario	identity type	tool permission	secret access	audit log	Applicazione tipica
Strumento interno a basso rischio	service account	whitelist, solo strumenti read	Variabili d’ambiente	actor/tool/outcome	Report interni, sincronizzazione pianificata
SaaS multi-tenant	delegated token + tenantId	per-tool permission filtrata per tenant	secret vault con isolamento tenant	full schema con tenantId	Agent CRM, assistente email
Transazione finanziaria	user identity + approval	scope minimization + approval	secret reference con token breve	full schema + approvalId	Approvazione trading, operazioni su fondi
Operazione su dati sensibili	delegated token + approval	whitelist + approval + guardrails	secret vault con revoca d’emergenza	full schema + mascheramento	Export dati, ricerca clienti

OWASP AI Agent Security Cheat Sheet raccomanda separate tool sets per trust level diversi ed explicit authorization per operazioni sensibili. Il punto della tabella è la composizione: gli scenari ad alto rischio richiedono più livelli di controllo, non un singolo meccanismo presentato come soluzione universale.

Checklist di troubleshooting: sintomi comuni dei problemi di permessi

Ecco sintomi comuni, cause probabili, verifiche e soluzioni.

Sintomo	Causa probabile	Verifica	Soluzione
L’Agent riceve 403 Forbidden quando chiama uno strumento	actor senza tool permission o subject senza target permission	Controllare permission_level di actor e permessi resource di subject	Confermare il mapping dell’identità e regolare la matrice dei permessi
Nei log actor è vuoto o subject è confuso	I campi di identity mapping non vengono passati correttamente	Verificare che agent context contenga actor/subject/tenantId	Passare i campi di identità lungo tutta la catena di chiamate
La chiamata allo strumento riesce, ma l’audit log manca di campi necessari	Audit Log Schema incompleto	Verificare che la logica di scrittura includa tutti i campi	Completare lo schema e aggiungere traceId/approvalId
La richiesta dell’utente A può leggere dati dell’utente B	tenantId o subject non sono isolati, oppure si condivide un token amministratore	Verificare uso di delegated token e correttezza di tenantId	Usare delegated token e imporre validazione tenantId
Dopo secret rotation l’Agent usa ancora la vecchia key	Secret reference non aggiornata o rotation non applicata	Verificare che il vault restituisca il nuovo secret e che l’Agent lo recuperi di nuovo	Fare in modo che rotation aggiorni automaticamente la reference
Dopo l’approvazione la chiamata allo strumento fallisce ancora	Guardrails falliti, per parametri fuori limite o rilevamento PII	Controllare i log di tool_input_guardrails	Regolare parametri o regole di guardrails

Checklist di implementazione: costruire un modello di permessi Agent da zero

Questi sono i 5 passi centrali per implementare il modello di permessi.

Passo 1: definire le regole di identity mapping

Punti decisionali: serve isolamento multi-tenant, quindi un campo tenantId? Esistono job in background, quindi un service account? Esistono workflow automatizzati, quindi delegated token?

Pseudocodice:

interface IdentityContext {
  actor: string;        // Entità che avvia la chiamata
  subject: string | null;  // Entità rappresentata
  delegatedBy?: string;  // Origine della delega
  tenantId?: string;    // Identificatore del tenant
}

Passo 2: progettare la matrice dei permessi degli strumenti

Punti decisionali: serve approvazione, quindi needs_approval=true? Serve filtro dinamico, quindi implementare is_enabled a runtime? Serve validare i parametri, quindi implementare tool_input_guardrails?

Esempio di codice:

interface ToolPermission {
  name: string;
  permission_level: 'read' | 'write' | 'admin';
  required_scope: string[];
  needs_approval: boolean;
  is_enabled: (context: IdentityContext) => boolean;
}

Passo 3: collegare un secret vault

Punti decisionali: servono credenziali brevi, quindi una secret reference? Serve revoca d’emergenza, quindi il vault deve supportare disattivazione immediata?

Esempio di codice:

async function getSecret(secretRef: string, context: IdentityContext): Promise<string> {
  // Verifica l'identità
  await vault.authenticate(context.actor);
  // Verifica i permessi
  await vault.authorize(context.actor, secretRef);
  // Ottiene un token breve
  const token = await vault.getToken(secretRef, expiresIn: '15m');
  // Registra l'audit
  await auditLog.record({
    actor: context.actor,
    action: 'get_secret',
    resource: secretRef,
    outcome: 'success'
  });
  return token;
}

Passo 4: implementare gli audit log

Punti decisionali: serve mascheramento, quindi regole di redaction? Serve traceId, quindi riuso di trace/runId da N156?

Esempio di codice:

interface AuditLogEntry {
  traceId: string;
  timestamp: Date;
  actor: string;
  subject: string | null;
  tool: string;
  action: 'read' | 'write' | 'delete';
  resource: string;  // Mascherato
  outcome: 'success' | 'failure' | 'denied';
}

Passo 5: testare i confini dei permessi

Punti decisionali: testerai accessi non autorizzati, come l’utente A che prova ad accedere ai dati dell’utente B? Testerai la fuga di token simulando la revoca dopo una fuga di secret? Testerai la tracciabilità dell’audit risalendo a tutta la catena tramite traceId?

Checklist di test: test di accesso non autorizzato (actor=user_A, resource=tenant_B → deve restituire 403); test di fuga token (vault.revoke(secretRef) → l’Agent non deve poter ottenere un nuovo token); test di tracciabilità Audit (cercare l’intera catena con traceId → deve includere actor/subject/tool/outcome).

Prossimo passo: letture correlate

Il modello di permessi di un Agent tocca identità, strumenti, Secret e audit su più livelli. Queste letture aiutano a completare il quadro.

Articoli pubblicati:

• Guida Agent Sandbox: la Sandbox risolve l’isolamento di esecuzione con container/Docker. Questo articolo copre confini di permessi e secret; i due aspetti si completano.
• Tool Calling nella pratica: le basi del tool calling. Questo articolo le estende con tool whitelist, per-tool permission e validazione dell’input.
• Monitoraggio e recovery degli AI Agent: basi di monitoraggio e alert. Questo articolo aggiunge campi audit e traceId.