Funzionamento dell'autenticazione della casella degli strumenti in Microsoft Foundry

L'autenticazione della casella degli strumenti in Microsoft Foundry determina la modalità di autenticazione degli strumenti per i servizi downstream. Le impostazioni di autenticazione vengono configurate nelle connessioni di progetto, consentendo agli agenti di usare l'accesso anonimo, le credenziali condivise, le identità del servizio o l'identità di un utente connesso senza implementare la logica di autenticazione nel codice dell'agente.

Questo articolo illustra il funzionamento dell'autenticazione della casella degli strumenti e illustra come configurare il pass-through dell'identità OAuth per un server MCP privato e LQ aziendale mantenendo al tempo stesso le autorizzazioni e i limiti di accesso di ogni utente.

Una casella degli strumenti centralizza l'autenticazione sulla connessione. L'autenticazione è una proprietà della connessione, non il codice nell'agente. Quando si connette uno strumento, si seleziona un tipo di autenticazione e Foundry gestisce l'acquisizione, lo scambio, l'aggiornamento e l'inserimento di token sul lato servizio. Il codice dell'agente rimane incentrato sulla logica di business anziché sui flussi di autenticazione.

Perché l'autenticazione per utente è difficile da creare manualmente

Se implementi tu stesso l'accesso per utente agli strumenti protetti da Entra, ti assumi la responsabilità di meccanismi di base cruciali per la sicurezza, in cui è facile commettere errori difficili da individuare:

  1. Implementa autonomamente l'isolamento dei token per utente. È necessario partizionare correttamente le cache dei token in base all'utente e al tenant. Una chiave di cache errata può trasferire silenziosamente a un altro utente l'accesso di un utente all'API downstream, un bug che supera tutti i test funzionali.
  2. Gestire il consenso e il ciclo di vita per utente, per risorsa. È necessario rilevare errori relativi al consenso, come AADSTS65001, far completare agli utenti il flusso di consenso, aggiornare i token scaduti e gestire correttamente i nuovi tentativi in caso di errori 401/403 per ogni API in ogni agente che scrivi.
  3. Assorbire la complessità che si adatta in modo lineare con strumenti e agenti. Ogni nuovo strumento aggiunge un altro ambito, scambio di token, voce della cache, percorso di consenso, percorso di ripetizione dei tentativi e percorso di intestazione. Man mano che arrivi a gestire centinaia di strumenti e migliaia di agenti, ricostruisci più e più volte la stessa fragile infrastruttura.

Le due identità in ogni chiamata di strumento

Il concetto chiave da tenere a mente è questo: ci sono sempre due identità in gioco, e tutte le difficoltà dell’autenticazione per utente stanno nel mantenerle corrette, separate e senza mai confonderle tra utenti concorrenti.

  • Confine tra agente e toolbox (quello stabile). L'agente esegue l'autenticazione alla piattaforma con la propria identità agente. Questa identità consente di accedere alla casella degli strumenti stessa, non ai singoli strumenti al suo interno.
  • Confine tra strumento e dati (quello per utente). Per la chiamata dati effettiva, Foundry fornisce al servizio downstream credenziali che rappresentano l'utente connesso. A seconda del tipo di autenticazione, tali credenziali provengono da un flusso di autorizzazione OAuth o da un token di accesso specifico del gruppo di destinatari Microsoft Entra. Il servizio downstream restituisce solo ciò che l'utente può accedere e rispetta le autorizzazioni e le etichette di riservatezza.

Modalità di gestione dell'autenticazione da parte di una casella degli strumenti

Una toolbox sposta l'intero onere dell'autenticazione dal tuo agente alla connessione:

  • L'autenticazione risiede nella connessione, non nell'agente. Quando si connette uno strumento, si sceglie un tipo di autenticazione una sola volta. Il codice dell'agente rimane senza autenticazione.
  • Foundry gestisce l'intero flusso. A seconda delle esigenze di uno strumento, Foundry archivia e inserisce chiavi API, ottiene le credenziali per le identità del servizio, completa l'autorizzazione OAuth o fornisce un token di accesso specifico del gruppo di destinatari Microsoft Entra. Foundry isola le credenziali per utente da altri utenti.
  • È sufficiente creare la logica di business. Non spettava mai a te sviluppare il flusso di autenticazione.
L'onere del diy Che cosa fa invece una cassetta degli attrezzi
Isolamento dei token per utente Foundry isola automaticamente i token per ogni chiamante. Non c'è alcuna chiave di cache da impostare in modo errato.
Gestione del consenso e del ciclo di vita, per utente e per risorsa Foundry gestisce il flusso di consenso e il ciclo di vita dei token per ogni utente, inclusa l'acquisizione e l'aggiornamento dei token dopo che è stato concesso il consenso richiesto.
Autenticazione reimplementata per strumento e per team Crei una toolbox con i relativi strumenti e l’autenticazione una sola volta, quindi la riutilizzi in ogni agente e runtime.

Impostare il tipo di autenticazione nella connessione

È possibile scegliere il tipo di autenticazione quando si crea la connessione, nel portale, con l'interfaccia della riga di comando per sviluppatori Azure o tramite l'API REST. Mai nel codice dell'agente. Ogni tipo di autenticazione determina quale identità viene trasmessa allo strumento:

authType La cui identità raggiunge lo strumento Usalo per
none Anonimo Server pubblici, ad esempio il server MCP di Learn Microsoft.
custom-keys Una chiave o un'intestazione API archiviata SaaS basato su chiave. L'agente non vede mai il segreto.
project-managed-identity Identità gestita del progetto Chiamate da servizio a servizio senza contesto utente.
agentic-identity Identità dell'agente Controllo per agente e privilegio minimo.
oauth2 L'utente che completa l'autorizzazione OAuth Servizi compatibili con OAuth, inclusi Work IQ e i server MCP partner (ad esempio, Vercel).
user-entra-token L'utente Microsoft Entra connesso Servizi Microsoft gestiti che richiedono un token Entra specifico per il destinatario, ad esempio gli endpoint privati dell'agente dati di Fabric dell'area di lavoro.

Sia oauth2 che user-entra-token supportano l'accesso per utente, ma ottengono credenziali in modo diverso. Con oauth2, l'utente completa un flusso di autorizzazione OAuth e Foundry archivia e aggiorna le credenziali risultanti. Con user-entra-token, Foundry fornisce al servizio downstream un token di accesso specifico del gruppo di destinatari Microsoft Entra che rappresenta l'utente connesso. Usare il tipo di autenticazione richiesto dal servizio.

Configurare una connessione per ogni tipo di autenticazione

Registrare ogni connessione con azd ai connection create. La forma del comando è sempre la stessa; I flag differiscono per tipo di autenticazione. Usare --kind remote-tool per i server MCP e A2A.

azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://public-mcp.example.com/mcp \
  --auth-type none

Procedura dettagliata: passaggio dell'identità OAuth

Questo esempio collega due strumenti protetti da Microsoft Entra per l'accesso per singolo utente: un server MCP privato per gli ordini e Work IQ. Entrambi usano il pass-through dell'identità OAuth, quindi ogni chiamata downstream viene eseguita come utente che autorizza la connessione.

1. Creare una connessione per ogni strumento

# Private orders MCP: OAuth identity passthrough
azd ai connection create orders-mcp \
  --kind remote-tool \
  --target https://orders-mcp.example.com/mcp \
  --auth-type oauth2 \
  --authorization-url https://auth.example.com/authorize \
  --token-url https://auth.example.com/token \
  --client-id <oauth-client-id> \
  --client-secret <oauth-client-secret> \
  --scopes "openid offline_access orders.read"

# Work IQ: OAuth identity passthrough
azd ai connection create workiq-conn \
  --kind remote-a2a \
  --target https://workiq.svc.cloud.microsoft/a2a/ \
  --auth-type oauth2 \
  --authorization-url https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize \
  --token-url https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token \
  --client-id <oauth-client-id> \
  --client-secret <oauth-client-secret> \
  --scopes "api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask offline_access"

2. Aggiungere entrambi gli strumenti a una casella degli strumenti

Ogni strumento fa riferimento alla connessione in base all'ID. Tale singolo riferimento è l'intera differenza tra l'esecuzione come account del servizio condiviso e l'azione per conto dell'utente connesso. L'agente non richiede un broker di token o una cache dei token per utente.

Questo esempio richiede azure-ai-projects (Python) o @azure/ai-projects (TypeScript) versione 2.3.0 o successiva.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPToolboxTool, WorkIQPreviewToolboxTool

endpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>"
project = AIProjectClient(endpoint=endpoint, credential=DefaultAzureCredential())
orders_connection = project.connections.get("orders-mcp")
workiq_connection = project.connections.get("workiq-conn")

toolbox_version = project.toolboxes.create_version(
    name="employee-toolbox",
    description="Private orders MCP + Work IQ, both via OAuth identity passthrough.",
    tools=[
        MCPToolboxTool(
            server_label="orders",
            server_url="https://orders-mcp.example.com/mcp",
            require_approval="never",
            project_connection_id=orders_connection.id,
        ),
        WorkIQPreviewToolboxTool(project_connection_id=workiq_connection.id),
    ],
)
print(f"Created toolbox: {toolbox_version.name}, version: {toolbox_version.version}")

Per JavaScript, consulta l'esempio aggiornato di connessione al progetto Toolbox e l'esempio Work IQ. Il primo esempio crea una casella degli strumenti supportata da MCP che usa una connessione di progetto e la collega a un agente. Il secondo esempio mostra come fare riferimento alla connessione al progetto IQ di lavoro.

3. Connettere l'agente alla casella degli strumenti

L'agente si connette al singolo endpoint consumer della casella degli strumenti, che serve sempre la versione predefinita. L'agente esegue l'autenticazione alla piattaforma con la propria identità. Per ogni strumento, Foundry fornisce le credenziali che rappresentano l'utente che ha completato l'autorizzazione OAuth. L'agente non include alcun codice di autenticazione specifico per ciascuno strumento.

from azure.identity import DefaultAzureCredential
from agent_framework import FoundryToolbox

# Agent-to-toolbox identity: the agent's own credential, scoped to the platform
credential = DefaultAzureCredential()
, timeout=120.0)

# Consumer endpoint always resolves to the toolbox's default version
CONSUMER_URL = f"{endpoint}/toolboxes/employee-toolbox/mcp?api-version=v1"

toolbox = FoundryToolbox(
    name="employee_toolbox",
    url=CONSUMER_URL,
    http_client=http_client,
    load_prompts=False,
)

agent = chat_client.as_agent(
    name="employee-agent",
    instructions="Help employees with their orders and Microsoft 365 context.",
    tools=[toolbox],
)

Foundry genera un collegamento di consenso la prima volta che un determinato utente deve autorizzare uno strumento. Dopo il consenso, le chiamate successive usano le credenziali dell'utente. L'utente potrebbe dover autorizzare nuovamente lo strumento se il token di aggiornamento scade o viene revocato.

Note

Gli utenti di un agente che usa l'inoltro dell'identità OAuth devono disporre almeno del ruolo Foundry Agent Consumer nel progetto. Il tenant Microsoft Entra dell'utente deve corrispondere al tenant del progetto Foundry. Lo scambio di token tra tenant non è supportato.

Oltre al pass-through: cos'altro ti offre una toolbox

Poiché il traffico degli strumenti e l'autenticazione passano attraverso la casella degli strumenti, è possibile ottenere più di una gestione pulita delle identità:

  • Misure di protezione per l'IA responsabile. Le protezioni controllano gli input e gli output di ogni strumento, quindi una risposta MCP non attendibile non può introdurre nell’agente attacchi di prompt injection o contenuti non sicuri.
  • Gateway IA personalizzato Metti i tuoi server MCP dietro Gestione API di Azure (APIM) per la limitazione della frequenza, il logging e i criteri di rete.
  • Controllo delle versioni. Crea e testa una nuova versione della toolbox, quindi impostala come predefinita. Ogni agente che punta all'endpoint consumer preleva automaticamente la versione alzata di livello, senza modifiche al codice.

Contenuti correlati

  • Last updated on