Configurare l'autenticazione per gli strumenti MCP (Model Context Protocol)

La maggior parte dei server MCP (Model Context Protocol) richiede l'autenticazione per accedere al server e al servizio sottostante. L'autenticazione corretta garantisce che gli agenti possano connettersi in modo sicuro ai server MCP, richiamare i propri strumenti e accedere alle risorse protette mantenendo al contempo i controlli di accesso appropriati.

In questo articolo, tu:

Prerequisiti

Prima di iniziare, è necessario:

• Accedere al Portale Foundry e a un progetto. Se non ne hai uno, consulta Creare progetti in Foundry.
• Autorizzazioni per creare connessioni di progetto e configurare gli agenti. Per informazioni dettagliate, vedere Controllo degli accessi in base al ruolo nel portale foundry.
• URL dell'endpoint server MCP remoto a cui connettersi.
• Credenziali per il metodo di autenticazione selezionato:
  • Autenticazione basata su chiave: una chiave API, un token di accesso personale (PAT) o un altro token.
  • Microsoft Entra autenticazione: assegnazioni di ruolo per l'identità dell'agente o l'identità gestita del progetto nel servizio sottostante.
  • Passaggio dell'identità OAuth: configurazione OAuth gestita o registrazione dell'applicazione OAuth (OAuth personalizzata).

Scegliere un metodo di autenticazione

In generale, esistono due scenari di autenticazione:

• Autenticazione condivisa: ogni utente dell'agente usa la stessa identità per l'autenticazione nel server MCP. Il contesto utente non persiste.
• Autenticazione singola: ogni utente esegue l'autenticazione con il proprio account in modo che il contesto utente venga mantenuto.

Usare le indicazioni seguenti per scegliere un metodo:

Metodi di autenticazione supportati

Autenticazione basata su chiave

Usare l'autenticazione basata su chiave quando il server MCP richiede una chiave API, un token di accesso personale o credenziali simili e non è necessario mantenere il contesto utente singolo.

Passare una chiave API, un token di accesso personale (PAT) o altre credenziali ai server MCP che supportano l'autenticazione basata su chiave. Per una maggiore sicurezza, archiviare le credenziali condivise in una connessione di progetto anziché passarle in fase di esecuzione.

Quando si connette un server MCP a un agente nel portale foundry, Foundry crea automaticamente una connessione al progetto. Specificare il nome delle credenziali e il valore delle credenziali. Ad esempio, se ci si connette al server MCP GitHub, è possibile specificare:

• Nome credenziale: Authorization
• Valore credenziale: Bearer <your-personal-access-token>

Quando l'agente richiama il server MCP, Agent Service recupera le credenziali dalla connessione al progetto e le passa al server MCP.

Per la sicurezza:

• Usare le credenziali con privilegi minimi, se possibile.
• Ruotate regolarmente i token.
• Limitare l'accesso ai progetti che contengono segreti condivisi.

autenticazione Microsoft Entra

Usare l'autenticazione Microsoft Entra quando il server MCP (e il servizio correlato sottostante) supporta i token Microsoft Entra. Questo metodo elimina la necessità di gestire i segreti e fornisce la rotazione automatica dei token.

Usare l'autenticazione dell'identità dell'agente (anteprima)

Usare l'identità dell'agente quando si desidera che l'autenticazione sia limitata a un agente specifico. Questo approccio è ideale quando si dispone di più agenti che necessitano di diversi livelli di accesso allo stesso server MCP.

Usare l'identità dell'agente per eseguire l'autenticazione con i server MCP che supportano l'autenticazione dell'identità dell'agente. Se si crea l'agente usando il servizio Agent, si assegna automaticamente un'identità dell'agente.

Prima della pubblicazione, tutti gli agenti nel progetto Foundry condividono la stessa identità dell'agente. Dopo la pubblicazione di un agente, l'agente ottiene un'identità univoca.

Assicurarsi che l'identità dell'agente disponga delle assegnazioni di ruolo necessarie nel servizio sottostante che supporta il server MCP.

Quando l'agente richiama il server MCP, Agent Service usa l'identità dell'agente disponibile per richiedere un token di autorizzazione e passarlo al server MCP.

Utilizzare l'autenticazione dell'identità gestita del progetto

Usare l'identità gestita del progetto quando si vuole che tutti gli agenti in un progetto convidano lo stesso livello di accesso o quando il server MCP richiede un'identità gestita anziché un'identità dell'agente.

Usare l'identità gestita del progetto Foundry per eseguire l'autenticazione con i server MCP che supportano l'autenticazione dell'identità gestita.

Assicurarsi che l'identità gestita del progetto disponga delle assegnazioni di ruolo necessarie nel servizio sottostante che supporta il server MCP.

Quando l'agente richiama il server MCP, Agent Service usa l'identità gestita del progetto per richiedere un token di autorizzazione e passarlo al server MCP.

Trasmissione diretta dell'identità OAuth

Il pass-through dell'identità OAuth è disponibile per l'autenticazione a server MCP Microsoft e non-Microsoft e ai servizi sottostanti conformi a OAuth, inclusi Microsoft Entra.

Usare il pass-through dell'identità OAuth per richiedere agli utenti che interagiscono con l'agente di accedere al server MCP e al servizio sottostante. Il servizio Agent archivia in modo sicuro le credenziali dell'utente e le usa solo all'interno del contesto dell'agente che comunica con il server MCP.

Quando si usa il pass-through dell'identità OAuth, il servizio Agent genera un collegamento di consenso la prima volta che un determinato utente deve autorizzare l'accesso. Dopo l'accesso e il consenso dell'utente, l'agente può individuare e richiamare gli strumenti nel server MCP con le credenziali dell'utente.

Il servizio Agent supporta due opzioni OAuth: OAuth gestite e OAuth personalizzate.

• Con OAuth gestito, Microsoft o l'autore del server MCP gestisce l'app OAuth.
• Con OAuth personalizzato, puoi portare la tua registrazione dell'app OAuth.

Quando si configura OAuth personalizzato, specificare le informazioni seguenti:

• ID client: obbligatorio
• Segreto client: facoltativo (dipende dall'app OAuth)
• URL di autenticazione: obbligatorio
• URL di aggiornamento: obbligatorio (se non si dispone di un URL di aggiornamento separato, è possibile usare invece l'URL del token)
• URL del token: obbligatorio
• Ambiti: facoltativo

Flow using OAuth identity passthrough (Flusso tramite pass-through dell'identità OAuth)

L'ambito di OAuth è specifico al nome dello strumento (connessione) per progetto Foundry. A ogni nuovo utente che usa un nuovo strumento (connessione) in un progetto Foundry viene richiesto di fornire il consenso.

• Quando un utente tenta per la prima volta di usare un nuovo strumento in un progetto Foundry, l'output della risposta condivide il collegamento di consenso in response.output_item. È possibile trovare il collegamento di consenso nel tipo di elemento oauth_consent_request, in consent_link. Mostra questo collegamento di consenso all'utente.

  "type":"response.output_item.done",
  "sequence_number":7,
  "output_index":1,
  "item":{
      "type":"oauth_consent_request",
      "id":"oauthreq_10b0f026610e2b76006981547b53d48190840179e52f39a0aa",
      "created_by":{},
      "consent_link":"https://logic-swedencentral-001.consent.azure-apihub.net/login?data=xxxx"
  }
  

  Esempio:

• All'utente viene richiesto di accedere e fornire il consenso dopo aver esaminato l'accesso necessario. Dopo aver fornito il consenso, l'utente visualizza una finestra di dialogo simile all'esempio seguente:

• Dopo che l'utente ha chiuso la finestra di dialogo, è necessario inviare un'altra risposta con l'ID risposta precedente

  # Requires: azure-ai-projects >= 2.0.0
  from azure.ai.projects import AIProjectClient
  from azure.identity import DefaultAzureCredential
  
  # Submit another response after user consent
  response = client.responses.create(
       previous_response_id="YOUR_PREVIOUS_RESPONSE_ID",
       input=user_input,
       extra_body={
           "agent_reference": {"name": agent.name, "type": "agent_reference"},
           "tool_choice": "required",
           "stream": True
       },
  )
  

Una volta che l'utente ha eseguito l'accesso e dato il consenso una volta, non è necessario fornire il consenso in futuro.

Registrazione dell'app Bring Your Own Microsoft Entra

Per usare il pass-through di identità con i servizi Microsoft, porta la tua registrazione dell'app Microsoft Entra. Portando la registrazione dell'app Microsoft Entra personalizzata, è possibile controllare le autorizzazioni concesse.

La procedura seguente usa il server MCP Agent 365 come esempio:

1. Seguire la guida alla registrazione di app per creare un'app Microsoft Entra e ottenere l'ID client e il segreto client.

2. Concedere autorizzazioni scoped all'app Microsoft Entra.

   Per i server MCP di Agent 365, passare a Gestisci>Autorizzazioni API e cercare Agent 365 Tools. Se non è possibile trovarlo, cercare ea9ffc3e-8a23-4a7d-836d-234d7c7565c1. Assegnare le autorizzazioni necessarie e concedere il consenso amministratore per il tenant.

   Di seguito sono riportate le autorizzazioni per ogni server MCP:

   • Server MCP di Microsoft Outlook Mail (Frontier): McpServers.Mail.All
   • Server di Microsoft Outlook Calendar MCP (Frontier): McpServers.Calendar.All
   • Microsoft Teams MCP Server (Frontier): McpServers.Teams.All
   • Server MCP del Profilo Utente Microsoft 365 (Frontier): McpServers.Me.All
   • Microsoft SharePoint e OneDrive MCP Server (Frontier): McpServers.OneDriveSharepoint.All
   • Microsoft SharePoint Elenco MCP Server (Frontiera): McpServers.SharepointLists.All
   • Microsoft Word MCP Server (Frontier): McpServers.Word.All
   • MCP Server Microsoft 365 Copilot (Search) (Frontier): McpServers.CopilotMCP.All
   • Amministrazione Microsoft 365 Center MCP Server (Frontier): McpServers.M365Admin.All
   • Microsoft Dataverse MCP Server (Frontier): McpServers.Dataverse.All

3. Tornare al portale di Foundry e configurare il server MCP. Connettere uno strumento, passare a Personalizzato e quindi selezionare MCP. Specificare un nome e un endpoint server MCP e quindi selezionare Pass-through dell'identità OAuth:

   • ID del cliente e segreto del cliente
   • URL del token: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
   • URL di autenticazione: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
   • URL di aggiornamento: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
   • Ambiti: ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/{permission above}

4. Dopo aver completato la configurazione, si riceve un URL di reindirizzamento. Aggiungilo alla tua app Microsoft Entra.

Accesso non autenticato

Usare l'accesso non autenticato solo quando il server MCP non richiede l'autenticazione. Questo metodo è appropriato per i server MCP pubblici che forniscono l'accesso aperto ai relativi strumenti o per i server MCP privati all'interno della rete virtuale che si basano sull'isolamento a livello di rete anziché sull'autenticazione esplicita.

Configurare l'autenticazione per un server MCP

1. Identificare il server MCP remoto a cui connettersi.

2. Creare o selezionare una connessione di progetto che archivia l'endpoint server MCP, il tipo di autenticazione e le credenziali necessarie.

   Se si connette il server MCP nel portale foundry, il portale crea automaticamente la connessione al progetto.

3. Creare o aggiornare un agente con uno mcp strumento con le informazioni seguenti:

   1. server_url: URL del server MCP. Ad esempio, https://api.githubcopilot.com/mcp/.
   2. server_label: identificatore univoco del server MCP per l'agente. Ad esempio, github.
   3. require_approval: facoltativamente determinare se è necessaria l'approvazione. I valori supportati sono:
      • always: uno sviluppatore deve fornire l'approvazione per ogni chiamata. Se non si specifica un valore, questo valore è l'impostazione predefinita.
      • never: non è necessaria alcuna approvazione.
      • {"never":[<tool_name_1>, <tool_name_2>]}: viene fornito un elenco di strumenti che non richiedono l'approvazione.
      • {"always":[<tool_name_1>, <tool_name_2>]}: viene fornito un elenco di strumenti che richiedono l'approvazione.
   4. project_connection_id: nome della connessione in cui sono archiviati l'endpoint server MCP, la selezione dell'autenticazione e le informazioni pertinenti. Nella connessione, se si specificano endpoint diversi rispetto a server_url, viene utilizzato l'endpoint nella connessione.

4. Eseguire l'agente.

5. Se il modello tenta di richiamare uno strumento nel server MCP con l'approvazione richiesta o l'utente deve accedere per il pass-through dell'identità OAuth, esaminare l'output della risposta:

   • Link di consenso: oauth_consent_request
   • Richiesta di approvazione: mcp_approval_request

   Dopo l'accesso dell'utente o l'approvazione della chiamata, inviare un'altra risposta per continuare.

Convalidare

Dopo aver configurato l'autenticazione, verificare che la connessione funzioni correttamente:

1. Attivare una chiamata allo strumento MCP dall'agente inviando un prompt che fa sì che l'agente usi uno degli strumenti del server MCP.
2. Verificare che la chiamata allo strumento venga completata correttamente. L'output dello strumento dovrebbe essere visualizzato nella risposta dell'agente senza errori di autenticazione.
3. Se stai utilizzando il pass-through dell'identità OAuth:
   • Verificare che un nuovo utente riceva un collegamento di consenso (oauth_consent_request nella risposta).
   • Dopo il consenso dell'utente, verificare che le chiamate successive dello strumento abbiano esito positivo senza richiedere di nuovo il consenso.
   • Eseguire il test con un utente diverso per verificare che il flusso di consenso per utente funzioni correttamente.

Risoluzione dei problemi

Ospitare un server MCP locale

Se è stato sviluppato un server MCP personalizzato o si vuole usare un server MCP open source che viene eseguito in locale, è necessario ospitarlo nel cloud prima di connetterlo al servizio Agent.

Il runtime del servizio Agent accetta solo un endpoint server MCP remoto. Per aggiungere strumenti da un server MCP locale, è necessario ospitarlo in modalità self-host in App contenitore di Azure o Funzioni di Azure per ottenere un endpoint server MCP remoto.

L'endpoint remoto può essere un endpoint pubblico o un endpoint privato all'interno della rete virtuale. Per i server MCP privati, distribuire l'applicazione container con accesso solo interno su una subnet MCP dedicata delegata a Microsoft.App/environments. Per iniziare, usare il modello 19-hybrid-private-resources-agent-setup . Per informazioni dettagliate sul supporto degli strumenti negli ambienti isolati dalla rete, vedere Strumenti di Agent con isolamento di rete.

Quando si tenta di ospitare server MCP locali nel cloud, tenere presente quanto segue:

Passaggi successivi

• Connettersi ai server del Model Context Protocol
• Configurare la rete privata per il Foundry Agent Service
• Concetti relativi all'identità dell'agente in Foundry
• Controllo degli accessi in base al ruolo nel portale foundry
• Aggiungere una connessione in Foundry