Authentifizierung in der Direct Line-API 1,1Authentication in Direct Line API 1.1

Wichtig

Dieser Artikel beschreibt die Authentifizierung in Direct Line API v1. 1.This article describes authentication in Direct Line API 1.1. Wenn Sie eine neue Verbindung zwischen Ihrer Clientanwendung und dem Bot herstellen, verwenden Sie stattdessen Direct Line API 3.0.If you are creating a new connection between your client application and bot, use Direct Line API 3.0 instead.

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.A client can authenticate requests to Direct Line API 1.1 either by using a secret that you obtain from the Direct Line channel configuration page in the Bot Framework Portal or by using a token that you obtain at runtime.

Das Geheimnis bzw. Token muss im Authorization-Header jeder Anforderung angegeben werden, entweder mit dem Schema „Bearer“ oder dem Schema „BotConnector“.The secret or token should be specified in the Authorization header of each request, using either the "Bearer" scheme or the "BotConnector" scheme.

Bearer-Schema:Bearer scheme:

Authorization: Bearer SECRET_OR_TOKEN

BotConnector-Schema:BotConnector scheme:

Authorization: BotConnector SECRET_OR_TOKEN

Geheimnisse und TokenSecrets and tokens

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.A Direct Line secret is a master key that can be used to access any conversation that belongs to the associated bot. Ein Geheimnis kann auch zum Abrufen eines Tokens verwendet werden.A secret can also be used to obtain a token. Geheimnisse laufen nicht ab.Secrets do not expire.

Ein Direct Line-Token ist ein Schlüssel, der zum Zugriff auf eine einzelne Konversation verwendet werden kann.A Direct Line token is a key that can be used to access a single conversation. Ein Token läuft zwar ab, kann aber aktualisiert werden.A token expires but can be refreshed.

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.If you're creating a service-to-service application, specifying the secret in the Authorization header of Direct Line API requests may be simplest approach. 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.If you're writing an application where the client runs in a web browser or mobile app, you may want to exchange your secret for a token (which only works for a single conversation and will expire unless refreshed) and specify the token in the Authorization header of Direct Line API requests. Wählen Sie das Sicherheitsmodell aus, das für Sie am besten geeignet ist.Choose the security model that works best for you.

Hinweis

Ihre Direct Line-Clientanmeldeinformationen unterscheiden sich von den Anmeldeinformationen Ihres Bots.Your Direct Line client credentials are different from your bot's credentials. Dies ermöglicht Ihnen, Ihre Schlüssel unabhängig zu überarbeiten und Clienttoken gemeinsam zu nutzen, ohne das Kennwort Ihres Bots offenzulegen.This enables you to revise your keys independently and lets you share client tokens without disclosing your bot's password.

Abrufen eines Direct Line-GeheimnissesGet a Direct Line secret

Im Azure-Portal können Sie über die Direct Line-Kanalkonfigurationsseite für Ihren Bot ein Direct Line-Geheimnis abrufen:You can obtain a Direct Line secret via the Direct Line channel configuration page for your bot in the Azure Portal:

Direct Line-Konfiguration

Generieren eines Direct Line-TokensGenerate a Direct Line token

Um ein Direct Line-Token zu generieren, das für den Zugriff auf eine einzelne Konversation verwendet werden kann, rufen Sie zunächst das Direct Line-Geheimnis von der Direct Line-Kanalkonfigurationsseite im Azure-Portal ab.To generate a Direct Line token that can be used to access a single conversation, first obtain the Direct Line secret from the Direct Line channel configuration page in the Azure Portal. Geben Sie dann diese Anforderung zum Austausch Ihres Direct Line-Geheimnisses gegen ein Direct Line-Token aus:Then issue this request to exchange your Direct Line secret for a Direct Line token:

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.In the Authorization header of this request, replace SECRET with the value of your Direct Line secret.

Die folgenden Codeausschnitte enthalten ein Beispiel der Anforderung „Token generieren“ und der Antwort.The following snippets provide an example of the Generate Token request and response.

AnforderungRequest

POST https://directline.botframework.com/api/tokens/conversation
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

AntwortResponse

Wenn die Anforderung erfolgreich ist, enthält die Antwort ein Token, das für eine Konversation gültig ist.If the request is successful, the response contains a token that is valid for one conversation. Das Token läuft in 30 Minuten ab.The token will expire in 30 minutes. Damit das Token nutzbar bleibt, müssen Sie das Token aktualisieren, bevor es abläuft.For the token to remain useful, you must refresh the token before it expires.

HTTP/1.1 200 OK
[other headers]

"RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn"

„Token generieren“ im Vergleich zu „Unterhaltung starten“Generate Token versus Start Conversation

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.The Generate Token operation (POST /api/tokens/conversation) is similar to the Start Conversation operation (POST /api/conversations) in that both operations return a token that can be used to access a single conversation. Jedoch im Gegensatz zu dem Vorgang „Unterhaltung starten“ startet der Vorgang „Token generieren“ weder eine Unterhaltung, noch stellt er einen Kontakt mit dem Bot her.However, unlike the Start Conversation operation, the Generate Token operation does not start the conversation or contact the bot.

Wenn Sie beabsichtigen, das Token an Clients zu verteilen, und möchten, dass diese die Unterhaltung initiieren, verwenden Sie den Vorgang „Token generieren“.If you plan to distribute the token to clients and want them to initiate the conversation, use the Generate Token operation. Wenn Sie die Unterhaltung sofort beginnen möchten, verwenden Sie stattdessen den Vorgang Unterhaltung starten.If you intend to start the conversation immediately, use the Start Conversation operation instead.

Aktualisieren eines Direct Line-TokensRefresh a Direct Line token

Ein Direct Line-Token ist ab dem Zeitpunkt, zu dem es generiert wurde, 30 Minuten gültig und kann beliebig oft aktualisiert werden, solange es nicht abgelaufen ist.A Direct Line token is valid for 30 minutes from the time it is generated and can be refreshed an unlimited amount of times, as long as it has not expired. Ein abgelaufenes Token kann nicht aktualisiert werden.An expired token cannot be refreshed. Um ein Direct Line-Token zu aktualisieren, geben Sie diese Anforderung aus:To refresh a Direct Line token, issue this request:

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.In the URI of this request, replace {conversationId} with the ID of the conversation for which the token is valid and in the Authorization header of this request, replace TOKEN_TO_BE_REFRESHED with the Direct Line token that you want to refresh.

Die folgenden Codeausschnitte enthalten ein Beispiel der Anforderung „Token aktualisieren“ und der Antwort.The following snippets provide an example of the Refresh Token request and response.

AnforderungRequest

POST https://directline.botframework.com/api/tokens/abc123/renew
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

AntwortResponse

Wenn die Anforderung erfolgreich ist, enthält die Antwort ein neues Token, das für dieselbe Konversation wie das vorherige gültig ist.If the request is successful, the response contains a new token that is valid for the same conversation as the previous token. Das neue Token läuft in 30 Minuten ab.The new token will expire in 30 minutes. Damit das neue Token nutzbar bleibt, müssen Sie das Token aktualisieren, bevor es abläuft.For the new token to remain useful, you must refresh the token before it expires.

HTTP/1.1 200 OK
[other headers]

"RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0"

Zusätzliche RessourcenAdditional resources