Integrare agenti di terze parti con Microsoft Entra Agent ID

Microsoft Entra Agent ID consente agli agenti di intelligenza artificiale di piattaforme di terze parti di autenticare e accedere in modo sicuro alle API senza gestire direttamente le credenziali. Questo articolo illustra due modelli di integrazione, Microsoft Entra ID Auth SDK (sidecar) e federazione, per piattaforme come Amazon Web Service (AWS) Bedrock e n8n.

Prerequisiti

Prima di iniziare, assicurarsi di avere:

  • Microsoft Entra tenant con funzionalità di identità dell'agente abilitate.
  • Sottoscrizione Azure, necessaria per alcune opzioni di distribuzione.
  • Docker e Docker Compose per il modello sidecar.
  • Credenziali o configurazione della federazione, a seconda del modello scelto.
  • PowerShell 7.5 o versione successiva con il modulo powerShell Microsoft Graph.
  • Ruolo amministratore globale , obbligatorio solo per la configurazione iniziale. Usare Privileged Identity Management (PIM) per attivare questo ruolo giusto in tempo.
  • Amministratore applicazioni Cloud o Amministratore di applicazioni per concedere autorizzazioni delegate Microsoft Graph per le operazioni di gestione degli agenti.

Per verificare che l'ambiente sia pronto:

  1. Verificare di avere le autorizzazioni per creare applicazioni e entità servizio nel tenant Microsoft Entra.
  2. Se si esegue la distribuzione in Azure, verificare la sottoscrizione e il gruppo di risorse.
  3. Esaminare la documentazione per la piattaforma agente, ad esempio AWS Bedrock o n8n.

Perché è necessaria l'integrazione dell'agente di terze parti

Le organizzazioni usano agenti di intelligenza artificiale da più piattaforme, ad esempio AWS Bedrock, n8n e altri. Questi agenti spesso devono:

  • Chiamare api di Microsoft, ad esempio Microsoft Graph e servizi di Azure.
  • Accedere alle API e alle risorse interne.
  • Eseguire l'autenticazione in modo sicuro senza archiviare segreti nel codice o nella configurazione.

Microsoft Entra Agent ID fornisce un servizio di identità centralizzato e sicuro che gli agenti di terze parti possono usare per acquisire token su richiesta, senza gestire direttamente segreti o certificati. Usando Microsoft Entra Agent ID, è possibile:

  • Rimuovere la necessità degli agenti di gestire direttamente le credenziali.
  • Usare la federazione di identità del carico di lavoro per agenti che operano al di fuori di Azure.
  • Supportare più modelli di autenticazione, tra cui credenziali client, identità federata e a nome di qualcun altro.
  • Eseguire l'integrazione con piattaforme di agenti di terze parti usando Microsoft Entra ID Auth SDK (sidecar).

Modelli di integrazione per agenti di terze parti

Per integrare agenti di terze parti con Microsoft Entra Agent ID, scegliere tra i modelli seguenti:

Usare Microsoft Entra ID Auth SDK (sidecar)

Il pattern sidecar esegue l'SDK di autenticazione di Microsoft Entra ID (sidecar) come contenitore di supporto accanto all'agente. L'agente invoca il sidecar per ottenere i token per le chiamate API. L'agente non gestisce mai le credenziali direttamente; delega invece l'acquisizione di token al sidecar.

Ideale per:

  • Agenti containerizzati su Docker o Kubernetes.
  • Agenti AWS Bedrock in esecuzione nella vostra orchestrazione.
  • Sviluppo locale con Docker Compose.
  • Le organizzazioni usano già l'infrastruttura dei contenitori.

Piattaforme supportate:

  • AWS Bedrock, inclusi Claude e altri modelli di base.
  • Modelli di linguaggio di grandi dimensioni locali, ad esempio Ollama con LangChain.
  • Qualsiasi agente containerizzato.

Vantaggi:

  • Codice agente senza credenziali.
  • Funziona con qualsiasi agente containerizzato.
  • Sviluppo locale semplice con Docker Compose.
  • Può essere distribuito in App contenitore di Azure, Kubernetes o in locale.

Considerazione:

  • Richiede la gestione di un secondo contenitore.

Il diagramma seguente illustra l'architettura sidecar. Un contenitore agente e un sidecar container funzionano insieme nello stesso ambiente di orchestrazione. L'agente richiede token dal sidecar, che comunica con Microsoft Entra Agent ID per acquisire i token di accesso.

Diagramma che mostra l'architettura del pattern sidecar con un agente e un container sidecar in esecuzione nello stesso ambiente di orchestrazione, in cui il sidecar richiede token da Microsoft Entra Agent ID.

Usare la federazione dell'identità del carico di lavoro (scambio diretto di identità)

Il modello di federazione utilizza il Workload Identity Federation per scambiare credenziali da provider di identità esterni, come ad esempio AWS Security Token Service (STS), direttamente per i token Microsoft Entra. Questo modello non richiede un sidecar.

Ideale per:

  • Agenti AWS che usano STS e OIDC.
  • Organizzazioni che dispongono già di un'infrastruttura federativa.
  • Agenti che non possono eseguire contenitori.

Piattaforme supportate:

  • Identità del carico di lavoro GCP → Microsoft Entra Agent ID.
  • AWS STS → Microsoft Entra Agent ID.

Vantaggi:

  • Non è necessario alcun sidecar.
  • Usa l'infrastruttura esistente in AWS e altre piattaforme.
  • Scambio di token diretto a livello di identità.

Requirements:

  • Credenziali di identità federate preconfigurate in Microsoft Entra.
  • Una piattaforma agente che supporta OIDC o STS.

Il diagramma seguente illustra il flusso di federazione. Un agente in una piattaforma di terze parti autentica tramite il proprio provider di identità nativo del carico di lavoro, scambia il token OIDC risultante con un token Microsoft Entra, per poi chiamare le tue API.

Diagram che mostra il flusso del modello di federazione in cui un agente della piattaforma di terze parti scambia un token OIDC tramite Microsoft Entra Agent ID per accedere alle API o alle API Microsoft.

Comprendere il flusso del token

Entrambi i modelli seguono lo stesso flusso di token di base:

  1. Agent richiede un token. L'agente, oppure il sidecar per conto dell'agente, invia una richiesta a Microsoft Entra Agent ID utilizzando le credenziali di autenticazione.
  2. Microsoft Entra convalida l'identità. Microsoft Entra verifica l'identità dell'agente tramite credenziali client, credenziali federate o un altro metodo supportato.
  3. Microsoft Entra restituisce un token. L'agente riceve un token di accesso Microsoft Entra.
  4. Agent chiama l'API. L'agente usa il token per eseguire l'autenticazione per Microsoft o API personalizzate.
  5. L'API convalida il token. L'API controlla la firma e le attestazioni del token, quindi concede l'accesso.

Scenari di integrazione comuni

AWS Bedrock Agent chiama Microsoft Graph

Un agente AWS Bedrock, ad esempio Claude, deve eseguire query sui dati di Microsoft 365 o gestire le risorse tramite Microsoft Graph. Il modello sidecar è ideale per questo scenario. Per integrare un agente AWS Bedrock con il modello sidecar:

  1. Distribuire l'agente e il sidecar su AWS o sulla propria infrastruttura.
  2. Configurare un'identità agente in Microsoft Entra con autorizzazioni per Microsoft Graph.
  3. L'agente chiama il sidecar per ottenere un token.
  4. Il sidecar acquisisce un token da Microsoft Entra Agent ID.
  5. L'agente usa il token per chiamare Microsoft Graph.

Per istruzioni dettagliate, vedere Secure an Amazon Bedrock agent with Microsoft Entra Agent ID(Sicurezza di un agente Amazon Bedrock con Microsoft Entra Agent ID.

Agente n8n che chiama Microsoft Graph e MCP Server for Enterprise

Un agente n8n deve accedere ai dati Microsoft 365 tramite Microsoft Graph o il Server MCP di Microsoft Graph per l'Enterprise. Questo scenario usa il nodo della community n8n-nodes-entraagentid per gestire l'acquisizione dei token direttamente all'interno dei flussi di lavoro n8n. Per integrare un agente n8n:

  1. Distribuire n8n in App contenitore di Azure usando l'interfaccia della riga di comando di Azure Developer (azd).
  2. Configurare un'identità agente in Microsoft Entra con autorizzazioni per Microsoft Graph.
  3. Il flusso di lavoro n8n usa il nodo della community per acquisire un token da Microsoft Entra Agent ID.
  4. L'agente usa il token per chiamare Microsoft Graph o MCP Server for Enterprise.

Per istruzioni dettagliate, vedere Secure an n8n agent with Microsoft Entra Agent ID(Sicurezza di un agente n8n con Microsoft Entra Agent ID.

Sviluppo locale con Ollama

Si sta sviluppando con un LLM locale come Ollama e si vuole testare l'autenticazione prima della distribuzione. Usare il modello sidecar con Docker Compose. Per eseguire il test in locale:

  1. Eseguire l'agente e il sidecar in Docker Compose.
  2. L'agente chiama localhost:7000/token per richiedere un token dal sidecar.
  3. Il sidecar acquisisce un token da Microsoft Entra Agent ID.
  4. Testare il comportamento dell'agente in locale prima della distribuzione.

Per istruzioni dettagliate, vedere Eseguire il sidecar per lo sviluppo locale.

Roadmap generale

Usare la tabella seguente per identificare i passaggi per il modello scelto:

Passaggio Modello Attività
1 Entrambi Configurare l'identità e le autorizzazioni dell'agente in Microsoft Entra.
2 Entrambi Scegliere un modello di integrazione: sidecar o federazione.
3 Sidecar Distribuire l'agente e i contenitori sidecar, quindi eseguire il test in locale.
4 Sidecar Eseguire la distribuzione nell'ambiente di produzione in App contenitore di Azure, Kubernetes o in un'altra piattaforma.
5 Federazione Configurare le credenziali di identità federate in Microsoft Entra.
6 Federazione Distribuire l'agente nella piattaforma di destinazione.

Procedure consigliate per la sicurezza

Quando si integrano agenti di terze parti, seguire questi principi di sicurezza:

  • Non incorporare mai le credenziali nel codice dell'agente. Usare Microsoft Entra Agent ID per acquisire i token in modo dinamico.
  • Usare privilegi minimi. Concedere alle identità dell'agente solo le autorizzazioni necessarie tramite ruoli o ambiti.
  • Convalidare il gruppo di destinatari e l'autorità emittente del token. Verificare sempre che i token provengano dal tenant Microsoft Entra.
  • Cambiare regolarmente le credenziali. Se si usano segreti client, ruotarli in base a una pianificazione. Prendere invece in considerazione le credenziali federate.
  • Monitorare l'utilizzo dei token. Usare Microsoft Entra log per tenere traccia degli agenti che accedono alle API.
  • Mantenere aggiornato Microsoft Entra ID Auth SDK (sidecar). Gli aggiornamenti di sicurezza e compatibilità vengono rilasciati regolarmente.

Risolvere i problemi comuni

Se si verificano problemi durante l'integrazione, usare le indicazioni seguenti per identificare la causa e la risoluzione:

Emetti Causa Soluzione
L'agente non riesce a raggiungere il sidecar Problema di configurazione di rete o sidecar non in esecuzione Verificare che il sidecar sia in esecuzione, controllare DNS e rete e confermare l'associazione di porte. La porta predefinita è 7000.
Sidecar non riesce ad acquisire il token autenticazione Microsoft Entra non riuscita Verificare le credenziali dell'identità dell'agente, controllare le autorizzazioni di Microsoft Entra ed esaminare l'ID tenant e l'ID client.
La richiesta di token restituisce 401 Credenziali di Microsoft Entra non valide o credenziali federate non configurate Verificare che le credenziali siano corrette e verificare che le credenziali dell'identità federata siano configurate se si usa il modello di federazione.
L'API rifiuta il token Il token non dispone dell'ambito o dell'autorizzazione necessari Aggiungere le autorizzazioni API necessarie all'identità dell'agente e richiedere un token con l'ambito corretto.

Contenuti correlati

  • Last updated on