API-Schlüssel-Authentifizierung konfigurieren

Tipp

Empfohlen: Beginnen Sie mit Work IQ Dev Tools für unterstützte Pro-Code-, deklarative Agent- und Plug-In-Szenarien. Siehe WIQD-Schnellstart. Toolkitbasierte Anweisungen bleiben für vorhandene Projekte und Workflows verfügbar, die sie erfordern. Überprüfen Sie die Unterstützung der Funktionen und der Zielerfahrung , bevor Sie ein Tool auswählen: WIQD ist nicht für benutzerdefinierte Engine-Agenten vorgesehen.

Einige APIs verwenden API-Schlüssel zur Autorisierung. Ein API-Schlüssel ist ein gemeinsames Geheimnis, das der Client in API-Anforderungen zur Authentifizierung und zum Zugriff einschließt. API-Plug-Ins unterstützen das Senden des API-Schlüssels auf drei Arten:

  • Als Bearertoken in der Authorization Kopfzeile
  • Als Wert in einem benutzerdefinierten Header
  • Als Abfrageparameter

Hinweis

Bei Aktionen mit deklarativen Agents gilt die API-Schlüssel-Authentifizierung für API-Plug-Ins, die aus einem OpenAPI-Dokument erstellt wurden, nicht für MCP-Plug-Ins. Verwenden Sie für das MCP-Plug-In eines Agents OAuth 2.0 (einschließlich dynamischer Clientregistrierung) oder Microsoft Entra SSO. Eine Remote-MCP-Verbindung auf Paketebene verwendet eine andere Konfiguration. Siehe Authentifizierung im App-Manifest.

Konfigurieren Sie die API-Schlüsselauthentifizierung in zwei Schritten: Fügen Sie den API-Schlüssel zu Ihrem OpenAPI-Dokument hinzu, und erstellen Sie die Konfiguration für die API-Schlüsselauthentifizierung.

Schritt 1: Hinzufügen des API-Schlüssels zum OpenAPI-Dokument

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

Bearertoken

Wenn Ihre API den API-Schlüssel als Bearertoken akzeptiert, aktivieren Sie die Bearer-Authentifizierung 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 mit der in Eigenschaft auf header und der name Eigenschaft auf den Headernamen. 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, indem Sie die in Eigenschaft auf query und die name Eigenschaft auf den Namen des Abfrageparameters festlegen. Weitere Informationen finden Sie unter API-Schlüssel.

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

Schritt 2: Erstellen der Konfiguration für die API-Schlüsselauthentifizierung

Die API-Schlüsselauthentifizierung basiert auf einer Authentifizierungskonfiguration (Authentifizierungskonfiguration) – einem im Microsoft Enterprise-Tokenspeicher gespeicherten Eintrag, den Microsoft 365 Copilot verwendet, um den API-Schlüssel zu senden, wenn Ihr Plug-In die API aufruft. Beginnen Sie mit WIQD für ein unterstütztes Pro-Code-Projekt. Toolkit- und Microsoft Teams-Entwicklerportalverfahren bleiben als Alternativen verfügbar. Der Entwicklerskill "deklarativer Agent" unterstützt die Authentifizierung von API-Schlüsseln nicht, da er MCP-Plug-Ins erstellt.

Verwenden Sie wiqd agent add auth für ein vorhandenes API-Plug-In-Manifest mit --plugin-manifest, --auth-nameund --auth-type api-key. Legen Sie diese Option auf header oder query und --api-key-name auf den Namen aus Ihrem OpenAPI-Sicherheitsschema fest--api-key-in. Wenn die API ihren Schlüssel stattdessen als Bearertoken akzeptiert, wählen Sie --auth-type bearer-tokenaus.

Beim Hinzufügen einer Aktion aus einem OpenAPI-Dokument wiqd agent add action werden API-Schlüssel- oder Bearer-Anmeldeinformationen akzeptiert --api-key . Der Befehl dokumentiert Umgebungsplatzhalter, wenn der Wert weggelassen wird. Folgen Sie der Behandlung der Anmeldeinformationen des ausgewählten Befehls, und schließen Sie den Bereitstellungsworkflow des Projekts ab. Diese API-Schlüsseloptionen stellen keine API-Schlüsselunterstützung für das MCP-Plug-In eines Agenten her.

Verwenden des Microsoft 365 Agents Toolkit

Wenn Sie ein API-Plug-In aus einem vorhandenen OpenAPI-Dokument im Microsoft 365 Agents Toolkit erstellen, registriert das Toolkit den API-Schlüssel, erstellt die Authentifizierungskonfiguration und aktualisiert Ihr Plug-In-Manifest für Sie. Sie müssen die securitySchemes Eigenschaft in Ihrem OpenAPI-Dokument definieren.

Verwenden des Teams-Entwicklerportals

Die Registrierung im Teams-Entwicklerportal ist optional, wenn Sie Agents Toolkit verwenden. Verwenden Sie es, um die Authentifizierungskonfiguration manuell zu erstellen oder eine Authentifizierungskonfiguration zu verwalten, die Agents Toolkit bereits erstellt hat.

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

  2. Wenn keine Registrierungen vorhanden sind, wählen Sie API-Schlüssel erstellen aus. Wenn Sie bereits registriert sind, 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 Array in Ihrem servers OpenAPI-Dokument entsprechen.
    • Zielmandant: Beschränken Sie den API-Zugriff auf Ihren Heimmandanten, oder lassen Sie einen beliebigen Mandanten zu.
    • Teams-Ziel-App: 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. Wählen Sie Speichern aus.

  6. Nach Abschluss der Registrierung wird eine Authentifizierungskonfigurations-ID generiert (derzeit im Teams-Entwicklerportal als API-Schlüsselregistrierungs-ID 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 ApiKeyPluginVaultund legen Sie die reference_id auf die Authentifizierungskonfigurations-ID fest. Agents Toolkit übernimmt diese Aufgaben für Sie.

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