OAuth 2.0-Authentifizierung konfigurieren

Ein Plug-In kann auf einen MCP-Server (Model Context Protocol) oder eine API zugreifen, indem es ein Bearertoken verwendet, das über den OAuth 2.0-Autorisierungscodefluss abgerufen wurde, wobei die PKCE-Unterstützung (Proof Key for Code Exchange) standardmäßig aktiviert ist. In diesem Flow öffnet Microsoft 365 Copilot die Anmeldeerfahrung, der OAuth-Anbieter gibt eine Autorisierungsantwort an Microsoft Teams zurück, und Teams tauscht den Autorisierungscode gegen Token aus.

In diesem Artikel werden MCP-Plug-Ins als Standardexemplarische Vorgehensweise verwendet. Die gleichen Schritte gelten für API-Plug-Ins, die aus einem OpenAPI-Dokument erstellt wurden, sofern nicht anders angegeben.

Konfigurieren Sie die OAuth 2.0-Authentifizierung in drei Schritten: Registrieren Sie einen OAuth-Client bei Ihrem Identitätsanbieter, konfigurieren Sie den Umleitungs-URI, und erstellen Sie die OAuth 2.0-Konfiguration.

Schritt 1: Registrieren eines OAuth-Clients bei Ihrem Identitätsanbieter

Registrieren Sie eine App bei Ihrem OAuth 2.0-Anbieter (Ihrem Identitätsanbieter), um eine Client-ID und für einen vertraulichen (Web-)Client einen geheimen Clientschlüssel abzurufen. Geben Sie diese Werte an, wenn Sie die OAuth 2.0-Konfiguration in Schritt 3 erstellen.

Legen Sie für einen MCP-Server, der eine Autorisierung erfordert, die type Eigenschaft des Laufzeitauthentifizierungsobjekts auf OAuthPluginVaultfest. None und ApiKeyPluginVault gelten nicht für einen MCP-Server, für den eine Autorisierung erforderlich ist. Im Manifest wird nur die Authentifizierungskonfigurations-ID gespeichert, es werden keine Client-IDs, geheimen Clientschlüssel oder Token in das Manifest geschrieben. Um den Client dynamisch statt statisch zu registrieren, behalten Sie typeOAuthPluginVault bei und erstellen Sie die Authentifizierungskonfiguration über die dynamische Clientregistrierung (Dynamic Client Registration DCR), die für einen Server, der durch Microsoft Entra ID geschützt ist, nicht verfügbar ist.

Hinweis

Diese Werte gelten für das Plug-In-Manifest. Wenn Sie Ihren MCP-Server stattdessen als Agent-Connector im agentConnectors Knoten des Microsoft 365-App-Manifests registrieren, verwenden Sie OAuthPluginVault oder DynamicClientRegistration dort ebenfalls. Verwenden Sie AzureKeyVaultnicht: sie existiert nur im Schema, sodass ein Paket, das devPreview auf eine nummerierte Schemaversion abzielt, bei der Überprüfung fehlschlägt. Weitere Informationen finden Sie unter Registrieren von MCP-Servern als Agent-Connectors.

Schritt 2: Konfigurieren des Umleitungs-URI

Fügen Sie die folgende Umleitungs-URI (auch Autorisierungsrückruf-URL genannt) zu Ihrer OAuth-Anbieterregistrierung hinzu:

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

Dies ist die URL, an die Ihr OAuth-Anbieter die Autorisierungsantwort sendet, nachdem sich ein Benutzer angemeldet hat. Teams empfängt die Antwort unter dieser Rückruf-URL und tauscht den Autorisierungscode gegen Token aus. Wenn Sie diesen Umleitungs-URI nicht bei Ihrem Anbieter registrieren, schlägt die Anmeldung fehl. Der Umleitungs-URI ist für jedes Plug-In und jeden Anbieter gleich – Sie passen ihn nicht pro App an.

Schritt 3: Erstellen der OAuth 2.0-Authentifizierungskonfiguration

Die OAuth 2.0-Authentifizierung basiert auf einer Authentifizierungskonfiguration (Authentifizierungskonfiguration) – einem im Microsoft Enterprise-Tokenspeicher gespeicherten Eintrag, den Microsoft 365 Copilot verwendet, um Token für Ihr MCP-Plug-In abzurufen und zu aktualisieren. Sie können die Authentifizierungskonfiguration auf drei Arten erstellen. Die empfohlenen Ansätze – Microsoft 365 Agents Toolkit und der Entwicklerskill für deklarative Agents – erstellen Sie die Authentifizierungskonfiguration, und aktualisieren Sie Ihr Plug-In-Manifest automatisch. Anschließend können Sie das Teams-Entwicklerportal verwenden, um die Authentifizierungskonfiguration zu verwalten und zu verfeinern.

Wie auch immer Sie es erstellen, die Authentifizierungskonfiguration verfügt über eine Authentifizierungskonfigurations-ID , auf die Ihr Plug-In-Manifest verweist.

Wenn Sie einen Agent mit einem MCP-Plug-In erstellen (wenn der Server eine Authentifizierung erfordert) oder ein API-Plug-In aus einem vorhandenen OpenAPI-Dokument im Microsoft 365 Agents Toolkit erstellen, werden Sie vom Toolkit zur Eingabe der OAuth-Client-ID, des geheimen Clientschlüssels und der Bereiche aufgefordert. Agents Toolkit ruft die Autorisierungs-, Token- und Aktualisierungsendpunkte vom bekannten Endpunkt Ihres MCP-Servers (oder aus dem OpenAPI-Dokument für API-Plug-Ins) ab, erstellt die Authentifizierungskonfiguration im Enterprise-Tokenspeicher und aktualisiert das Laufzeitauthentifizierungsobjekt in Ihrem Plug-In-Manifest automatisch.

Hinweis

Für API-Plug-Ins müssen Sie die securitySchemes Eigenschaft in Ihrem OpenAPI-Dokument definieren, damit Agents Toolkit die OAuth-Details lesen kann. Weitere Informationen finden Sie unter OAuth 2.0.

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

PKCE ist standardmäßig aktiviert, da viele Organisationen geheime Clientschlüssel blockieren. Legen Sie diese Einstellung in Ihrem Agentprojekt nur dann auf false m365agents.yml fest, isPKCEEnabled wenn Ihr OAuth-Anbieter PKCE nicht unterstützt.

isPKCEEnabled: false

Um geheime Clientschlüssel vollständig zu vermeiden, registrieren Sie einen öffentlichen Client bei Ihrem Anbieter – eine Single-Page-Anwendungsplattform anstelle einer Webplattform – und lassen Sie PKCE den Codeaustausch sichern.

Verwenden des Entwicklerskills für deklarative Agents

Der Skill "Entwickler für deklarative Agents" (declarative-agent-developer) ist ein Agent-Skill in Microsoft Work IQ , der das Wissen enthält, das zum Erstellen deklarativer Agents erforderlich ist. Anstatt Befehle auszuführen oder Manifeste selbst zu bearbeiten, beschreiben Sie in natürlicher Sprache, was Sie Copilot oder der GitHub-CLI hinzufügen möchten. Der Skill erstellt ein Gerüst für den deklarativen Agent, fügt das MCP-Plug-In hinzu und übernimmt die Authentifizierungskonfiguration für Sie. Der Skill unterstützt nur MCP-Plug-Ins. Für OAuth 2.0 unterstützt es sowohl die statische Registrierung als auch die dynamische Clientregistrierung (DCR): Es erstellt die Authentifizierungskonfiguration im Enterprise-Tokenspeicher und aktualisiert das Plug-In-Manifest ohne manuelle Schritte.

Tipp

Eine exemplarische Vorgehensweise zur Verwendung des Entwicklerskills für deklarative Agents finden Sie unter Erstellen deklarativer Agents mit dem Entwicklerskill für deklarative Agents.

Verwenden des Teams-Entwicklerportals

Die Registrierung im Teams-Entwicklerportal ist optional, wenn Sie das Agents-Toolkit oder den deklarativen Agent-Entwicklerskill verwenden. Verwenden Sie es, wenn Sie die Authentifizierungskonfiguration manuell erstellen möchten, oder - häufiger - um eine Authentifizierungskonfiguration zu verwalten, die Agents Toolkit oder der bereits erstellte Skill enthält. Im Portal können Sie die Authentifizierungskonfiguration auf eine bestimmte Teams-App oder Microsoft 365-organization beschränken und andere Eigenschaften ändern.

Die OAuth-Clientregistrierung im Teams-Entwicklerportal verbindet die Plug-In-Konfiguration Ihres Agents mit der OAuth-Anbieterregistrierung, die Token für Ihren MCP-Server oder Ihre API ausstellt. Die Werte in dieser Registrierung müssen mit Ihrem OAuth-Anbieter, Ihrem Plug-In-Manifest und dem geschützten API-Endpunkt übereinstimmen. Nicht übereinstimmende Basis-URLs, App-Einschränkungen oder Authentifizierungskonfigurations-IDs können Benutzer daran hindern, sich anzumelden, oder den Austausch von Token blockieren.

Warnung

Beschränken Sie die Registrierung auf beliebige Teams-Apps. Eine Registrierung, die auf eine bestimmte Teams-App beschränkt ist, ist an diese Teams-App-ID gebunden. Microsoft 365 Copilot löst diese ID beim Aufrufen eines MCP-Servers nicht auf, sodass die Bereitstellung erfolgreich abgeschlossen wird und dann jeder Toolaufruf einen 404 Fehler zurückgibt.

  1. Öffnen Sie das Teams-Entwicklerportal. Wählen Sie Extras ->OAuth-Clientregistrierung aus.

  2. Wenn noch keine Registrierungen vorhanden sind, wählen Sie "Client registrieren" aus. Wenn Sie bereits registriert sind, wählen Sie Neue OAuth-Clientregistrierung aus.

  3. Füllen Sie die folgenden Felder aus.

    • Registrierungsname: Ein Anzeigename für Ihre Registrierung.
    • Basis-URL: Die Basis-URL Ihrer API. Dieser Wert sollte der URL in der url Eigenschaft des MCP-Serverspezifikationsobjekts im Plug-In-Manifest für MCP-basierte Plug-Ins oder einem Eintrag im servers Array in Ihrem OpenAPI-Dokument für API-Plug-Ins entsprechen.
    • Einschränken der Nutzung nach Organisation: Wählen Sie aus, welche Microsoft 365-Organisationen diese OAuth-Registrierung für den Zugriff auf Ihre API-Endpunkte verwenden können. Use My organization only for development or testing in one tenant. Verwenden Sie eine beliebige Microsoft 365-organization, wenn das Plug-In mandantenübergreifend funktionieren muss.
    • Einschränken der Nutzung nach App: Wählen Sie eine beliebige Teams-App aus. Binden Sie die Registrierung nicht an eine vorhandene Teams-App-ID für einen MCP-Server. Wenn Sie die Authentifizierungskonfiguration stattdessen mit dem Microsoft 365 Agents Toolkit bereitstellen, lautet die entsprechende Einstellung in der oauth/register Aktion in m365agents.yml .applicableToApps: AnyApp Behalten Sie das appId Feld in dieser Aktion bei, auch wenn AnyApp es inaktiv wird, da der Bereitstellungstreiber bedingungslos validiert appId wird und das Entfernen der Bereitstellung unterbrochen wird.
    • Client-ID: Die Client-ID oder Anwendungs-ID, die von Ihrem OAuth 2.0-Anbieter ausgestellt wurde.
    • Geheimer Clientschlüssel: Ihr geheimer Clientschlüssel, der von Ihrem OAuth 2.0-Anbieter ausgestellt wurde.
    • Autorisierungsendpunkt: Die URL Ihres OAuth 2.0-Anbieters, die Apps verwenden, um einen Autorisierungscode anzufordern.
    • Tokenendpunkt: Die URL Ihres OAuth 2.0-Anbieters, die Apps verwenden, um einen Code für ein Zugriffstoken einzulösen.
    • Endpunkt aktualisieren: Die URL von Ihrem OAuth 2.0-Anbieter, die Apps zum Aktualisieren des Zugriffstokens verwenden.
    • Umfang: Die Berechtigungen, die Ihr Plug-In vom OAuth-Anbieter anfordert. Verwenden Sie die Bereichswerte, die von Ihrem Anbieter und Ihrer API verlangt werden. Wenn Ihr Anbieter die Microsoft Identity Platform verwendet und Ihr Plug-In Aktualisierungstoken benötigt, schließen Sie diese in alle API-spezifischen delegierten Bereiche ein.offline_access
    • Beweisschlüssel für Codeaustausch (PKCE) aktivieren: Lassen Sie diese Einstellung aktiviert. Es ist standardmäßig aktiviert; Deaktivieren Sie es nur, wenn Ihr OAuth-Anbieter PKCE nicht unterstützt.

  4. Klicken Sie auf Speichern.

  5. Nach Abschluss der Registrierung wird die Authentifizierungskonfiguration erstellt und eine Authentifizierungskonfigurations-ID generiert (derzeit als OAuth-Clientregistrierungs-ID im Teams-Entwicklerportal bezeichnet).

Hinzufügen der Auth-Konfigurations-ID zum Plug-In-Manifest

Wenn Sie die Authentifizierungskonfiguration manuell im Teams-Entwicklerportal erstellen, legen Sie die type Eigenschaft des Laufzeitauthentifizierungsobjekts auf OAuthPluginVaultund legen Sie die reference_id auf die Authentifizierungskonfigurations-ID fest. Das Agents-Toolkit und der deklarative Agent-Entwicklerskill erledigen dies für Sie.

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

Überlegungen zu Microsoft Entra ID

Wenn Sie Ihren MCP-Server mithilfe von Microsoft Entra ID schützen, gelten drei Einschränkungen, die Sie in Tools nicht umgehen können.

  • Die dynamische Clientregistrierung ist nicht verfügbar. Microsoft Entra ID veröffentlicht keinen RFC 7591-Registrierungsendpunkt, sodass die dynamische Clientregistrierung nichts hat, wofür sie registriert werden kann. Registrieren Sie den OAuth-Client statisch, indem Sie die Schritte in diesem Artikel ausführen.
  • Der agentConnectors Knoten verfügt über keinen Microsoft Entra-Autorisierungstyp. Im Gegensatz zu composeExtensionshat der agentConnectors Knoten im Microsoft 365-App-Manifest keinen microsoftEntra Autorisierungstyp. Ein MCP-Server, der durch Microsoft Entra ID geschützt ist, benötigt immer eine App, die Sie selbst in Microsoft Entra ID registrieren, sowie eine OAuth-Authentifizierungskonfiguration, auch wenn der Server einer Microsoft-API eines Erstanbieters vorausgeht.
  • Die Bereichszustimmung wird bei der Bereitstellung nicht überprüft. Bei der Bereitstellung wird nicht geprüft, ob dem von Ihnen angeforderten Bereich eine Zustimmung erteilt werden kann. Ein Bereich, dem keine Zustimmung erteilt werden kann und der später mit "Administratorgenehmigung erforderlich" fehlschlägt, kann die Ressourcen-App sowohl für Sie als auch für Ihren Mandantenadministrator unsichtbar sein. Vergewissern Sie sich, dass ein Administrator dem Umfang zugestimmt hat, bevor Sie die Bereitstellung durchführen.

Verwalten der Authentifizierungskonfiguration

Die oauth/register Aktion in m365agents.yml erstellt nur eine Authentifizierungskonfiguration oder überspringt deren Erstellung – es wird nie ein vorhandener Datensatz umgeschrieben.

  • Wenn configurationId bereits ein Wert vorhanden ist, bewirkt die Aktion nichts.
  • Wenn configurationId auf eine Registrierung verweist, die Sie gelöscht haben, warnt Sie die Aktion und tut nichts.
  • Verwenden Sie die oauth/update Aktion, um die Werte in einer vorhandenen Registrierung zu ändern.
  • Um eine Registrierung zu löschen, verwenden Sie das Teams-Entwicklerportal. Dies ist der einzige Ort, an dem Sie eine löschen können.

Abmelden

Hinweis

Benutzer können sich von einem Agent über die Chat-Einstellungen>Agents in Microsoft 365 Copilot abmelden. Durch diese Aktion wird das gespeicherte OAuth-Token gelöscht.

Verwandte Inhalte

  • Last updated on