Proteggere un agente n8n con Microsoft Entra Agent ID

Questa guida illustra come distribuire n8n in App contenitore di Azure con integrazione Microsoft Entra Agent ID. La distribuzione usa l'interfaccia della riga di comando Azure Developer (azd) per effettuare il provisioning dell'infrastruttura, creare oggetti identity Microsoft Entra e configurare automaticamente flussi di lavoro n8n.

A differenza del modello authentication with Microsoft Entra ID Auth SDK (sidecar) usato per gli agenti personalizzati, l'integrazione n8n usa il nodo della community n8n-nodes-entraagentid per gestire l'acquisizione dei token direttamente all'interno dei flussi di lavoro n8n. I flussi di lavoro distribuiti illustrano sia i flussi di token autonomi (solo app) che i flussi di token OBO (on-behalf-of), con accesso a Microsoft Graph e al Microsoft Graph MCP Server for Enterprise, https://mcp.svc.cloud.microsoft/enterprise.

Prerequisiti

Prima di iniziare, assicurarsi di avere:

• Sottoscrizione Azure con quota per Azure OpenAI (GPT-4o o simile), server flessibile PostgreSQL e App contenitore di Azure.
• Amministratore globale nel tenant Microsoft Entra. Questo ruolo è obbligatorio perché l'automazione crea più oggetti Microsoft Entra e concede il consenso amministratore alle autorizzazioni. Usare Privileged Identity Management (PIM) per attivare questo ruolo giusto in tempo.

Azure Cloud Shell (scelta consigliata) include tutti gli elementi preinstallati: interfaccia della riga di comando di Azure, interfaccia della riga di comando per sviluppatori Azure (azd), PowerShell 7 e Git.

Se si esegue localmente anziché Cloud Shell, installare questi strumenti prima di procedere:

• Azure Developer CLI (azd) v1.9 o versione successiva.
• interfaccia della riga di comando di Azure (az) v2.60 o versione successiva.
• PowerShell 7.4+.
• Microsoft.Entra PowerShell module v1.2 o versione successiva.
• Git.

Autentica sia interfaccia della riga di comando di Azure sia Azure Developer CLI in modo che i comandi di distribuzione possano creare e gestire risorse nella tua sottoscrizione:

az login
azd auth login

Clonare e distribuire

L'intera distribuzione viene eseguita tramite un singolo comando azd up che effettua il provisioning dell'infrastruttura Azure e configura automaticamente n8n. Seguire questa procedura per distribuire n8n:

1. Aprire Azure Cloud Shell e selezionare PowerShell.

2. Clonare il repository e avviare la distribuzione:

   git clone https://github.com/astaykov/n8n-aca.git && cd n8n-aca && azd auth login && azd up
   

   In Azure Cloud Shell azd auth login visualizza un codice del dispositivo. Aprire l'URL visualizzato e immettere il codice da autenticare, quindi azd up continua automaticamente.

3. Quando richiesto, specificare i valori seguenti:

   • Nome ambiente: Qualsiasi nome (ad esempio, my-n8n). Usato per isolare questa implementazione.
   • Azure subscription: Selezionare la sottoscrizione in cui eseguire la distribuzione.
   • Azure location: Selezionare un'area, ad esempio northeurope.
   • n8n admin email: Indirizzo email per l'account proprietario n8n.
   • n8n admin password: Password per l'account proprietario n8n (minimo 8 caratteri, maiuscole/minuscole, numero).

4. Durante la fase di post-provisioning, l'automazione esegue un secondo accesso. Viene visualizzato un codice del dispositivo. Aprire l'URL e immettere il codice. Questo passaggio richiede il ruolo Amministratore globale o Amministratore applicazioni. L'hook azd up postprovision quindi:

   • Crea Microsoft Entra Agent ID oggetti (Blueprint, Agent Identity, Agent User).
   • Abilita l'Microsoft Graph MCP Server for Enterprise.
   • Attende che n8n diventi pronto.
   • Crea l'account proprietario.
   • Installa il nodo community @astaykov/n8n-nodes-entraagentid.
   • Genera una chiave API per l'automazione n8n.
   • Crea cinque credenziali, tutte con valori reali.
   • Importa e attiva i tre flussi di lavoro demo.

Al termine della distribuzione, lo script stampa l'URL n8n e un riepilogo di ciò che è stato configurato. L'ID tenant viene rilevato automaticamente dall'accesso Azure, quindi non è necessaria alcuna configurazione manuale.

Esplorare le risorse distribuite

La distribuzione crea risorse di Azure, oggetti di identità di Microsoft Entra e risorse di configurazione di n8n che lavorano insieme per supportare i flussi di lavoro di esempio.

Esaminare le risorse dell'infrastruttura Azure

La distribuzione crea le risorse Azure seguenti:

• Ambiente app contenitore: Ospita n8n e l'applicazione a pagina singola di test.
• App contenitore n8n: Esegue l'immagine ufficiale n8nio/n8n con ingresso HTTPS.
• App Web statica: Testare SPA per il flusso del webhook OBO.
• Server flessibile PostgreSQL: Memoria persistente per flussi di lavoro, credenziali e storia di esecuzione (Burstable B1ms).
• Account di archiviazione e condivisione di file: Directory persistente /home/node/.n8n . I nodi della community e la configurazione sopravvivono ai riavvii.
• Azure OpenAI: distribuzione del modello GPT usata dai flussi di lavoro dell'agente di intelligenza artificiale.
• Log Analytics Workspace: Diagnostica e monitoraggio.

Esaminare gli oggetti di identità di Microsoft Entra

L'automazione crea questi oggetti una volta e li riutilizza nelle esecuzioni successive:

• Progetto di identità dell'agente: Registrazione dell'app che rilascia token per conto delle identità dell'agente tramite le credenziali di identità federate.
• Entità servizio identità dell'agente: Entità servizio principale dell'agente di intelligenza artificiale. Acquisisce i token Microsoft Graph e MCP in modo autonomo.
• Account utente agente: Un'identità utente solo cloud che abilita i flussi di token delegati (OBO).
• Registrazione dell'app a pagina singola (SPA): App client per la demo del webhook, preconfigurata con URI di reindirizzamento e autorizzazioni API blueprint.

Esaminare le credenziali e i flussi di lavoro n8n

L'hook postprovision configura automaticamente n8n:

Credenziali create:

• EntraAgentID - Autonomous: Token API Microsoft Graph solo per app (senza contesto utente).
• EntraAgentID - utente agente OBO: Token delegato per conto dell'agente utente.
• Azure OpenAI: Connessione al modello GPT distribuito per i workflow degli agenti di intelligenza artificiale.
• AgentID Auth Manager - Token di accesso: Inoltro di token da Gestione autenticazione a nodi downstream.
• Bearer da AuthManager: Inoltro di token di connessione per le chiamate MCP.

Flussi di lavoro importati:

• Id agente Auth Manager - Utente Agente con MCP Enterprise: Acquisisce un token MCP delegato per l'Utente Agente e lo inoltra a un sottoprocesso.
• HTTP Request with autonomous agent token: Illustra un agente autonomo che chiama Microsoft Graph direttamente con un token solo app.
• Webhook - agente interattivo (on-behalf-of): Punto di ingresso del webhook che riceve un token bearer dalla SPA, invoca Auth Manager e risponde tramite Graph MCP Server per conto dell'utente autenticato.

Informazioni sul flusso del token

La distribuzione n8n supporta due modelli di flusso di token:

• Autonomo (solo app): Il flusso di lavoro n8n usa le credenziali di Agent Identity Blueprint con le Federated Identity Credentials per acquisire un token app-only per l'entità di servizio di identità agente. Il flusso di lavoro chiama quindi Microsoft Graph direttamente con questo token. Non è coinvolto alcun contesto utente.

• On-behalf-of (OBO) con MCP: Un'applicazione a pagina singola basata su browser invia un token portatore a un webhook n8n. Il webhook chiama il flusso di lavoro del Gestore di Autenticazione, che usa le credenziali Blueprint per acquisire un token delegato per conto dell'utente agente. Auth Manager inoltra il token a un flusso di lavoro secondario che chiama il Microsoft Graph MCP Server for Enterprise, che converte le chiamate dello strumento MCP in richieste API Microsoft Graph usando il token delegato.

In entrambi i modelli, agent Identity Blueprint funge da factory di token. Agent Identity Blueprint rilascia i token per le identità dell'agente senza archiviare le credenziali nell'agente stesso. Il nodo della community di Auth Manager gestisce l'acquisizione dei token e la memorizzazione nella cache AES-256-GCM all'interno di ogni esecuzione del flusso di lavoro.

Distribuire l'applicazione a pagina singola (SPA) di test (facoltativo)

L'SPA di test è un'app JavaScript statica che illustra il flusso del webhook OBO da un browser.

1. Distribuirlo al termine del provisioning iniziale:

   azd deploy spa
   

Informazioni sugli ambiti del server MCP

L'installazione concede i seguenti ambiti delegati MCP.* al principale del servizio Identità agente. Questi ambiti rispecchiano le controparti Microsoft Graph ,ad esempio MCP.User.Read.All corrisponde a User.Read.All):

• MCP.User.Read.All: Leggi tutti gli utenti.
• MCP.Organization.Read.All: Leggere le informazioni della tenant organization.
• MCP.Group.Read.All: legge tutti i gruppi.
• MCP.GroupMember.Read.All: leggi le appartenenze ai gruppi.
• MCP.Application.Read.All: Leggere le registrazioni delle app e i principali di servizio.
• MCP.AuditLog.Read.All: legge i log di accesso e di controllo.
• MCP.Reports.Read.All: leggere i report sull'utilizzo di Microsoft 365.
• MCP.Policy.Read.All: legge i criteri di accesso condizionale.
• MCP.Domain.Read.All: legge i domini verificati.
• MCP.Device.Read.All: leggere i dispositivi registrati Microsoft Entra.

Per aggiungere altri ambiti, modificare la $MCP_SCOPES matrice in scripts/Setup-EntraAgentId.ps1 ed eseguire azd provisiondi nuovo .

Rieseguire e aggiornare la distribuzione

La distribuzione è completamente idempotente:

• Bicep ignora le risorse Azure già esistenti.
• L'ambiente azd salva gli ID oggetto Microsoft Entra (Blueprint, Agent Identity, Agent User, Blueprint secret) dopo la prima esecuzione e li riutilizza nelle esecuzioni successive.
• La configurazione n8n (credenziali, flussi di lavoro) viene applicata fresca ad ogni esecuzione, che consente di riparare uno stato danneggiato.

Per rieseguire solo gli script di postprovisioning senza modificare l'infrastruttura, eseguire di nuovo il provisioning. I modelli di Bicep non rilevano modifiche all'infrastruttura ed eseguono solo gli hook di distribuzione:

azd provision   # Bicep detects no changes, runs hooks only

Eseguire gli script manualmente (facoltativo)

Se necessario, è possibile eseguire gli script di configurazione in modo indipendente:

• Completamente end-to-end (Microsoft Entra e n8n):

  .\scripts\Run-All.ps1 `
      -TenantId  "<your-tenant-id>" `
      -N8nUrl    "https://ca-n8n-<token>.<region>.azurecontainerapps.io"
  

• Solo configurazione n8n (ignorare l'installazione di Entra):

  .\scripts\Configure-N8n.ps1 `
      -N8nUrl          "https://ca-n8n-<token>.<region>.azurecontainerapps.io" `
      -OwnerEmail      "admin@contoso.com" `
      -OwnerPassword   "MyStr0ngPassword!"
  

• Solo configurazione Entra:

  .\scripts\Setup-EntraAgentId.ps1 `
      -TenantId  "<your-tenant-id>" `
      -N8nUrl    "https://ca-n8n-<token>.<region>.azurecontainerapps.io"
  

Pulire le risorse

Rimuovere tutte le risorse Azure create dalla distribuzione ed eliminare qualsiasi stato di distribuzione conservato:

azd down --purge

Contenuti correlati

• Integrate agenti di terze parti con Microsoft Entra Agent ID
• Autenticazione con Microsoft Entra ID Auth SDK (sidecar)
• nodo comunitario n8n-nodes-entraagentid
• Panoramica dell'interfaccia della riga di comando per sviluppatori di Azure