Konfigurieren der Authentifizierung für API-Plug-Ins in Agents

Sie können die Authentifizierung für API-Plug-Ins in Agents konfigurieren, die in Microsoft 365 Copilot ausgeführt werden, indem Sie eines der vier unterstützten Authentifizierungsschemas verwenden, um eine nahtlose Verbindung mit ihren Back-End-APIs herzustellen:

• OAuth 2.0-Autorisierungscodefluss
• Microsoft Entra ID Authentifizierung mit einmaligem Anmelden (Single Sign On, SSO)
• API-Schlüsselauthentifizierung
• Keine Authentifizierung (anonym)

OAuth 2.0-Autorisierungscodefluss

Ein Plug-In kann mithilfe eines Bearertokens, das über den OAuth 2.0-Autorisierungscodeflow abgerufen wurde, mit optionaler Unterstützung für Proof Key for Code Exchange (PKCE) auf eine API zugreifen.

Bevor Sie beginnen, müssen Sie sich bei Ihrem OAuth 2.0-Anbieter registrieren, um eine Client-ID und einen geheimen Schlüssel zu erhalten. Wenn Ihr OAuth-Anbieter erfordert, dass Sie während der App-Registrierung zulässige Umleitungs-URIs angeben, stellen Sie sicher, dass Sie in die Liste einschließen https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect .

Sie können dieses Schema in der securitySchemes -Eigenschaft eines OpenAPI-Dokuments definieren. 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

Um die OAuth 2.0-Authentifizierung zu aktivieren, müssen Sie einen OAuth-Client im Teams-Entwicklerportal registrieren. Sie können einen OAuth-Client beim Teams-Toolkit in Visual Studio Code oder manuell im Teams-Entwicklerportal registrieren.

Registrieren eines OAuth-Clients beim Teams Toolkit

Teams Toolkit registriert Ihren OAuth-Client und aktualisiert Ihr App-Paket für Sie, wenn Sie einen Agent mit API-Plug-In aus einem vorhandenen OpenAPI-Dokument erstellen. Die -Eigenschaft muss in Ihrem OpenAPI-Dokument definiert sein securitySchemes .

Wenn Ihr OAuth-Anbieter PKCE unterstützt, heben Sie die Auskommentierung der folgenden Codezeile in teamsapp.yml in Ihrem Agent-Projekt auf, bevor Sie den Agent bereitstellen.

# isPKCEEnabled: true

Registrieren eines OAuth-Clients im Teams-Entwicklerportal

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

2. Wenn Keine Registrierungen vorhanden sind, wählen Sie Client registrieren aus. Wenn Sie über vorhandene Registrierungen verfügen, 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 einem Eintrag im servers Array in Ihrem OpenAPI-Dokument entsprechen.
   • 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 zum Anfordern eines Autorisierungscodes verwenden.
   • Tokenendpunkt: Die URL Ihres OAuth 2.0-Anbieters, die Apps verwenden, um einen Code für ein Zugriffstoken einzulösen.
   • Aktualisierungsendpunkt: Die URL Ihres OAuth 2.0-Anbieters, die Apps zum Aktualisieren des Zugriffstokens verwenden.
   • Bereich: Der von Ihrer API definierte Berechtigungsbereich, der den Zugriff zulässt.
   • Proof Key for Code Exchange (PKCE) aktivieren: Aktivieren Sie diese Einstellung, wenn Ihr OAuth-Anbieter PKCE unterstützt.

4. Klicken Sie auf Speichern.

5. Wenn Sie die Registrierung abschließen, wird eine OAuth-Clientregistrierungs-ID generiert.

Hinzufügen der Clientregistrierungs-ID zum Plug-In-Manifest

Um die OAuth 2.0-Authentifizierung für Ihr API-Plug-In zu verwenden, legen Sie die type -Eigenschaft des Laufzeitauthentifizierungsobjekts auf OAuthPluginVaultfest, und legen Sie auf reference_id die Clientregistrierungs-ID aus dem Teams-Entwicklerportal fest.

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

Microsoft Entra ID-SSO-Authentifizierung

Microsoft Entra ID SSO-Authentifizierung ermöglicht eine nahtlose Integration des einmaligen Anmeldens (Single Sign-On, SSO), sodass sich Benutzer mit ihren vorhandenen anmeldeinformationen Microsoft Entra ID authentifizieren können. Diese Integration vereinfacht die Zugriffsverwaltung und stellt sichere Verbindungen mit APIs sicher, ohne dass zusätzliche Anmeldeinformationen erforderlich sind. Ihre API muss Microsoft Entra ID verwenden, um den Zugriff zu steuern.

Registrieren eines SSO-Clients im Teams-Entwicklerportal

1. Öffnen Sie das Teams-Entwicklerportal. Wählen Sie Tools ->Microsoft Entra SSO-Client-ID-Registrierung aus.

2. Wenn keine Registrierungen vorhanden sind, wählen Sie Client-ID registrieren aus. Wenn Sie über vorhandene Registrierungen verfügen, wählen Sie Neue 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 einem Eintrag im servers Array in Ihrem OpenAPI-Dokument entsprechen.
   • Nutzung nach Organisation einschränken: Wählen Sie aus, welche Microsoft 365-organization Zugriff auf Ihre App hat, um auf API-Endpunkte zuzugreifen.
   • Nutzung nach App einschränken: Wählen Sie Eine beliebige Teams-App aus, wenn Sie Ihre endgültige App-ID nicht kennen. Nachdem Sie Ihre App veröffentlicht haben, binden Sie diese Registrierung an Ihre veröffentlichte App-ID.
   • Client-ID: Die Client-ID der App, die in Microsoft Entra registriert ist.

4. Klicken Sie auf Speichern.

5. Durch Abschließen der Registrierung werden eine Microsoft Entra SSO-Registrierungs-ID und ein Anwendungs-ID-URI generiert.

Aktualisieren der Microsoft Entra App-Registrierung

1. Öffnen Sie Microsoft Entra Admin Center. Aktualisieren Sie die Microsoft Entra App-Registrierung, die Ihre API mit dem anwendungs-ID-URI schützt, der vom Teams-Entwicklerportal generiert wird. Wenn Sie über einen vorhandenen Anwendungs-ID-URI verfügen, der der App-Registrierung zugeordnet ist, können Sie den Manifest-Editor verwenden, um im Abschnitt identifierUris einen weiteren URI hinzuzufügen.

   "identifierUris": [
     "<<URI1>>"
     "<<URI2>>"
   ]
   

   Hinweis

   Das Hinzufügen mehrerer URIs wird über die Benutzeroberfläche des Microsoft Entra Admin Center nicht unterstützt. Auf der Benutzeroberfläche wird nur der erste URI in der Liste angezeigt. Das Hinzufügen mehrerer URIs wirkt sich nicht auf Ihre vorhandenen URIs und Bereiche aus, auch wenn sie auf der Benutzeroberfläche anders angezeigt werden.

2. Wählen Sie unter Verwalten die Option Authentifizierung aus. Fügen Sie https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect den Umleitungs-URIs auf der Webplattform hinzu.

3. Wählen Sie unter Verwalten die Option Eine API verfügbar machen aus. Wählen Sie Clientanwendung hinzufügen aus, und fügen Sie die Client-ID des Unternehmenstokenspeichers von Microsoft hinzu. ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b

Hinzufügen der SSO-Registrierungs-ID zum Plug-In-Manifest

Legen Sie die type -Eigenschaft des Laufzeitauthentifizierungsobjekts auf OAuthPluginVaultfest, und legen Sie auf reference_id die Microsoft Entra SSO-Registrierungs-ID aus dem Teams-Entwicklerportal fest.

"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "SSO registration ID"
},

Hinzufügen der neuen Tokenzielgruppe zu Ihrer API

Aktualisieren Sie Ihre API, um den neuen Bezeichner-URI als Tokenzielgruppe zuzulassen. Wenn Ihre API die Clientanwendungs-ID überprüft, stellen Sie sicher, dass die Client-ID des Microsoft Enterprise-Tokenspeichers (ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b) als zulässige Clientanwendung hinzugefügt wird.

API-Schlüsselauthentifizierung

Einige APIs verwenden API-Schlüssel für die Autorisierung. Ein API-Schlüssel ist ein gemeinsam genutztes Geheimnis, das der Client in API-Anforderungen einschließt, um sich zu authentifizieren und Zugriff zu erhalten. API-Plug-Ins unterstützen das Senden des API-Schlüssels auf drei Arten:

• Als Bearertoken im Authorization Header
• Als Wert in einem benutzerdefinierten Header
• Als Abfrageparameter

Hinzufügen eines API-Schlüssels zu Ihrem OpenAPI-Dokument

Microsoft 365 Copilot bestimmt, wie der API-Schlüssel basierend auf dem securitySchemes Eintrag in Ihrem OpenAPI-Dokument gesendet wird.

Bearertoken

Wenn Ihre API den API-Schlüssel als Bearertoken akzeptiert, aktivieren Sie die Bearerauthentifizierung in Ihrem OpenAPI-Dokument. Weitere Informationen finden Sie unter Bearerauthentifizierung.

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer

Benutzerdefinierter Header

Wenn Ihre API den API-Schlüssel in einem benutzerdefinierten Header akzeptiert, aktivieren Sie die API-Schlüsselauthentifizierung in Ihrem OpenAPI-Dokument, wobei die in Eigenschaft auf header und die name Eigenschaft auf den Headernamen festgelegt ist. Weitere Informationen finden Sie unter API-Schlüssel.

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-KEY

Abfrageparameter

Wenn Ihre API den API-Schlüssel in einem Abfrageparameter akzeptiert, aktivieren Sie die API-Schlüsselauthentifizierung in Ihrem OpenAPI-Dokument, wobei die in Eigenschaft auf und die name Eigenschaft auf query den Namen des Abfrageparameters festgelegt ist. Weitere Informationen finden Sie unter API-Schlüssel.

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: query
    name: api_key

Registrieren eines API-Schlüssels

Um die API-Schlüsselauthentifizierung zu aktivieren, müssen Sie den API-Schlüssel im Teams-Entwicklerportal registrieren. Sie können den API-Schlüssel beim Teams-Toolkit in Visual Studio Code oder manuell im Teams-Entwicklerportal registrieren.

Registrieren eines API-Schlüssels beim Teams Toolkit

Teams Toolkit registriert Ihren API-Schlüssel und aktualisiert Ihr App-Paket für Sie, wenn Sie einen Agent mit API-Plug-In aus einem vorhandenen OpenAPI-Dokument erstellen. Die -Eigenschaft muss in Ihrem OpenAPI-Dokument definiert sein securitySchemes .

Registrieren eines API-Schlüssels im Teams-Entwicklerportal

1. Öffnen Sie das Teams-Entwicklerportal. Wählen Sie Tools ->API-Schlüsselregistrierung aus.

2. Wenn Keine Registrierungen vorhanden sind, wählen Sie API-Schlüssel erstellen aus. Wenn Sie über vorhandene Registrierungen verfügen, wählen Sie Neuer API-Schlüssel aus.

3. Wählen Sie Geheimnis hinzufügen aus, und geben Sie den API-Schlüssel ein.

4. Füllen Sie die folgenden Felder aus.

   • API-Schlüsselname: Ein Anzeigename für Ihre Registrierung.
   • Basis-URL: Die Basis-URL Ihrer API. Dieser Wert sollte einem Eintrag im servers Array in Ihrem OpenAPI-Dokument entsprechen.
   • Zielmandant: Beschränken Sie den API-Zugriff auf den Basismandanten oder nicht.
   • Teams-App als Ziel: Wählen Sie Eine beliebige Teams-App aus, wenn Sie Ihre endgültige App-ID nicht kennen. Nachdem Sie Ihre App veröffentlicht haben, binden Sie diese Registrierung an Ihre veröffentlichte App-ID.

5. Klicken Sie auf Speichern.

6. Durch Abschließen der Registrierung wird eine API-Schlüsselregistrierungs-ID generiert.

Hinzufügen der REGISTRIERUNGS-ID des API-Schlüssels zum Plug-In-Manifest

1. Legen Sie in Ihrer Plug-In-Manifestdatei die type -Eigenschaft des Laufzeitauthentifizierungsobjekts auf ApiKeyPluginVaultfest, und legen Sie auf reference_id die REGISTRIERUNGS-ID des API-Schlüssels aus dem Teams-Entwicklerportal fest.

"auth": {
  "type": "ApiKeyPluginVault",
  "reference_id": "app key registration ID"
},

Keine Authentifizierung (anonym)

Für APIs, die keine Authentifizierung erfordern, oder für Entwicklerumgebungen, in denen die Authentifizierung noch nicht implementiert ist, können Plug-Ins anonym auf die APIs zugreifen. Legen Sie in diesem Fall die type -Eigenschaft des Laufzeitauthentifizierungsobjekts auf fest None.

"auth": {
  "type": "None"
},