Verificatie in Direct Line API 3.0

Een client kan aanvragen voor Direct Line API 3.0 verifiëren met behulp van een geheim dat u ophaalt via de configuratiepagina van het Direct Line-kanaal in de Bot Framework-portal of met behulp van een token dat u tijdens runtime verkrijgt. Het geheim of token moet worden opgegeven in de Authorization header van elke aanvraag, met behulp van deze indeling:

Authorization: Bearer SECRET_OR_TOKEN

Geheimen en tokens

Een Direct Line-geheim is een hoofdsleutel die kan worden gebruikt voor toegang tot gesprekken die deel uitmaken van de bijbehorende bot. Een geheim kan ook worden gebruikt om een token te verkrijgen. Geheimen verlopen niet.

Een Direct Line-token is een sleutel die kan worden gebruikt voor toegang tot één gesprek. Een token verloopt, maar kan worden vernieuwd.

Bepalen wanneer of of de geheime sleutel of een token moet worden gebruikt, moet zijn gebaseerd op beveiligingsoverwegingen. Het blootstellen van de geheime sleutel kan acceptabel zijn als dit opzettelijk en met zorg wordt gedaan. Dit is het standaardgedrag omdat Direct Line hiermee kan bepalen of de client legitiem is. Over het algemeen is beveiliging echter een probleem als u gebruikersgegevens probeert vast te houden. Zie de sectie Beveiligingsoverwegingen voor meer informatie.

Als u een service-naar-service-toepassing maakt, is het opgeven van het geheim in de Authorization header van Direct Line API-aanvragen mogelijk het eenvoudigst. Als u een toepassing schrijft waarin de client wordt uitgevoerd in een webbrowser of mobiele app, kunt u uw geheim uitwisselen voor een token (dat alleen werkt voor één gesprek en verloopt tenzij vernieuwd) en het token opgeven in de Authorization header van Direct Line-API-aanvragen. Kies het beveiligingsmodel dat het beste bij u past.

Notitie

De referenties van uw Direct Line-client verschillen van de referenties van uw bot. Hierdoor kunt u uw sleutels onafhankelijk herzien en kunt u clienttokens delen zonder het wachtwoord van uw bot bekend te maken.

Een Direct Line-geheim ophalen

U kunt een Direct Line-geheim verkrijgen via de configuratiepagina van het Direct Line-kanaal voor uw bot in Azure Portal:

Een Direct Line-token genereren

Als u een Direct Line-token wilt genereren dat kan worden gebruikt voor toegang tot één gesprek, moet u eerst het Direct Line-geheim verkrijgen via de configuratiepagina van het Direct Line-kanaal in Azure Portal. Geef vervolgens deze aanvraag uit om uw Direct Line-geheim in te wisselen voor een Direct Line-token:

POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer SECRET

Vervang SECRET in de Authorization header van deze aanvraag door de waarde van uw Direct Line-geheim.

De volgende codefragmenten bevatten een voorbeeld van de aanvraag en het antwoord genereren van tokens.

Aanvragen

POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

De nettolading van de aanvraag, die de tokenparameters bevat, is optioneel, maar wordt aanbevolen. Wanneer u een token genereert dat naar de Direct Line-service kan worden verzonden, geeft u de volgende nettolading op om de verbinding veiliger te maken. Door deze waarden op te tellen, kan Direct Line extra beveiligingsvalidatie uitvoeren van de gebruikers-id en -naam, waardoor deze waarden worden geremd door kwaadwillende clients. Als u deze waarden opneemt, verbetert u ook de mogelijkheid van Direct Line om de activiteit van de gespreksupdate te verzenden, zodat deze de gespreksupdate onmiddellijk kan genereren wanneer de gebruiker deelneemt aan het gesprek. Wanneer deze informatie niet is opgegeven, moet de gebruiker inhoud verzenden voordat direct line de gespreksupdate kan verzenden.

{
  "user": {
    "id": "string",
    "name": "string"
  },
  "trustedOrigins": [
    "string"
  ]
}

Parameter	Type	Omschrijving
user.id	tekenreeks	Optioneel. Kanaalspecifieke id van de gebruiker om te coderen binnen het token. Voor een Direct Line-gebruiker moet dit beginnen met dl_. U kunt een unieke gebruikers-id maken voor elk gesprek, en voor betere beveiliging moet u deze id onguessable maken.
user.name	tekenreeks	Optioneel. De weergavevriendelijke naam van de gebruiker om te coderen binnen het token.
trustedOrigins	tekenreeksmatrix	Optioneel. Een lijst met vertrouwde domeinen die in het token moeten worden ingesloten. Dit zijn de domeinen die de Webchat-client van de bot kunnen hosten. Dit moet overeenkomen met de lijst op de pagina Direct Line-configuratie voor uw bot.

Respons

Als de aanvraag is geslaagd, bevat het antwoord een token geldige waarde voor één gesprek en een expires_in waarde die het aantal seconden aangeeft totdat het token verloopt. Om het token bruikbaar te houden, moet u het token vernieuwen voordat het verloopt.

HTTP/1.1 200 OK
[other headers]

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

Token genereren versus gesprek starten

De bewerking Token genereren (POST /v3/directline/tokens/generate) is vergelijkbaar met de bewerking Gesprek starten (POST /v3/directline/conversations) omdat beide bewerkingen een token bewerking retourneren die kan worden gebruikt voor toegang tot één gesprek. In tegenstelling tot de bewerking Gesprek starten, start de bewerking Token genereren het gesprek echter niet, neemt u geen contact op met de bot en maakt u geen streaming WebSocket-URL.

Als u van plan bent het token te distribueren naar clients en wilt dat ze het gesprek starten, gebruikt u de bewerking Token genereren. Als u het gesprek onmiddellijk wilt starten, gebruikt u in plaats daarvan de bewerking Gesprek starten.

Een Direct Line-token vernieuwen

Een Direct Line-token kan een onbeperkt aantal keren worden vernieuwd, zolang het niet is verlopen. Een verlopen token kan niet worden vernieuwd. Als u een Direct Line-token wilt vernieuwen, voert u deze aanvraag uit:

POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer TOKEN_TO_BE_REFRESHED

Vervang in de Authorization header van deze aanvraag TOKEN_TO_BE_REFRESHED door het token direct line dat u wilt vernieuwen.

De volgende fragmenten bevatten een voorbeeld van de vernieuwingstokenaanvraag en het antwoord.

Aanvragen

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

Respons

Als de aanvraag is geslaagd, bevat het antwoord een nieuw token dat geldig is voor hetzelfde gesprek als het vorige token en een expires_in waarde die het aantal seconden aangeeft totdat het nieuwe token verloopt. Als u het nieuwe token nuttig wilt houden, moet u het token vernieuwen voordat het verloopt.

HTTP/1.1 200 OK
[other headers]

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

Verificatie van Azure AI Bot Service

De informatie die in deze sectie wordt weergegeven, is gebaseerd op het artikel Verificatie toevoegen aan uw bot via azure AI Bot Service .

Met Azure AI Bot Service-verificatie kunt u gebruikers verifiëren voor en toegangstokens ophalen van verschillende id-providers, zoals Microsoft Entra-id, GitHub, Uber, enzovoort. U kunt ook verificatie configureren voor een aangepaste OAuth2-id-provider . Hiermee kunt u één stukje verificatiecode schrijven die werkt voor alle ondersteunde id-providers en kanalen. Ga als volgt te werk om deze mogelijkheden te gebruiken:

1. Statisch configureren settings op uw bot die de details van uw toepassingsregistratie bij een id-provider bevat.
2. Gebruik een OAuthCard, ondersteund door de toepassingsgegevens die u in de vorige stap hebt opgegeven, om een gebruiker aan te melden.
3. Toegangstokens ophalen via azure AI Bot Service-API.

Beveiligingsoverwegingen

Wanneer u Azure AI Bot Service-verificatie met Webchat gebruikt, zijn er enkele belangrijke beveiligingsoverwegingen waarmee u rekening moet houden.

1. Imitatie. Imitatie is wanneer een aanvaller de bot overtuigt dat de aanvaller iemand anders is. In Webchat kan een aanvaller iemand anders imiteren door de gebruikers-id van het Webchat exemplaar te wijzigen. Om imitatie te voorkomen, raden we aan botontwikkelaars de gebruikers-id onprokenbaar te maken.

   Als u verbeterde verificatieopties inschakelt, kan Azure AI Bot Service elke wijziging van de gebruikers-id verder detecteren en negeren. Dit betekent dat de gebruikers-id (Activity.From.Id) voor berichten van Direct Line naar uw bot altijd hetzelfde is als degene waarmee u de Webchat hebt geïnitialiseerd. Deze functie vereist dat de gebruikers-id begint met dl_.

   Notitie

   Wanneer een User.Id wordt opgegeven tijdens het uitwisselen van een geheim voor een token, wordt die User.Id in het token ingesloten. Direct Line zorgt ervoor dat de berichten die naar de bot worden verzonden, die id hebben als de From.Id van de activiteit. Als een client een bericht verzendt naar Direct Line met een andere From.Id, wordt dit gewijzigd in de id in het token voordat het bericht naar de bot wordt doorgestuurd. U kunt dus geen andere gebruikers-id gebruiken nadat een kanaalgeheim is geïnitialiseerd met een gebruikers-id

2. Gebruikersidentiteiten. Elke gebruiker heeft meerdere gebruikersidentiteiten:

   1. De identiteit van de gebruiker in een kanaal.
   2. De identiteit van de gebruiker in een id-provider waarin de bot geïnteresseerd is.

Wanneer een bot gebruiker A in een kanaal vraagt zich aan te melden bij een id-provider P, moet het aanmeldingsproces ervoor zorgen dat gebruiker A degene is die zich aanmeldt bij P. Als een andere gebruiker B zich mag aanmelden, heeft gebruiker A toegang tot de resource van de gebruiker B via de bot. In Webchat hebben we twee mechanismen om ervoor te zorgen dat de juiste gebruiker zich aanmeldt, zoals hierna wordt beschreven.

1. Aan het einde van de aanmelding werd de gebruiker in het verleden een willekeurig gegenereerde zescijferige code (magic code) gepresenteerd. De gebruiker moet deze code typen in het gesprek dat de aanmelding heeft gestart om het aanmeldingsproces te voltooien. Dit mechanisme leidt meestal tot een slechte gebruikerservaring. Daarnaast is het nog steeds vatbaar voor phishingaanvallen. Een kwaadwillende gebruiker kan een andere gebruiker misleiden om zich aan te melden en de magic-code te verkrijgen via phishing.

2. Vanwege de problemen met de vorige benadering heeft Azure AI Bot Service de noodzaak voor de magic-code verwijderd. Azure AI Bot Service garandeert dat het aanmeldingsproces alleen kan worden voltooid in dezelfde browsersessie als de Webchat zelf. Als u deze beveiliging wilt inschakelen, moet u als botontwikkelaar beginnen Webchat met een Direct Line-token met een lijst met vertrouwde domeinen die de Webchat-client van de bot kunnen hosten. Voorheen kon u dit token alleen verkrijgen door een niet-gedocumenteerde optionele parameter door te geven aan de Direct Line-token-API. Met verbeterde verificatieopties kunt u nu statisch de lijst met vertrouwde domeinen (oorsprong) opgeven op de pagina Direct Line-configuratie.

Zie Verificatie toevoegen aan uw bot via Azure AI Bot Service voor meer informatie.

Codevoorbeelden

De volgende .NET-controller werkt met verbeterde verificatieopties ingeschakeld en retourneert een Direct Line Token en gebruikers-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; }
}

De volgende JavaScript-controller werkt met verbeterde verificatieopties ingeschakeld en retourneert een Direct Line Token en gebruikers-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');
        }
    });
});

Aanvullende informatie

• Belangrijke concepten
• een bot Verbinding maken naar Directe lijn
• Verificatie toevoegen aan uw bot via Azure AI Bot Service