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:
Wechseln Sie zu Tools>API-Schlüsselregistrierung.
Wählen Sie + Neuer API-Schlüssel aus.
Wählen Sie auf der Seite API-Schlüsselregistrierungdie Option + Geheimnis hinzufügen aus. Das Dialogfeld API-Schlüssel hinzufügen wird angezeigt.
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.
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.
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.
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.
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.
Eine API-Schlüsselregistrierungs-ID wird generiert.
Wählen Sie im Entwicklerportal für Teams apps und dann eine App aus, der Sie den API-Schlüssel hinzufügen möchten.
Wechseln Sie zu App-Features>Nachrichtenerweiterung.
Wählen Sie unter Authentifizierungdie Option API-Schlüssel aus, und fügen Sie die Registrierungs-ID des API-Schlüssels hinzu.
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 128 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.
- Die Basis-URL muss mit
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.