Authentifizierung in Direct Line API 3.0

  • Artikel

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. Das Geheimnis bzw. Token muss im Authorization-Header jeder Anforderung mit diesem Format angegeben werden:

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

Die Entscheidung, wann oder ob das Geheimnis oder ein Token verwendet werden soll, muss auf der Grundlage von Sicherheitsüberlegungen getroffen werden. Die Offenlegung des Geheimnisses kann akzeptabel sein, wenn sie bewusst und mit Bedacht erfolgt. Genau genommen ist dies das Standardverhalten, da Direct Line so die Legitimität des Clients überprüfen kann. Bei der dauerhaften Speicherung von Benutzerdaten gibt es allerdings ganz allgemein Sicherheitsbedenken. Weitere Informationen finden Sie im Abschnitt Sicherheitshinweise.

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

Im Azure-Portal können Sie über die Direct Line-Kanalkonfigurationsseite für Ihren Bot ein Direct Line-Geheimnis abrufen:

Direct Line configuration

Generieren eines Direct Line-Tokens

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. Geben Sie dann diese Anforderung zum Austausch Ihres Direct Line-Geheimnisses gegen ein Direct Line-Token aus:

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.

Die folgenden Codeausschnitte enthalten ein Beispiel der Anforderung „Token generieren“ und der Antwort.

Anforderung

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. 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. 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. 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. Wenn diese Informationen nicht bereitgestellt werden, muss der Benutzer Inhalt senden, bevor Direct Line die Konversationsaktualisierung senden kann.

{
  "user": {
    "id": "string",
    "name": "string"
  },
  "trustedOrigins": [
    "string"
  ]
}
Parameter Typ Beschreibung
user.id string Optional. Kanalspezifische ID des Benutzers für die Codierung im Token. Für einen Direct Line-Benutzer muss sie mit dl_ beginnen. 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.
user.name Zeichenfolge Optional. Der Anzeigename des Benutzers für die Codierung im Token.
trustedOrigins Zeichenfolgenarray Optional. Eine Liste mit vertrauenswürdigen Domänen für die Einbettung in das Token. Dies sind die Domänen, die den Web Chat-Client des Bots hosten können. Diese Liste sollte mit der Liste auf der Direct Line-Konfigurationsseite für Ihren Bot übereinstimmen.

Antwort

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. Damit das Token nützlich bleibt, müssen Sie das Token aktualisieren, bevor es abläuft.

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“

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. 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.

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 kann beliebig oft aktualisiert werden, 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/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.

Die folgenden Codeausschnitte enthalten ein Beispiel der Anforderung „Token aktualisieren“ und der Antwort.

Anforderung

POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

Antwort

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. Damit das neue Token nutzbar bleibt, müssen Sie das Token aktualisieren, bevor es abläuft.

HTTP/1.1 200 OK
[other headers]

{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0",
  "expires_in": 1800
}

Azure KI Bot Service-Authentifizierung

Die Informationen in diesem Abschnitt basieren auf dem Artikel Hinzufügen von Authentifizierung zu Ihrem Bot über Azure Ki Bot Service.

Die Azure KI Bot Service-Authentifizierung ermöglicht es Ihnen, Benutzer bei verschiedenen Identitätsanbietern wie Microsoft Entra ID, GitHub, Uber usw. zu authentifizieren und Zugriffstoken von ihnen zu erhalten. Sie können auch die Authentifizierung für einen benutzerdefinierten OAuth2-Identitätsanbieter konfigurieren. All dies ermöglicht es Ihnen, einen Authentifizierungscode zu schreiben, der für alle unterstützten Identitätsanbieter und Kanäle funktioniert. Um diese Funktionalitäten zu nutzen:

  1. Konfigurieren Sie settings statisch auf Ihrem Bot, der die Details Ihrer Anwendungsregistrierung bei einem Identitätsanbieter enthält.
  2. Verwenden Sie eine OAuthCard in Verbindung mit den Anwendungsinformationen, die Sie im vorherigen Schritt angegeben haben, um einen Benutzer anzumelden.
  3. Rufen Sie Zugriffstoken über die Azure KI Bot Service-API ab.

Sicherheitsüberlegungen

Wenn Sie die Azure KI Bot Service-Authentifizierung mit Webchat verwenden, müssen einige wichtige Sicherheitsaspekte beachtet werden.

  1. Identitätswechsel. Identitätsdiebstahl ist der Zeitpunkt, an dem ein Angreifer den Bot davon überzeugt, dass der Angreifer eine andere Person ist. In Webchat kann ein Angreifer die Benutzer-ID seiner Webchat-Instance ändern und sich so als jemand anders ausgeben. Um den Identitätsdiebstahl zu verhindern, wird Bot-Entwicklern empfohlen, eine nicht erratbare Benutzer-ID zu verwenden.

    Wenn Sie erweiterte Authentifizierungsoptionen aktivieren, kann Azure KI Bot Service jede Änderung der Benutzer-ID weiter erkennen und ablehnen. 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. Dieses Feature setzt voraus, dass die Benutzer-ID mit dl_ beginnt.

    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. Direct Line stellt sicher, dass die an den Bot gesendeten Nachrichten diese ID als From.Id der Aktivität enthalten. Wenn ein Client eine Nachricht mit einer anderen From.Id an Direct Line sendet, wird diese in die ID im Token geändert, bevor die Nachricht an den Bot weitergeleitet wird. Nachdem ein Kanalgeheimnis mit einer Benutzer-ID initialisiert wurde, kann also keine andere Benutzer-ID mehr verwendet werden

  2. Benutzeridentitäten. Jeder Benutzer verfügt über mehrere Benutzeridentitäten:

    1. Die Identität des Benutzers in einem Kanal.
    2. Die Identität des Benutzers bei einem Identitätsanbieter, an dem der Bot interessiert ist.

Wenn ein Bot Benutzer A in einem Kanal auffordert, sich bei einem Identitätsanbieter P anzumelden, muss beim Anmeldeprozess sichergestellt werden, dass Benutzer A derjenige ist, der sich bei P anmeldet. Wenn sich ein anderer Benutzer B anmelden kann, dann hat Benutzer A über den Bot Zugriff auf die Ressource von Benutzer B. In Web Chat haben wir zwei Mechanismen, um sicherzustellen, dass sich der richtige Benutzer angemeldet hat, wie nachfolgend beschrieben.

  1. Am Ende der Anmeldung wurde dem Benutzer bisher ein zufällig generierter 6-stelliger Code (magischer Code) bereitgestellt. Der Benutzer muss diesen Code in der Konversation eingeben, die die Anmeldung initiiert hat, um den Anmeldevorgang abzuschließen. Dieser Mechanismus führt tendenziell zu einer schlechten Benutzererfahrung. Zudem ist er nach wie vor anfällig für Phishing-Angriffe. Ein böswilliger Benutzer kann einen anderen Benutzer dazu bringen, sich anzumelden und den magischen Code durch Phishing erhalten.

  2. Aufgrund der Probleme mit dem vorherigen Ansatz ist der magische Code in Azure KI Bot Service nicht mehr erforderlich. Azure KI Bot Service garantiert, dass der Anmeldevorgang nur in derselben Browsersitzung durchgeführt werden kann, in der sich auch die Webchat-Instance befindet. Diesen Schutz wird wie folgt aktiviert: Als Botentwicker müssen Sie Web Chat mit einem Direct Line-Token starten, das eine Liste mit vertrauenswürdigen Domänen enthält, die den Webchat-Client des Bots hosten können. Bisher konnten Sie dieses Token nur abrufen, indem Sie einen nicht dokumentierten optionalen Parameter an die Direct Line-Token-API übergeben haben. Mithilfe von erweiterten Authentifizierungsoptionen können Sie nun die Liste der vertrauenswürdigen Domänen (Ursprung) auf der Direct Line-Konfigurationsseite statisch angeben.

Weitere Informationen finden Sie unter Hinzufügen von Authentifizierung zu Ihrem Bot über Azure KI Bot Service.

Codebeispiele

Der folgende .NET-Controller funktioniert mit aktivierten erweiterten Authentifizierungsoptionen und gibt ein Direct Line-Token sowie eine Benutzer-ID zurück.

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.

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');
        }
    });
});

Weitere Informationen