Configurare l'autenticazione OAuth 2.0

Suggerimento

Consigliato: Inizia con Work IQ Dev Tools per scenari di agenti dichiarativi e plug-in pro-code supportati. Vedere la guida introduttiva di WIQD. Le istruzioni basate su toolkit rimangono disponibili per i progetti e i flussi di lavoro esistenti che le richiedono. Controlla il supporto per le funzionalità e l'esperienza di destinazione prima di scegliere uno strumento: WIQD non si rivolge agli agenti del motore personalizzato.

Un plug-in può accedere a un server o a un'API MCP (Model Context Protocol) usando un token di connessione ottenuto tramite il flusso del codice di autorizzazione OAuth 2.0, con il supporto PKCE (Proof Key for Code Exchange) abilitato per impostazione predefinita. In questo flusso, Microsoft 365 Copilot apre l'esperienza di accesso, il provider OAuth restituisce una risposta di autorizzazione a Microsoft Teams e Teams scambia il codice di autorizzazione con i token.

Questo articolo utilizza i plug-in MCP come procedura predefinita per la procedura dettagliata. Gli stessi passaggi si applicano ai plug-in API compilati da un documento OpenAPI, tranne dove specificato.

Configurare l'autenticazione OAuth 2.0 in tre passaggi: registrare un client OAuth con il provider di identità, configurare l'URI di reindirizzamento e creare la configurazione OAuth 2.0.

Passaggio 1: registra un client OAuth con il provider di identità

Registrare un'app con il provider OAuth 2.0 (provider di identità) per ottenere un ID client e, per un client (Web) riservato, un segreto client. Specificare questi valori quando si crea la configurazione OAuth 2.0 nel passaggio 3.

Per un server MCP che richiede l'autorizzazione, impostare la type proprietà dell'oggetto di autenticazione runtime su OAuthPluginVault. None e ApiKeyPluginVault non si applicano a un server MCP che richiede l'autorizzazione. Nel manifesto viene archiviato solo l'ID di configurazione di autenticazione: non viene scritto alcun ID client, segreto client o token. Per registrare il client in modo dinamico anziché statico, mantieni type come OAuthPluginVault e crea la configurazione di autenticazione tramite la registrazione dinamica del client (DCR), che non è disponibile per un server protetto da Microsoft Entra ID.

Nota

Questi valori si applicano al manifesto del plug-in MCP per le azioni dell'agente dichiarativo. Se invece configuri il server MCP remoto di un plug-in tramite agentConnectors il manifesto dell'app Microsoft 365, usa OAuthPluginVault o, per un server che supporta DCR, DynamicClientRegistration. Anche gli schemi di manifesto dell'app 1.29 e 1.30 includono AzureKeyVault, ma l'accettazione dello schema non stabilisce il supporto nell'esperienza di destinazione. Per i requisiti di configurazione e host, vedere Configurare server MCP remoti per i plug-in di Microsoft 365 Copilot.

Passaggio 2: configurare l'URI di reindirizzamento

Aggiungere l'URI di reindirizzamento seguente (denominato anche URL di callback di autorizzazione) alla registrazione del provider OAuth:

https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect

URL a cui il provider OAuth invia la risposta di autorizzazione dopo l'accesso di un utente. Teams riceve la risposta a questo URL di callback e scambia il codice di autorizzazione con i token. Se non si registra questo URI di reindirizzamento con il provider, l'accesso non riuscirà. L'URI di reindirizzamento è lo stesso per ogni plug-in e provider: non viene personalizzato per ogni app.

Passaggio 3: Creare la configurazione di autenticazione OAuth 2.0

L'autenticazione OAuth 2.0 si basa su una configurazione di autenticazione (auth config), un record archiviato nell'archivio token Microsoft Enterprise usato da Microsoft 365 Copilot per ottenere e aggiornare i token per il plug-in MCP. Iniziare con WIQD per un progetto pro-code supportato. Le procedure Toolkit, Competenze per sviluppatori e Portale per sviluppatori di Teams rimangono disponibili come alternative.

Comunque lo si crei, la configurazione di autenticazione ha un ID di configurazione di autenticazione a cui fa riferimento il manifesto del plug-in.

Per un'azione MCP, utilizzare wiqd agent add action con --mcp-server-url e --mcp-auth-type oauth. Fornisci i dettagli del cliente registrato tramite --mcp-client-id, --mcp-client-secret quando richiesto, e --mcp-scopes. Per un'azione OpenAPI, usare --openapi-auth-identity-provider oauth e le opzioni , --openapi-auth-client-id--openapi-auth-client-secret, e --openapi-auth-scopes corrispondenti. Abilitare PKCE per la route OpenAPI quando --openapi-auth-pkce il provider lo supporta. Vedere la guida ai comandi per l'azione WIQD.

Per un manifesto di plug-in esistente, utilizzare wiqd agent add auth con --plugin-manifest, --auth-namee --auth-type oauth. Usare l'endpoint OAuth, l'ambito e le opzioni client di quel comando; la sua opzione PKCE è --oauth-pkce. Completare il flusso di lavoro di provisioning del progetto per l'ambiente. Per la registrazione automatica del client anziché OAuth statico, seguire la route DCR WIQD.

Usare Microsoft 365 Agents Toolkit

Quando crei un agente con un plug-in MCP (se il server richiede l'autenticazione) o crei un plug-in API da un documento OpenAPI esistente in Microsoft 365 Agents Toolkit, il toolkit richiede l'ID client OAuth, il segreto client e gli ambiti. Agents Toolkit recupera gli endpoint di autorizzazione, token e aggiornamento dall'endpoint noto del server MCP (o dal documento OpenAPI per i plug-in API), crea la configurazione di autenticazione nell'archivio token Enterprise e aggiorna automaticamente l'oggetto di autenticazione runtime nel manifesto del plug-in.

Nota

Per i plug-in API, devi definire la securitySchemes proprietà nel documento OpenAPI in modo che Agents Toolkit possa leggere i dettagli OAuth. Per altre informazioni, vedere OAuth 2.0.

securitySchemes:
  OAuth2:
    type: oauth2
    flows:
      authorizationCode:
        authorizationUrl: <authorization_url>
        tokenUrl: <token_url>
        refreshUrl: <refresh_url>
        scopes:
          scope: description

PKCE è abilitato per impostazione predefinita, poiché molte organizzazioni bloccano i segreti client. Impostato isPKCEEnabled su false in m365agents.yml nel progetto agente prima di eseguire il provisioning dell'agente solo quando il provider OAuth non supporta PKCE.

isPKCEEnabled: false

Per evitare completamente i segreti del client, registrare un client pubblico con il provider - una piattaforma applicativa a pagina singola anziché una piattaforma Web - e lasciare che PKCE protegga lo scambio di codice.

Usare la competenza per lo sviluppo dell'agente dichiarativo

La declarative agent developer skill (declarative-agent-developer) è una skill dell'agente in Microsoft Work IQ che racchiude le conoscenze necessarie per creare agenti dichiarativi. Invece di eseguire comandi o modificare i manifesti manualmente, descrivi cosa vuoi Copilot o l'interfaccia della riga di comando di GitHub in linguaggio naturale e la competenza esegue lo scaffolding dell'agente dichiarativo, aggiunge il plug-in MCP e gestisce automaticamente la configurazione dell'autenticazione. La skill supporta solo plug-in MCP. Per OAuth 2.0, supporta sia la registrazione statica che la registrazione dinamica del client (DCR): crea la configurazione di autenticazione nell'archivio token Enterprise e aggiorna il manifesto del plug-in senza passaggi manuali.

Suggerimento

Per una procedura dettagliata sull'utilizzo della competenza per gli sviluppatori di agenti dichiarativi, vedere Creare agenti dichiarativi con la competenza per gli sviluppatori di agenti dichiarativi.

Usare il portale per sviluppatori di Teams

La registrazione al portale per sviluppatori di Teams è facoltativa se si usa Agents Toolkit o la competenza per sviluppatori di agenti dichiarativi. Usalo quando vuoi creare manualmente la configurazione di autenticazione o, più comunemente, per gestire una configurazione di autenticazione già creata da Agents Toolkit o dalla skill. Nel portale è possibile limitare la configurazione dell'autenticazione a un'app di Teams specifica o a un'organizzazione di Microsoft 365 e modificare altre proprietà.

La registrazione del client OAuth nel portale per sviluppatori di Teams connette la configurazione del plug-in dell'agente alla registrazione del provider OAuth che rilascia token per il server o l'API MCP. I valori in questa registrazione devono corrispondere al provider OAuth, al manifesto del plug-in e all'endpoint dell'API protetto. URL di base, restrizioni delle app o ID di configurazione di autenticazione non corrispondenti possono impedire agli utenti di accedere o bloccare lo scambio di token.

Avviso

Limitare la registrazione a qualsiasi app di Teams. Una registrazione limitata a una specifica app Teams è associata a tale ID app Teams. Microsoft 365 Copilot non risolve tale ID quando chiama un server MCP, quindi il provisioning viene completato correttamente e quindi ogni chiamata allo strumento restituisce un 404 errore.

  1. Aprire il portale per sviluppatori di Teams. Selezionare Strumenti ->Registrazione client OAuth.

  2. Se non hai registrazioni esistenti, seleziona Registra client. Se sono presenti registrazioni esistenti, selezionare Nuova registrazione del client OAuth.

  3. Compila i seguenti campi.

    • Nome di registrazione: un nome descrittivo per la registrazione.
    • URL di base: URL di base dell'API. Questo valore deve corrispondere all'URL url nella proprietà dell'oggetto spec del server MCP nel manifesto del plug-in per i plug-in basati su MCP o a una voce nell'arrayservers nel documento OpenAPI per i plug-in API.
    • Limitare l'utilizzo per organizzazione: selezionare le organizzazioni di Microsoft 365 che possono usare questa registrazione OAuth per accedere agli endpoint API. Usare l'organizzazione solo per lo sviluppo o il test in un tenant. Usare qualsiasi organizzazione di Microsoft 365 quando il plug-in deve funzionare tra tenant.
    • Limitare l'utilizzo in base all'app: selezionare un'app di Teams. Non associare la registrazione all'ID app di Teams esistente per un server MCP. Se invece esegui il provisioning della configurazione di autenticazione con Microsoft 365 Agents Toolkit, l'impostazione equivalente nell'azione oauth/register in m365agents.yml è applicableToApps: AnyApp. Mantenere il campo in tale azione anche se AnyApp lo rende inerte, perché il driver di provisioning esegue appId la convalida incondizionatamente e la rimozione interrompe il appId provisioning.
    • ID client: ID client o ID applicazione emesso dal provider OAuth 2.0.
    • Segreto client: segreto client emesso dal provider OAuth 2.0.
    • Endpoint di autorizzazione: URL del provider OAuth 2.0 usato dalle app per richiedere un codice di autorizzazione.
    • Endpoint token: URL del provider OAuth 2.0 usato dalle app per riscattare un codice per un token di accesso.
    • Endpoint aggiornamento: URL del provider OAuth 2.0 usato dalle app per aggiornare il token di accesso.
    • Ambito: le autorizzazioni richieste dal plug-in al provider OAuth. Usa i valori di ambito richiesti dal provider e dall'API. Se il provider usa Microsoft Identity Platform e il plug-in richiede token di aggiornamento, includerli offline_access in eventuali ambiti delegati specifici dell'API.
    • Abilita chiave di prova per lo scambio di codice (PKCE): lascia abilitata questa impostazione. È attivo per impostazione predefinita; disabilitarlo solo se il provider OAuth non supporta PKCE.
  4. Selezionare Salva.

  5. Il completamento della registrazione crea la configurazione di autenticazione e genera un ID di configurazione di autenticazione (attualmente denominato ID di registrazione del client OAuth nel portale per sviluppatori di Teams).

Aggiungere l'ID di configurazione dell'autenticazione al manifesto del plug-in

Quando si crea manualmente la configurazione dell'autenticazione nel portale per sviluppatori di Teams, impostare la type proprietà dell'oggetto di autenticazione di runtime su OAuthPluginVaulte quindi reference_id sull'ID di configurazione dell'autenticazione. Agents Toolkit e la capacità di sviluppatore agente dichiarativo fanno tutto questo per te.

"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "auth config ID"
},

Considerazioni su Microsoft Entra ID

Quando si protegge il server MCP utilizzando Microsoft Entra ID, si applicano tre vincoli che non è possibile aggirare con gli strumenti.

  • La registrazione dinamica del client non è disponibile. Microsoft Entra ID non pubblica un endpoint di registrazione RFC 7591, quindi la registrazione dinamica del client non ha nulla da registrare. Registrare il client OAuth in modo statico seguendo la procedura descritta in questo articolo.
  • Per il agentConnectors nodo non è presente alcun tipo di autorizzazione Microsoft Entra. A differenza di composeExtensions, il agentConnectors nodo nel manifesto dell'app Microsoft 365 non ha alcun microsoftEntra tipo di autorizzazione. Un server MCP protetto da Microsoft Entra ID ha sempre bisogno di un'app in cui ti registri tu stesso in Microsoft Entra ID, oltre a una configurazione di autenticazione OAuth, anche quando il server fronteggia un'API Microsoft proprietaria.
  • Il consenso dell'ambito non viene verificato durante il provisioning. Il provisioning non controlla se l'ambito richiesto può essere consentito. Un ambito che non può essere approvato correttamente ai provisioning, quindi ha esito negativo in un secondo momento con l'approvazione dell'amministratore necessario, e l'app delle risorse può essere invisibile sia all'utente che all'amministratore del tenant. Verificare che un amministratore abbia acconsentito all'ambito prima del provisioning.

Gestire la configurazione di autenticazione

L'azione oauth/register in m365agents.yml crea solo una configurazione di autenticazione o salta la creazione - non riscrive mai un record esistente.

  • Se configurationId ha già un valore, l'azione non esegue alcuna operazione.
  • Se configurationId punta a una registrazione eliminata, l'azione mostra un avviso e non esegue alcuna operazione.
  • Per modificare i valori in una registrazione esistente, usare l'azione oauth/update .
  • Per eliminare una registrazione, usare il portale per sviluppatori di Teams. È l'unico posto in cui puoi eliminarne uno.

Disconnettersi

Nota

Gli utenti possono disconnettersi da un agente dalle impostazioni> di ChatAgenti in Microsoft 365 Copilot. Questa azione cancella il token OAuth archiviato.