Freigeben über

API-Schlüsselauthentifizierung

Die API-Schlüsselauthentifizierung ist eine Methode zum Authentifizieren des Zugriffs auf Ihre Nachrichtenerweiterungs-App mithilfe einer API. Dies umfasst die Verwendung eines eindeutigen API-Schlüssels, der mit jeder API-Anforderung übergeben wird, um die Identität des Benutzers oder der App zu überprüfen, die die Anforderung initiiert hat. Der API-Schlüssel muss in Microsoft Teams registriert werden, und wenn ein Benutzer mit Ihrer Nachrichtenerweiterung interagiert, verwendet Teams das Geheimnis für die Authentifizierung bei Ihrer API.

Die folgenden API-Schlüsselregistrierungseigenschaften helfen Ihnen, Ihren Schlüssel zu schützen und sicherzustellen, dass er auf Ihre Anwendung beschränkt ist:

  • Basis-URL: Teams überträgt das Geheimnis an URL-Endpunkte, die mit dem Wert in diesem Feld beginnen.
  • Zielmandant: Zum Einschränken des API-Zugriffs auf Ihren Microsoft 365-Mandanten oder einen beliebigen Mandanten.
  • App-ID: Zum Einschränken des Schlüsselzugriffs auf eine bestimmte App oder eine beliebige App.
  • API-Schlüssel: Zum Authentifizieren des Zugriffs auf Ihre App.

Sie können einen API-Schlüssel über das Entwicklerportal für Teams registrieren und eine API-Schlüsselregistrierungs-ID generieren. Aktualisieren Sie das App-Manifest mit dem apiSecretServiceAuthConfiguration -Objekt mit einer apiSecretRegistrationId -Eigenschaft. Diese Eigenschaft muss die API-Schlüsselregistrierungs-ID enthalten, die zurückgegeben wurde, als Sie den API-Schlüssel über das Entwicklerportal für Teams übermittelt haben.

Hinweis

Sie müssen sicherstellen, dass die REGISTRIERUNGS-ID des API-Schlüssels gesichert wird, da sie aus dem Teams-App-Manifest abgerufen werden kann. Weitere Informationen zum Schützen Ihres API-Schlüssels finden Sie unter Bewährte Methoden.

Wenn eine API-Anforderung initiiert wird, ruft das System den API-Schlüssel aus einer verschlüsselten Datenbank ab und schließt ihn mithilfe des Bearertokenschemas in den Autorisierungsheader ein. Das System sendet den Autorisierungsheader mit dem API-Schlüssel an den im App-Manifest definierten Endpunkt.

Das folgende Beispiel zeigt die Nutzlast mit dem Autorisierungsheader unter Verwendung des Bearertokenschemas:

GET https://example.com/search?myQuery=test
Accept-Language: en-US
Authorization: Bearer <MY_API_KEY>

Registrieren eines API-Schlüssels

Führen Sie die folgenden Schritte aus, um einen API-Schlüssel zu registrieren:

  1. Wechseln Sie zu Tools>API-Schlüsselregistrierung.

    Screenshot: Option

  2. Wählen Sie + Neuer API-Schlüssel aus.

  3. Wählen Sie auf der Seite API-Schlüsselregistrierungdie Option + Geheimnis hinzufügen aus. Das Dialogfeld API-Schlüssel hinzufügen wird angezeigt.

  4. Geben Sie einen Wert für den Schlüssel ein, und wählen Sie Speichern aus.

    Hinweis

    Sie können bis zu zwei API-Schlüssel verwalten. Wenn Sie einen ersetzen müssen, können Sie dies ohne Dienstunterbrechung tun, da Teams während des Updatevorgangs den anderen konfigurierten Schlüssel verwendet.

    Screenshot: Dialogfeld

  5. Fügen Sie unter API-Schlüsselname einen aussagekräftigen Namen für den API-Schlüssel hinzu. Beispiel: API-Schlüssel für die Contoso-Nachrichtenerweiterung.

  6. Geben Sie unter Basis-URL eine allgemeine Basis-URL für alle API-Endpunkte an, die aufgerufen werden müssen. Diese URL muss mit https beginnen, einen vollqualifizierten Domänennamen und optional einen Pfad enthalten. Teams überträgt den Schlüssel an den URL-Endpunkt, der mit dem Wert in diesem Feld beginnt. Beispiel: https://api.yelp.com.

    Die Basis-URL stellt sicher, dass der Schlüssel sicher bleibt und nicht an zufällige Endpunkte weitergegeben wird, auch wenn eine andere App die REGISTRIERUNGS-ID des API-Schlüssels illegal abruft und in ihre eigene App integriert. Wenn die in der API-Schlüsselkonfiguration registrierte URL kein Präfix für die in der OpenAPI-Spezifikation definierten Zielendpunkte ist, wird der Aufruf gelöscht.

    Screenshot: Optionen

  7. Wählen Sie unter Zielmandant eine der folgenden Optionen aus:

    • Basismandant: Der API-Schlüssel ist nur innerhalb des Mandanten funktionsfähig, in dem er registriert ist.
    • Jeder Mandant: Der API-Schlüssel kann in jedem Mandanten verwendet werden.

    Screenshot: Optionen

  8. Wählen Sie unter Teams-Ziel-App eine der folgenden Optionen aus:

    • Vorhandene Teams-App: Die Option Vorhandene Teams-App bindet die REGISTRIERUNGS-ID des API-Schlüssels an Ihre spezifische Teams-App.
    • Jede Teams-App: Der API-Schlüssel kann mit jeder Teams-App verwendet werden.

    Screenshot der Optionen

    Eine API-Schlüsselregistrierungs-ID wird generiert.

    Screenshot: Im Entwicklerportal für Teams generierte API-Schlüsselregistrierungs-ID

  9. Wählen Sie im Entwicklerportal für Teams apps und dann eine App aus, der Sie den API-Schlüssel hinzufügen möchten.

  10. Wechseln Sie zu App-Features>Nachrichtenerweiterung.

  11. Wählen Sie unter Authentifizierungdie Option API-Schlüssel aus, und fügen Sie die Registrierungs-ID des API-Schlüssels hinzu.

    Screenshot: Beispiel für den Abschnitt

  12. Klicken Sie auf Speichern.

Die REGISTRIERUNGS-ID des API-Schlüssels wird als Wert für die apiSecretRegistrationId Eigenschaft im App-Manifest aktualisiert. Sie können Ihre API-Schlüsselregistrierungs-ID im App-Manifest im Entwicklerportal für Teams überprüfen.

Aktualisieren des App-Manifests

Fügen Sie ein apiSecretServiceAuthConfiguration Objekt mit einer apiSecretRegistrationId Eigenschaft hinzu, die die Verweis-ID enthält, wenn Sie den API-Schlüssel über das Entwicklerportal für Teams übermitteln. Weitere Informationen finden Sie unter composeExtensions.commands.

"composeExtensions": [
    {
      "composeExtensionType": "apiBased",
      "authorization": {
        "authType": "apiSecretServiceAuth",
        "apiSecretServiceAuthConfiguration": {
            "apiSecretRegistrationId": "9xxxxb0f-xxxx-40cc-xxxx-15xxxxxxxxx3"
        }
      },

Bewährte Methoden

  • API-Schlüssel:

    • Der API-Schlüssel muss mindestens 10 Zeichen und höchstens 2048 Zeichen enthalten.
    • Nach dem Aktualisieren des API-Schlüssels dauert es bis zu einer Stunde, bis der Schlüssel im gesamten System angezeigt wird.

  • Basis-URL:

    • Die Basis-URL muss mit https beginnen, um eine sichere Kommunikation sicherzustellen.
    • Sie müssen den vollständigen Hostnamen angeben, um die genaue Domäne anzugeben.
    • Sie können einen optionalen Pfad hinzufügen, um einen bestimmten Einstiegspunkt für die API zu definieren.

    Diese Struktur ist entscheidend für die Sicherheit Ihrer API-Schlüssel, da Teams api-Schlüssel an Endpunkte sendet, die mit der angegebenen Basis-URL beginnen.

  • Zielmandant: Während Sie Ihre App in Ihrem Microsoft 365-Mandanten entwickeln, testen Sie sie zunächst als benutzerdefinierte App, die für Ihre Organisation (LOB-App) oder eine benutzerdefinierte App erstellt wurde. In dieser Phase müssen Sie den API-Schlüssel bei Ihrem Home-Mandanten als Zielmandanten registrieren, um sicherzustellen, dass der Schlüssel exklusiv für Ihren Mandanten bleibt.

    Nachdem Sie die Tests abgeschlossen haben und bereit sind, Ihr App-Manifest an das Partner Center für den Teams Store zu übermitteln, müssen Sie die Einstellung des Zielmandanten in Beliebiger Mandant ändern. Diese Änderung ermöglicht die Verwendung Ihrer API-Schlüsselregistrierungs-ID für verschiedene Mandanten, sobald Ihre App im Teams Store verfügbar ist.

  • Teams-App-ID: Wenn Sie Ihre App in Ihrem Microsoft 365-Mandanten entwickeln und als benutzerdefinierte App testen, die für Ihre Organisation (LOB) oder benutzerdefinierte App erstellt wurde, müssen Sie die REGISTRIERUNGS-ID des API-Schlüssels mit der Teams-App-ID als Beliebige Teams-App festlegen. Diese Konfiguration ermöglicht die Verwendung des Schlüssels mit jeder Teams-App, die als benutzerdefinierte App hochgeladen wurde, und mit benutzerdefinierten Apps, die für Ihre Organisation (BRANCHEN-Apps) erstellt wurden, um IDs nach dem Hochladen zu generieren. Sie verfügen zu diesem Zeitpunkt nicht über die APP-ID.

    Die Sicherheit Ihres Schlüssels wird weiterhin über den Basismandanten und die Basis-URL aufrechterhalten. Wenn Sie bereit sind, Ihre App für die Welt freizugeben, müssen Sie die Einstellung Teams-App-ID in Vorhandene Teams-App ändern und Ihre Teams-App-ID eingeben. Übermitteln Sie schließlich Ihr App-Manifest an das Partner Center zur Aufnahme in den Teams Store. Ihre API-Schlüsselregistrierung ist jetzt an Ihre spezifische Teams-App gebunden und kann nicht mit anderen verwendet werden.

    Für eine benutzerdefinierte App, die für Ihre Organisation (LOB) oder benutzerdefinierte App erstellt wurde, gibt es eine interne App-ID, auf die nur schwer zugegriffen werden kann. Beschränken Sie in diesem Szenario die Konfiguration auf den Mandanten, in dem die App verwendet wird. Verknüpfen Sie bei anderen Apps die API-Schlüsselregistrierung mit Ihrer veröffentlichten App-ID, nachdem Sie sie im Teams Store veröffentlicht haben.

Siehe auch