Assegurar um agente n8n com o ID do Agente Microsoft Entra

Este guia mostra como implementar n8n em Azure Container Apps com integração ID do Agente Microsoft Entra. A implementação utiliza o CLI do Azure Developer (azd) para provisionar infraestrutura, criar objetos de identidade do Microsoft Entra e configurar automaticamente os fluxos de trabalho n8n.

Ao contrário do padrão Autenticação com o SDK de Autenticação do Microsoft Entra ID (sidecar) usado para agentes personalizados, a integração do n8n utiliza o nó da comunidade n8n-nodes-entraagentid para gerir diretamente a obtenção de tokens nos fluxos de trabalho do n8n. Os fluxos de trabalho implementados demonstram tanto fluxos de tokens autónomos (apenas aplicação) como on-behalf-of (OBO), com acesso ao Microsoft Graph e ao Microsoft Graph MCP Server for Enterprise, https://mcp.svc.cloud.microsoft/enterprise.

Pré-requisitos

Antes de começar, certifique-se de que tem:

• Uma subscrição do Azure com quota para Azure OpenAI (GPT-4o ou similar), PostgreSQL Flexible Server e Azure Container Apps.
• Administrador Global no seu tenant Microsoft Entra. Este papel é necessário porque a automação cria múltiplos objetos Microsoft Entra e concede consentimento ao administrador para permissões. Utilize Privileged Identity Management (PIM) para ativar esta função no momento necessário.

Azure Cloud Shell (recomendado) vem com tudo pré-instalado: CLI do Azure, Azure Developer CLI (azd), PowerShell 7 e Git.

Se estiver a correr localmente em vez do Cloud Shell, instale estas ferramentas antes de avançar:

• Azure Developer CLI (azd) v1.9 ou posterior.
• CLI do Azure (az) v2.60 ou posterior.
• PowerShell 7.4+.
• Microsoft.Entra o módulo PowerShell v1.2 ou posterior.
• Git.

Autentique tanto a CLI do Azure como a CLI do Azure Developer para que os comandos de implementação possam criar e gerir recursos na sua subscrição:

az login
azd auth login

Clonar e implementar

Toda a implementação é executada através de um único comando azd up que prevê Azure infraestrutura e configura automaticamente o n8n. Siga estes passos para implementar o n8n:

1. Abra Azure Cloud Shell e selecione PowerShell.

2. Clone o repositório e inicie a implementação:

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

   Em Azure Cloud Shell, azd auth login apresenta um código de dispositivo. Abra o URL mostrado e introduza o código para autenticar, depois azd up continua automaticamente.

3. Quando solicitado, forneça os seguintes valores:

   • Nome do ambiente: Qualquer nome (por exemplo, my-n8n). Usado para isolar esta implantação.
   • Subscrição do Azure: Selecione a subscrição para efetuar a implementação.
   • Azure localização: Selecione uma região (por exemplo, northeurope).
   • Email de administrador N8N: Email para a conta proprietária do n8n.
   • Palavra-passe de administrador N8N: Palavra-passe para a conta proprietária do n8n (mínimo 8 caracteres, número misto).

4. Durante a fase de pós-provisionamento, a automação realiza um segundo login. É apresentado um código de dispositivo. Abra o URL e introduza o código. Esta etapa requer o papel de Administrador Global ou Administrador de Aplicações. O hook de pós-aprovisionamento azd up em seguida:

   • Cria objetos ID do Agente Microsoft Entra (Blueprint, Identidade do Agente, Utilizador do Agente).
   • Ativa o Microsoft Graph MCP Server para Empresas.
   • Espera que o n8n fique pronto.
   • Cria a conta do proprietário.
   • Instala o @astaykov/n8n-nodes-entraagentid nó comunitário.
   • Gera uma chave API para automação n8n.
   • Cria as cinco credenciais com valores reais.
   • Importa e ativa os três fluxos de trabalho demo.

Quando a implementação é concluída, o script exibe o URL do n8n e um resumo do que foi configurado. O ID do inquilino é detetado automaticamente a partir do seu início de sessão no Azure, por isso não é necessária qualquer configuração manual.

Explorar os recursos implementados

A implementação cria recursos Azure, objetos de identidade Microsoft Entra e ativos de configuração n8n que funcionam em conjunto para suportar os fluxos de trabalho de exemplo.

Revise os recursos de infraestrutura do Azure

A implementação cria os seguintes recursos Azure:

• Ambiente de Aplicações de Contentores: Hospeda o n8n e o SPA de teste.
• Aplicação Container n8n: Executa a imagem oficial n8nio/n8n com entrada HTTPS.
• Aplicação Web Estática: Teste de SPA para o fluxo do webhook OBO.
• PostgreSQL Flexible Server: Armazenamento persistente para fluxos de trabalho, credenciais e histórico de execução (Burstable B1ms).
• Conta de Armazenamento e Partilha de Ficheiros: Diretório persistente /home/node/.n8n . Os nós da comunidade e a configuração resistem às reinicializações.
• Azure OpenAI: implementação do modelo GPT utilizado pelos fluxos de trabalho dos agentes de IA.
• Log Analytics Workspace: Diagnóstico e monitorização.

Revise os objetos de identidade do Microsoft Entra

A automação cria estes objetos uma vez e reutiliza-os em execuções subsequentes:

• Plano de identidade de agente: Registro de aplicação que emite tokens em nome das identidades de agentes através de credenciais de identidade federadas.
• Principal de serviço de identidade do agente: O principal de serviço do agente de IA. Adquire tokens Microsoft Graph e MCP de forma autónoma.
• Conta de utilizador do agente: Uma identidade de utilizador apenas na cloud que permite fluxos de tokens delegados (OBO).
• Registo de aplicação de SPA (Single Page Application): Aplicação cliente para a demonstração do webhook, pré-configurada com URIs de redirecionamento e permissões da API Blueprint.

Rever as credenciais e fluxos de trabalho do n8n

O elemento de ligação postprovision configura automaticamente o n8n.

Credenciais criadas:

• EntraAgentID - Autonomous: Microsoft Graph API token exclusivo de aplicação (sem contexto de utilizador).
• EntraAgentID - Agent User OBO: Token delegado em nome do Utilizador Agente.
• Azure OpenAI: Ligação ao modelo GPT implementado para fluxos de trabalho de agentes de IA.
• Gestor de Autenticação AgentID - Token de Acesso: Encaminhamento de tokens do Gestor de Autenticação para os nós a jusante.
• Token de Portador da AuthManager: Encaminhamento de tokens de portador para chamadas MCP.

Fluxos de trabalho importados:

• Gestor de Autenticação do ID do Agente - Utilizador do Agente com MCP Enterprise: Adquire um token MCP delegado para o Utilizador Agente e reencaminha-o para um subfluxo de trabalho.
• HTTP Request com token de agente autónomo: Demonstra um agente autónomo que chama o Microsoft Graph diretamente com um token somente da app.
• Webhook - agente interativo (em nome de): Ponto de entrada do webhook que recebe um token bearer da SPA, chama o Gestor de Autenticação e responde através do Graph MCP Server em nome do utilizador com sessão iniciada.

Entender o fluxo de tokens

A implementação do n8n suporta dois padrões de fluxo de tokens:

• Autónoma (apenas aplicação): O fluxo de trabalho n8n utiliza as credenciais Agent Identity Blueprint com as Federated Identity Credentials para adquirir um token exclusivo da app para o principal do serviço Agent Identity. O fluxo de trabalho chama então diretamente o Microsoft Graph com este token. Não está envolvido o contexto do utilizador.

• Em nome de (OBO) com MCP: Um SPA baseado em browser envia um token portador para um webhook n8n. O webhook aciona o fluxo de trabalho Auth Manager, que utiliza as credenciais Blueprint para adquirir um token delegado em nome do Agent User. O Gestor de Autenticação encaminha o token para um subworkflow que chama o Microsoft Graph MCP Server for Enterprise, que traduz chamadas de ferramentas MCP em pedidos da API Microsoft Graph usando o token delegado.

Em ambos os padrões, o Agente Identity Blueprint atua como uma fábrica de tokens. O Agent Identity Blueprint emite tokens para Identidades de Agente sem armazenar credenciais no próprio agente. O nó da comunidade Auth Manager gere a aquisição de tokens e a cache AES-256-GCM em cada execução de um workflow.

Implantar o SPA de teste (opcional)

O teste SPA é uma aplicação JavaScript estática que demonstra o fluxo do Webhook OBO a partir de um navegador.

1. Implemente-o após a conclusão do provisionamento inicial:

   azd deploy spa
   

Compreenda os escopos dos servidores MCP

A configuração concede os seguintes escopos delegados MCP.* ao principal do serviço de Identidade do Agente. Estes escopos espelham os seus equivalentes Microsoft Graph (por exemplo, MCP.User.Read.All corresponde a User.Read.All):

• MCP.User.Read.All: Leia todos os utilizadores.
• MCP.Organization.Read.All: Leia informações sobre a organização dos inquilinos.
• MCP.Group.Read.All: Leia todos os grupos.
• MCP.GroupMember.Read.All: Leia as filiações a grupos.
• MCP.Application.Read.All: Leia registos de aplicações e princípios de serviço.
• MCP.AuditLog.Read.All: Ler registos de login e auditoria.
• MCP.Reports.Read.All: Leia Microsoft 365 relatórios de utilização.
• MCP.Policy.Read.All: Leia as políticas de acesso condicional.
• MCP.Domain.Read.All: Leia domínios verificados.
• MCP.Device.Read.All: Leia dispositivos registados no Microsoft Entra.

Para adicionar mais escopos, edite o $MCP_SCOPES array em scripts/Setup-EntraAgentId.ps1 e volte a executar azd provision.

Reexecute e atualize a implementação

A implementação é totalmente idempotente:

• O Bicep ignora recursos do Azure que já existem.
• O ambiente azd guarda IDs de objeto do Microsoft Entra (Blueprint, Identidade do Agente, Utilizador do Agente, segredo do Blueprint) após a primeira execução e reutiliza-os nas execuções seguintes.
• A configuração do N8N (credenciais, fluxos de trabalho) é aplicada de novo em cada execução, o que permite reparar um estado avariado.

Para reexecutar apenas os scripts postprovision sem modificar a infraestrutura, execute o provisioning novamente. Os templates Bicep não detetam alterações na infraestrutura e apenas executam os hooks de implementação:

azd provision   # Bicep detects no changes, runs hooks only

Executar os scripts manualmente (opcional)

Podes executar os scripts de configuração de forma independente, se necessário:

• Completo fim a fim (Microsoft Entra e n8n):

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

• Apenas configuração n8n (evite a configuração Entra):

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

• Configuração Entra apenas:

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

Limpeza de recursos

Remova todos os recursos Azure criados pela implementação e elimine qualquer estado de implementação retido:

azd down --purge

Conteúdo relacionado

• Integrar agentes de terceiros com ID do Agente Microsoft Entra
• Autenticação com Microsoft Entra ID Auth SDK (sidecar)
• Nó da comunidade n8n-nodes-entraagentid
• Visão geral da CLI do desenvolvedor do Azure