Authentifizierung in der Direct Line-API 3,0Authentication in Direct Line API 3.0

Ein Client kann Anforderungen an Direct Line API 3.0 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 3.0 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 mit diesem Format angegeben werden:The secret or token should be specified in the Authorization header of each request, using this format:

Authorization: Bearer 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.

Die Entscheidung, wann oder ob das Geheimnis oder ein Token verwendet werden soll, muss auf der Grundlage von Sicherheitsüberlegungen getroffen werden.Deciding when or if to use the secret key or a token must be based on security considerations. Die Offenlegung des Geheimnisses kann akzeptabel sein, wenn sie bewusst und mit Bedacht erfolgt.Exposing the secret key could be acceptable if done intentionally and with care. Genau genommen ist dies das Standardverhalten, da Direct Line so die Legitimität des Clients überprüfen kann.As matter of a fact, this is the default behavior because this allows Direct Line to figure out if the client is legitimate. Bei der dauerhaften Speicherung von Benutzerdaten gibt es allerdings ganz allgemein Sicherheitsbedenken.Generally speaking though, security is a concern if you're trying to persist user data. Weitere Informationen finden Sie im Abschnitt Sicherheitshinweise.For more information, see section Security considerations.

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/v3/directline/tokens/generate
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/v3/directline/tokens/generate
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

Die Anforderungsnutzlast, in der die Tokenparameter enthalten sind, ist optional, aber ihre Verwendung wird empfohlen.The request payload, which contains the token parameters, is optional but recommended. Stellen Sie beim Generieren eines Tokens, das zurück an den Direct Line-Dienst gesendet werden kann, die folgende Nutzlast bereit, um die Verbindung sicherer zu machen.When generating a token that can be sent back to the Direct Line service, provide the following payload to make the connection more secure. Durch die Einbindung dieser Werte kann per Direct Line eine zusätzliche Sicherheitsüberprüfung der ID und des Namens des Benutzers durchgeführt werden, um eine Manipulation dieser Werte durch schädliche Clients zu verhindern.By including these values, Direct Line can perform additional security validation of the user ID and name, inhibiting tampering of these values by malicious clients. Darüber hinaus führt das Einbinden dieser Werte auch dazu, dass das Senden der Aktivität zur Konversationsaktualisierung durch Direct Line erleichtert wird, damit die Konversationsaktualisierung sofort nach dem Beitritt des Benutzers zur Konversation generiert werden kann.Including these values also improves Direct Line's ability to send the conversation update activity, allowing it to generate the conversation update immediately upon the user joining the conversation. Wenn diese Informationen nicht bereitgestellt werden, muss der Benutzer Inhalt senden, bevor Direct Line die Konversationsaktualisierung senden kann.When this information is not provided, the user must send content before Direct Line can send the conversation update.

{
  "user": {
    "id": "string",
    "name": "string"
  },
  "trustedOrigins": [
    "string"
  ]
}
ParameterParameter typeType BESCHREIBUNGDescription
user.id Zeichenfolgestring Optional.Optional. Kanalspezifische ID des Benutzers für die Codierung im Token.Channel-specific ID of the user to encode within the token. Für einen Direct Line-Benutzer muss sie mit dl_ beginnen.For a Direct Line user, this must begin with dl_. Sie können eine eindeutige Benutzer-ID für jede Konversation erstellen, und um die Sicherheit zu erhöhen, sollten Sie diese ID so wählen, dass sie nicht erraten werden kann.You can create a unique user ID for each conversation, and for better security, you should make this ID unguessable.
user.name Zeichenfolgestring Optional.Optional. Der Anzeigename des Benutzers für die Codierung im Token.The display-friendly name of the user to encode within the token.
trustedOrigins Zeichenfolgenarraystring array Optional.Optional. Eine Liste mit vertrauenswürdigen Domänen für die Einbettung in das Token.A list of trusted domains to embed within the token. Dies sind die Domänen, die den Web Chat-Client des Bots hosten können.These are the domains that can host the bot's Web Chat client. Diese Liste sollte mit der Liste auf der Direct Line-Konfigurationsseite für Ihren Bot übereinstimmen.This should match the list in the Direct Line configuration page for your bot.

AntwortResponse

Wenn die Anforderung erfolgreich war, enthält die Antwort ein token, das für eine Unterhaltung gültig ist, und einen expires_in-Wert, der die Anzahl von Sekunden bis zum Ablauf des Tokens angibt.If the request is successful, the response contains a token that is valid for one conversation and an expires_in value that indicates the number of seconds until the token expires. 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]
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800
}

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

Der Vorgang „Token generieren“ (POST /v3/directline/tokens/generate) ist vergleichbar mit dem Vorgang Unterhaltung starten (POST /v3/directline/conversations). Beide Vorgänge geben ein token zurück, mit dem auf eine einzelne Unterhaltung zugegriffen werden kann.The Generate Token operation (POST /v3/directline/tokens/generate) is similar to the Start Conversation operation (POST /v3/directline/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“ keine Unterhaltung, stellt keinen Kontakt mit dem Bot her und erstellt keine Streaming-WebSocket-URL.However, unlike the Start Conversation operation, the Generate Token operation does not start the conversation, does not contact the bot, and does not create a streaming WebSocket URL.

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 kann beliebig oft aktualisiert werden, solange es nicht abgelaufen ist.A Direct Line token 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/v3/directline/tokens/refresh
Authorization: Bearer TOKEN_TO_BE_REFRESHED

Ersetzen Sie im Authorization-Header dieser Anforderung TOKEN_TO_BE_REFRESHED mit dem Direct Line-Token, das Sie aktualisieren möchten.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/v3/directline/tokens/refresh
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

AntwortResponse

Wenn die Anforderung erfolgreich war, enthält die Antwort ein neues token, das für dieselbe Unterhaltung wie das vorherige Token gültig ist, und einen expires_in-Wert, der die Anzahl von Sekunden bis zum Ablauf des neuen Tokens angibt.If the request is successful, the response contains a new token that is valid for the same conversation as the previous token and an expires_in value that indicates the number of seconds until the new token expires. 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]
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0",
  "expires_in": 1800
}

Azure Bot Service-AuthentifizierungAzure Bot Service authentication

Die Informationen in diesem Abschnitt basieren auf dem Artikel Hinzufügen von Authentifizierung zu Ihrem Bot über Azure Bot Service.The information presented in this section is based on the Add authentication to your bot via Azure Bot Service article.

Die Azure Bot Service-Authentifizierung ermöglicht es Ihnen, Benutzer bei einer Vielzahl von Identitätsanbietern wie Azure Active Directory, GitHub, Uber usw. zu authentifizieren und Zugriffstoken von ihnen zu erhalten.Azure Bot Service authentication enables you to authenticate users to and get access tokens from a variety of identity providers such as Azure Active Directory, GitHub, Uber and so on. Sie können auch die Authentifizierung für einen benutzerdefinierten OAuth2-Identitätsanbieter konfigurieren.You can also configure authentication for a custom OAuth2 identity provider. All dies ermöglicht es Ihnen, einen Authentifizierungscode zu schreiben, der für alle unterstützten Identitätsanbieter und Kanäle funktioniert.All this enables you to write one piece of authentication code that works across all supported identity providers and channels. Um diese Funktionen nutzen zu können, müssen Sie die folgenden Schritte durchführen:To utilize these capabilities you need to perform the following steps:

  1. Konfigurieren Sie settings statisch auf Ihrem Bot, der die Details Ihrer Anwendungsregistrierung bei einem Identitätsanbieter enthält.Statically configure settings on your bot that contains the details of your application registration with an identity provider.
  2. Verwenden Sie eine OAuthCard in Verbindung mit den Anwendungsinformationen, die Sie im vorherigen Schritt angegeben haben, um einen Benutzer anzumelden.Use an OAuthCard, backed by the application information you supplied in the previous step, to sign-in a user.
  3. Rufen Sie Zugriffstoken über die Azure Bot Service-API ab.Retrieve access tokens through Azure Bot Service API.

SicherheitshinweiseSecurity considerations

Wenn Sie die Azure Bot Service-Authentifizierung mit Web Chat verwenden, sind einige wichtige Sicherheitsüberlegungen zu beachten.When you use Azure Bot Service authentication with Web Chat there are some important security considerations you must keep in mind.

  1. Identitätswechsel.Impersonation. Identitätswechsel bedeutet hier, dass ein Angreifer den Bot dazu bringt, ihn für jemand anderen zu halten.Impersonation here means an attacker makes the bot thinks he is someone else. In Web Chat kann ein Angreifer die Benutzer-ID seiner Web Chat-Instanz ändern und sich so als jemand anders ausgeben.In Web Chat, an attacker can impersonate someone else by changing the user ID of his Web Chat instance. Um dies zu verhindern, wird Botentwicklern empfohlen, eine nicht erratbare Benutzer-ID zu verwenden.To prevent this, it is recommend to bot developers to make the user ID unguessable.

    Wenn Sie erweiterte Authentifizierungsoptionen aktivieren, kann Azure Bot Service jede Änderung der Benutzer-ID weiter erkennen und ablehnen.If you enable enhanced authentication options, Azure Bot Service can further detect and reject any user ID change. Das bedeutet, dass die Benutzer-ID (Activity.From.Id) in Nachrichten von Direct Line an Ihren Bot immer die ist, mit der Sie die Web Chat-Instanz initialisiert haben.This means the user ID (Activity.From.Id) on messages from Direct Line to your bot will always be the same as the one you initialized the Web Chat with. Dieses Feature setzt voraus, dass die Benutzer-ID mit dl_ beginnt.Note that this feature requires the user ID starts with dl_.

    Hinweis

    Wenn eine Benutzer-ID (User.Id) beim Austauschen eines Geheimnisses für ein Token angegeben wird, wird diese Benutzer-ID (User.Id) in das Token eingebettet.When a User.Id is provided while exchanging a secret for a token, that User.Id is embedded in the token. DirectLine sorgt dafür, dass diese ID bei Nachrichten, die an den Bot gesendet werden, als From.Id der Aktivität verwendet wird. Wenn ein Client eine Nachricht mit einer anderen Von-ID (from.ID) an DirectLine sendet, wird diese in die ID aus dem Token geändert, bevor die Nachricht an den Bot weitergeleitet wird.DirectLine makes sure the messages sent to the bot have that id as the activity's From.Id. If a client sends a message to DirectLine having a different From.Id, it will be changed to the Id in the token before forwarding the message to the bot. Nachdem ein Kanalgeheimnis mit einer Benutzer-ID initialisiert wurde, kann also keine andere Benutzer-ID mehr verwendet werden.So you cannot use another user id after a channel secret is initialized with a user id

  2. Benutzeridentitäten.User identities. Sie müssen sich bewusst sein, dass es sich um zwei Benutzeridentitäten handelt:You must be aware that your are dealing with two user identities:

    1. Die Identität des Benutzers in einem Kanal.The user's identity in a channel.
    2. Die Identität des Benutzers in einem Identitäts Anbieter, an dem der bot interessiert ist.The user's identity in an identity provider that the bot is interested in.

    Wenn ein bot Benutzer a in einem Channel anfordert, sich bei einem Identitäts Anbieter P anzumelden, muss der Anmeldevorgang sicherstellen, dass Benutzer a der Anmeldevorgang ist, der sich bei p anmeldet. Wenn sich ein anderer Benutzer b anmelden darf, kann der Benutzer a über den bot auf die Ressource von Benutzer b zugreifen.When a bot asks user A in a channel to sign-in to an identity provider P, the sign-in process must assure that user A is the one that signs into P. If another user B is allowed to sign-in, then user A would have access to user B's resource through the bot. In Web Chat haben wir zwei Mechanismen, um sicherzustellen, dass sich der richtige Benutzer angemeldet hat, wie nachfolgend beschrieben.In Web Chat we have 2 mechanisms for ensuring the right user signed in as described next.

    1. Am Ende der Anmeldung wurde dem Benutzer bisher ein zufällig generierter 6-stelliger Code (auch bekannt als magischer Code) bereitgestellt.At the end of sign-in, in the past, the user was presented with a randomly generated 6-digit code (aka magic code). Der Benutzer muss diesen Code in der Konversation eingeben, die die Anmeldung initiiert hat, um den Anmeldevorgang abzuschließen.The user must type this code in the conversation that initiated the sign-in to complete the sign-in process. Dieser Mechanismus führt tendenziell zu einer schlechten Benutzererfahrung.This mechanism tends to result in a bad user experience. Zudem ist er nach wie vor anfällig für Phishing-Angriffe.Additionally, it is still susceptible to phishing attacks. Ein böswilliger Benutzer kann einen anderen Benutzer dazu bringen, sich anzumelden und den magischen Code durch Phishing erhalten.A malicious user can trick another user to sign-in and obtain the magic code through phishing.

    2. Aufgrund der Probleme mit dem vorherigen Ansatz ist der magische Code in Azure Bot Service nicht mehr erforderlich.Because of the issues with the previous approach, Azure Bot Service removed the need for the magic code. Azure Bot Service garantiert, dass der Anmeldevorgang nur in derselben Browsersitzung durchgeführt werden kann, in der sich auch die Web Chat-Instanz befindet.Azure Bot Service guarantees that the sign-in process can only be completed in the same browser session as the Web Chat itself. Um diesen Schutz zu ermöglichen, müssen Sie als bot-Entwickler den Webchat mit einem direkten Zeilen Token starten, das eine Liste vertrauenswürdiger Domänen enthält, die den Webchat Client des Bots hosten können.To enable this protection, as a bot developer, you must start Web Chat with a Direct Line token that contains a list of trusted domains that can host the bot's Web Chat client. Bisher konnten Sie dieses Token nur abrufen, indem Sie einen nicht dokumentierten optionalen Parameter an die Direct Line-Token-API übergeben haben.Before, you could only obtain this token by passing an undocumented optional parameter to the Direct Line token API. Mithilfe von erweiterten Authentifizierungsoptionen können Sie nun die Liste der vertrauenswürdigen Domänen (Ursprung) auf der Direct Line-Konfigurationsseite statisch angeben.Now, with enhanced authentication options, you can statically specify the trusted domain (origin) list in the Direct Line configuration page.

    Weitere Informationen finden Sie auch unter Hinzufügen von Authentifizierung zu Ihrem Bot über Azure Bot Service.See also Add authentication to your bot via Azure Bot Service.

CodebeispieleCode examples

Der folgende .NET-Controller funktioniert mit aktivierten erweiterten Authentifizierungsoptionen und gibt ein Direct Line-Token sowie eine Benutzer-ID zurück.The following .NET controller works with enhanced authentication options enabled and returns a Direct Line Token and user ID.

public class HomeController : Controller
{
    public async Task<ActionResult> Index()
    {
        var secret = GetSecret();

        HttpClient client = new HttpClient();

        HttpRequestMessage request = new HttpRequestMessage(
            HttpMethod.Post,
            $"https://directline.botframework.com/v3/directline/tokens/generate");

        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", secret);

        var userId = $"dl_{Guid.NewGuid()}";

        request.Content = new StringContent(
            JsonConvert.SerializeObject(
                new { User = new { Id = userId } }),
                Encoding.UTF8,
                "application/json");

        var response = await client.SendAsync(request);
        string token = String.Empty;

        if (response.IsSuccessStatusCode)
        {
            var body = await response.Content.ReadAsStringAsync();
            token = JsonConvert.DeserializeObject<DirectLineToken>(body).token;
        }

        var config = new ChatConfig()
        {
            Token = token,
            UserId = userId
        };

        return View(config);
    }
}

public class DirectLineToken
{
    public string conversationId { get; set; }
    public string token { get; set; }
    public int expires_in { get; set; }
}
public class ChatConfig
{
    public string Token { get; set; }
    public string UserId { get; set; }
}

Der folgende JavaScript-Controller funktioniert mit aktivierten erweiterten Authentifizierungsoptionen und gibt ein Direct Line-Token sowie eine Benutzer-ID zurück.The following JavaScript controller works with enhanced authentication options enabled and returns a Direct Line Token and user ID.

var router = express.Router(); // get an instance of the express Router

// Get a directline configuration (accessed at GET /api/config)
const userId = "dl_" + createUniqueId();

router.get('/config', function(req, res) {
    const options = {
        method: 'POST',
        uri: 'https://directline.botframework.com/v3/directline/tokens/generate',
        headers: {
            'Authorization': 'Bearer ' + secret
        },
        json: {
            User: { Id: userId }
        }
    };

    request.post(options, (error, response, body) => {
        if (!error && response.statusCode < 300) {
            res.json({
                    token: body.token,
                    userId: userId
                });
        }
        else {
            res.status(500).send('Call to retrieve token from Direct Line failed');
        }
    });
});

Zusätzliche RessourcenAdditional resources