Authentifizierung in Direct Line API 1.1
Wichtig
Dieser Artikel beschreibt die Authentifizierung in Direct Line API v1. 1. Wenn Sie eine neue Verbindung zwischen Ihrer Clientanwendung und Ihrem Bot erstellen, verwenden Sie stattdessen Direct Line API 3.0.
Ein Client kann Anforderungen an Direct Line API 1.1 entweder über ein Geheimnis authentifizieren, das Sie von der Konfigurationsseite des Direct Line-Kanals im Bot-Frameworkportal abrufen, oder mithilfe eines Tokens, das Sie zur Laufzeit abrufen.
Das Geheimnis bzw. Token muss im Authorization-Header jeder Anforderung angegeben werden, entweder mit dem Schema „Bearer“ oder dem Schema „BotConnector“.
Bearer-Schema:
Authorization: Bearer SECRET_OR_TOKEN
BotConnector-Schema:
Authorization: BotConnector SECRET_OR_TOKEN
Geheimnisse und Token
Ein Direct Line-Geheimnis ist ein Hauptschlüssel, der verwendet werden kann, um auf eine beliebige Konversation zuzugreifen, die zu dem zugehörigen Bot gehört. Ein Geheimnis kann auch zum Abrufen eines Tokens verwendet werden. Geheime Geheimnisse laufen nicht ab.
Ein Direct Line-Token ist ein Schlüssel, der zum Zugriff auf eine einzelne Konversation verwendet werden kann. Ein Token läuft zwar ab, kann aber aktualisiert werden.
Wenn Sie eine Dienst-zu-Dienst-Anwendung erstellen, kann die Angabe des Geheimnisses im Authorization-Header der Direct Line-API-Anforderungen der einfachste Ansatz sein. Wenn Sie eine Anwendung schreiben, in der der Client in einem Webbrowser oder einer mobilen App ausgeführt wird, sollten Sie Ihr Geheimnis gegen ein Token (das nur für eine einzelne Konversation funktioniert und abläuft, wenn es nicht aktualisiert wird) austauschen und das Token im Authorization-Header der Direct Line API-Anforderungen angeben. Wählen Sie das Sicherheitsmodell aus, das für Sie am besten geeignet ist.
Hinweis
Ihre Direct Line-Clientanmeldeinformationen unterscheiden sich von den Anmeldeinformationen Ihres Bots. Dies ermöglicht Ihnen, Ihre Schlüssel unabhängig zu überarbeiten und Clienttoken gemeinsam zu nutzen, ohne das Kennwort Ihres Bots offenzulegen.
Abrufen eines Direct Line-Geheimnisses
Sie können einen Direct Line geheimen Schlüssel über die Direct Line Kanalkonfigurationsseite für Ihren Bot im Azure-Portal abrufen:
Generieren eines Direct Line-Tokens
Um ein Direct Line Token zu generieren, das zum Zugriff auf eine einzelne Unterhaltung verwendet werden kann, erhalten Sie zuerst den geheimen Direct Line geheimen Schlüssel aus der Direct Line Kanalkonfigurationsseite im Azure-Portal. Geben Sie dann diese Anforderung zum Austausch Ihres Direct Line-Geheimnisses gegen ein Direct Line-Token aus:
POST https://directline.botframework.com/api/tokens/conversation
Authorization: Bearer SECRET
Ersetzen Sie im Authorization-Header dieser Anforderung SECRET mit dem Wert Ihres Direct Line-Geheimnisses.
Die folgenden Codeausschnitte enthalten ein Beispiel der Anforderung „Token generieren“ und der Antwort.
Anforderung
POST https://directline.botframework.com/api/tokens/conversation
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Antwort
Wenn die Anforderung erfolgreich ist, enthält die Antwort ein Token, das für eine Konversation gültig ist. Das Token läuft in 30 Minuten ab. Damit das Token nutzbar bleibt, müssen Sie das Token aktualisieren, bevor es abläuft.
HTTP/1.1 200 OK
[other headers]
"RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn"
„Token generieren“ im Vergleich zu „Unterhaltung starten“
Der Vorgang „Token generieren“ (POST /api/tokens/conversation) ist vergleichbar mit dem Vorgang Unterhaltung starten (POST /api/conversations). Beide Vorgänge geben ein token zurück, mit dem auf eine einzelne Unterhaltung zugegriffen werden kann. Im Gegensatz zum Vorgang "Unterhaltung starten" startet der Vorgang "Token generieren" jedoch nicht die Unterhaltung oder wenden Sie sich an den Bot.
Wenn Sie beabsichtigen, das Token an Clients zu verteilen, und möchten, dass diese die Unterhaltung initiieren, verwenden Sie den Vorgang „Token generieren“. Wenn Sie die Unterhaltung sofort beginnen möchten, verwenden Sie stattdessen den Vorgang Unterhaltung starten.
Aktualisieren eines Direct Line-Tokens
Ein Direct Line Token ist für 30 Minuten gültig, bis es generiert wird und eine unbegrenzte Anzahl von Zeiten aktualisiert werden kann, solange es nicht abgelaufen ist. Ein abgelaufenes Token kann nicht aktualisiert werden. Um ein Direct Line-Token zu aktualisieren, geben Sie diese Anforderung aus:
POST https://directline.botframework.com/api/tokens/{conversationId}/renew
Authorization: Bearer TOKEN_TO_BE_REFRESHED
Ersetzen Sie im URI der Anforderung {conversationId} mit der ID der Konversation, für die das Token gültig ist, und im Authorization-Header dieser Anforderung TOKEN_TO_BE_REFRESHED mit dem Direct Line-Token, das Sie aktualisieren möchten.
Die folgenden Codeausschnitte enthalten ein Beispiel der Anforderung „Token aktualisieren“ und der Antwort.
Anforderung
POST https://directline.botframework.com/api/tokens/abc123/renew
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn
Antwort
Wenn die Anforderung erfolgreich ist, enthält die Antwort ein neues Token, das für dieselbe Konversation wie das vorherige gültig ist. Das neue Token läuft in 30 Minuten ab. Damit das neue Token nutzbar bleibt, müssen Sie das Token aktualisieren, bevor es abläuft.
HTTP/1.1 200 OK
[other headers]
"RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0"