Sichern eines n8n-Agents mit Microsoft Entra-Agent-ID

In diesem Handbuch wird gezeigt, wie Sie n8n für Azure Container Apps mit Microsoft Entra-Agent-ID Integration bereitstellen. Die Bereitstellung verwendet die Azure Developer CLI (azd), um Infrastruktur bereitzustellen, Microsoft Entra Identitätsobjekte zu erstellen und n8n-Workflows automatisch zu konfigurieren.

Im Gegensatz zum für benutzerdefinierte Agents verwendeten Sidecar-Muster verwendet diese Integration den n8n-nodes-entraagentid Community-Knoten, um die Tokenakquisition direkt in n8n-Workflows zu verwalten. Die bereitgestellten Workflows demonstrieren sowohl autonome (nur App) als auch im Auftrag von (OBO) Token-Flows mit Zugriff auf Microsoft Graph und den Microsoft Graph MCP Server for Enterprise, https://mcp.svc.cloud.microsoft/enterprise.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie folgendes haben:

• Ein Azure-Abonnement mit Kontingent für Azure OpenAI (GPT-4o oder ähnlich), PostgreSQL Flexible Server und Azure Container Apps.
• Global Administrator Rolle in Ihrem Microsoft Entra Mandanten. Diese Rolle ist erforderlich, da die Automatisierung mehrere Microsoft Entra Objekte erstellt und administratorberechtigungen erteilt. Verwenden Sie Privileged Identity Management (PIM), um diese Rolle just-in-time zu aktivieren.

Azure Cloud Shell (empfohlen) enthält alles vorinstalliert: Azure CLI, Azure Developer CLI (azd), PowerShell 7 und Git.

Wenn Sie lokal arbeiten, anstatt die Cloud Shell zu verwenden, installieren Sie diese Tools, bevor Sie fortfahren:

• Azure Developer CLI (azd) v1.9 oder höher.
• Azure CLI (az) v2.60 oder höher.
• PowerShell 7.4+.
• Microsoft. Entra PowerShell-Modul v1.2 oder höher.
• Git.

Melden Sie sich vor dem Ausführen der Bereitstellung bei Azure CLI und Azure Developer CLI an:

az login
azd auth login

Klonen und Bereitstellen

Die gesamte Bereitstellung wird über einen einzelnen azd up-Befehl ausgeführt, der Azure Infrastruktur bereit stellt und n8n automatisch konfiguriert. Führen Sie die folgenden Schritte aus, um n8n bereitzustellen:

1. Öffnen Sie Azure Cloud Shell, und wählen Sie PowerShell aus.

2. Klonen Sie das Repository, und starten Sie die Bereitstellung:

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

   In Azure Cloud Shell zeigt azd auth login einen Gerätecode an. Öffnen Sie die angezeigte URL und geben Sie den Code ein, um sich zu authentifizieren; danach wird automatisch mit azd up fortgefahren.

3. Wenn Sie dazu aufgefordert werden, geben Sie die folgenden Werte an:

   • Umgebungsname: Ein beliebiger Name (z. B my-n8n. ). Wird verwendet, um diese Bereitstellung zu isolieren.
   • Azure subscription: Wählen Sie das abonnement aus, in dem sie bereitgestellt werden soll.
   • Azure location: Wählen Sie einen Bereich aus (z. B. northeurope).
   • n8n-Administrator-E-Mail: E-Mail für das n8n-Besitzerkonto.
   • n8n Administratorkennwort: Kennwort für das n8n-Besitzerkonto (mindestens 8 Zeichen, Gemischte Groß-/Kleinschreibung, Nummer).

4. Während der Postprovisionsphase führt die Automatisierung eine zweite Anmeldung durch. Es wird ein Gerätecode angezeigt. Öffnen Sie die URL, und geben Sie den Code ein. Dieser Schritt erfordert die Rolle "Globaler Administrator" oder "Anwendungsadministrator". Der Postprovision-Hook dann:

   • Erstellt Microsoft Entra-Agent-ID Objekte (Blueprint, Agent Identity, Agent User).
   • Aktiviert den Microsoft Graph MCP Server for Enterprise.
   • Wartet, bis n8n bereit ist.
   • Erstellt das Besitzerkonto.
   • Installiert den @astaykov/n8n-nodes-entraagentid Community-Knoten.
   • Generiert einen API-Schlüssel für die n8n-Automatisierung.
   • Erstellt alle fünf Anmeldedaten mit echten Werten.
   • Importiert und aktiviert die drei Demoworkflows.

Nach Abschluss der Bereitstellung gibt das Skript Ihre n8n-URL und eine Zusammenfassung der Konfigurationen aus. Die Mandanten-ID wird automatisch von Ihrer Azure Anmeldung erkannt, sodass keine manuelle Konfiguration erforderlich ist.

Erkunden der bereitgestellten Ressourcen

Azure-Infrastruktur

Die Bereitstellung erstellt die folgenden Azure-Ressourcen:

• Container-Apps-Umgebung: Hosten n8n und die Test-SPA.
• n8n Container-App: Führt das offizielle n8nio/n8n Image mit HTTPS-Ingress aus.
• Statische Web-App: Testen Sie SPA für den OBO-Webhook-Fluss.
• PostgreSQL Flexible Server: Beständiger Speicher für Workflows, Anmeldeinformationen und Ausführungsverlauf (Burstable B1ms).
• Speicherkonto und Dateifreigabe: Persistentes /home/node/.n8n Verzeichnis. Community-Knoten und Konfiguration überdauern Neustarts.
• Azure OpenAI: GPT-Modellbereitstellung, die von den AI-Agent-Workflows verwendet wird.
• Log Analytics Workspace: Diagnose und Überwachung.

Microsoft Entra Identitätsobjekte

Die Automatisierung erstellt diese Objekte einmal und verwendet sie bei nachfolgenden Ausführungen wieder:

• Agentidentitäts-Blueprint: App-Registrierungsvorgang, der Token im Namen von Agentidentitäten über Verbundidentitätsanmeldeinformationen ausgibt.
• Agent-Identitätsdienstprinzipal: Dienstprinzipal des KI-Agents. Erwirbt Microsoft Graph- und MCP-Token autonom.
• Agent-Benutzerkonto: Eine reine Cloudbenutzeridentität, die delegierte Tokenflüsse (OBO) ermöglicht.
• Single Page App (SPA)-App-Registrierung: Client-App für die Webhook-Demo, vorkonfiguriert mit Umleitungs-URIs und Blueprint-API-Berechtigungen.

n8n-Anmeldeinformationen und -workflows

Der Postprovision-Hook konfiguriert automatisch n8n:

Erstellte Anmeldeinformationen:

• EntraAgentID - Autonomous: App-only Microsoft Graph-API Token (kein Benutzerkontext).
• EntraAgentID - Agent User OBO: Delegiertes Token im Namen des Agent-Benutzers.
• Azure OpenAI: Verbindung mit dem bereitgestellten GPT-Modell für KI-Agent-Workflows.
• AgentID Auth Manager – Zugriffstoken: Tokenweiterleitung vom Auth-Manager an downstream-Knoten.
• Bearer von AuthManager: Weiterleitung von Bearer-Token für MCP-Aufrufe.

Importierte Workflows:

• Agent ID Auth Manager – Agent-Benutzer mit MCP Enterprise: Erwirbt ein delegiertes MCP-Token für den Agent-Benutzer und leitet es an einen Unterworkflow weiter.
• HTTP-Anforderung mit autonomem Agenttoken: Veranschaulicht einen autonomen Agent, der Microsoft Graph direkt mit einem Nur-App-Token aufruft.
• Webhook - Hilfsagent (im Auftrag von): Webhook-Einstiegspunkt, der ein Bearertoken vom SPA empfängt, den Auth-Manager aufruft und über den Graph MCP-Server im Namen des angemeldeten Benutzers antwortet.

Grundlegendes zum Tokenfluss

Die n8n-Bereitstellung unterstützt zwei Tokenflussmuster:

• Autonom (nur App): Der n8n-Workflow verwendet die Agent Identity Blueprint-Anmeldeinformationen mit Federated Identity Credentials, um ein App-Only-Token für den Agent Identity-Dienstprinzipal zu erhalten. Der Workflow ruft dann Microsoft Graph direkt mit diesem Token auf. Kein Benutzerkontext ist involviert.

• Im Auftrag von (OBO) mit MCP: Eine browserbasierte SPA sendet ein Bearertoken an einen n8n-Webhook. Der Webhook ruft den Auth-Manager-Workflow auf, der die Blueprint-Anmeldeinformationen verwendet, um ein delegiertes Token im Namen des Agent-Benutzers abzurufen. Der Authentifizierungs-Manager leitet das Token an einen Unterworkflow weiter, der den Microsoft Graph MCP Server for Enterprise aufruft, der MCP-Toolaufrufe mithilfe des delegierten Tokens in Microsoft Graph API-Anforderungen übersetzt.

In beiden Mustern fungiert der Agent Identity Blueprint als Tokenfactory. Token für Agentidentitäten werden ausgegeben, ohne Anmeldeinformationen für den Agent selbst zu speichern. Der Auth Manager-Communityknoten behandelt die Tokenakquisition und die AES-256-GCM-Zwischenspeicherung innerhalb der einzelnen Workflowausführungen.

Bereitstellen des Test-SPA (optional)

Der Test-SPA ist eine statische JavaScript-App, die den OBO-Webhook-Vorgang aus einem Browser veranschaulicht.

1. Stellen Sie sie nach Abschluss der ersten Bereitstellung bereit:

   azd deploy spa
   

Grundlegendes zu den MCP-Serverbereichen

Das Setup gewährt dem Agent Identity-Dienstprinzipal die folgenden delegierten MCP.*-Bereiche. Diese Scopes spiegeln ihre Microsoft Graph-Gegenstücke wider (zum Beispiel: MCP.User.Read.All entspricht User.Read.All):

• MCP.User.Read.All: Alle Benutzer anzeigen.
• MCP.Organization.Read.All: Informationen zur Mandantenorganisation lesen.
• MCP.Group.Read.All: Alle Gruppen anzeigen.
• MCP.GroupMember.Read.All: Gruppenmitgliedschaften lesen.
• MCP.Application.Read.All: App-Registrierungen und Dienstprinzipale lesen.
• MCP.AuditLog.Read.All: Lesen von Anmelde- und Prüfprotokollen.
• MCP.Reports.Read.All: Lesen Microsoft 365 Nutzungsberichte.
• MCP.Policy.Read.All: Richtlinien für bedingten Zugriff lesen.
• MCP.Domain.Read.All: Überprüfte Domänen lesen.
• MCP.Device.Read.All: Lesen Sie bei Microsoft Entra registrierte Geräte.

Um weitere Geltungsbereiche hinzuzufügen, bearbeiten Sie das $MCP_SCOPES-Array in scripts/Setup-EntraAgentId.ps1 und führen Sie azd provision erneut aus.

Erneut ausführen und Bereitstellung aktualisieren

Die Bereitstellung ist vollständig idempotent:

• Bicep überspringt Azure ressourcen, die bereits vorhanden sind.
• Die azd-Umgebung speichert Microsoft Entra Objekt-IDs (Blueprint, Agent Identity, Agent User, Blueprint Secret) nach der ersten Ausführung und verwendet sie bei nachfolgenden Ausführungen wieder.
• n8n-Konfiguration (Anmeldeinformationen, Workflows) wird bei jeder Ausführung neu angewendet, sodass ein fehlerhafter Zustand repariert werden kann.

Um nur die Nachbereitungs-Skripte erneut auszuführen, ohne die Infrastruktur zu ändern:

azd provision   # Bicep detects no changes, runs hooks only

Manuelles Ausführen der Skripts (optional)

Sie können die Konfigurationsskripts bei Bedarf unabhängig ausführen:

• Vollständige End-to-End-Lösung (Microsoft Entra und n8n):

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

• Nur n8n-Konfiguration (Entra-Setup überspringen):

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

• Nur Entra-Setup:

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

Bereinigen von Ressourcen

Entfernen Sie alle Azure-Ressourcen, die von der Bereitstellung erstellt wurden.

azd down --purge

Verwandte Inhalte

• Integrieren Sie Drittanbieter-Agenten mit Microsoft Entra-Agent-ID
• Authentifizierung mit Microsoft Entra Auth SDK (Sidecar)
• n8n-nodes-entraagentid community node
• Übersicht über die Azure Developer CLI