Dela via

Autentisering i Direct Line API 3.0

  • Artikel

En klient kan autentisera begäranden till Direct Line API 3.0 antingen med hjälp av en hemlighet som du hämtar från konfigurationssidan för Direct Line-kanalen i Bot Framework-portalen eller med hjälp av en token som du får vid körning. Hemligheten eller token ska anges i rubriken för Authorization varje begäran med det här formatet:

Authorization: Bearer SECRET_OR_TOKEN

Hemligheter och token

En Direct Line-hemlighet är en huvudnyckel som kan användas för att komma åt alla konversationer som tillhör den associerade roboten. En hemlighet kan också användas för att hämta en token. Hemligheter upphör inte att gälla.

En direktradstoken är en nyckel som kan användas för att komma åt en enda konversation. En token upphör att gälla men kan uppdateras.

Att bestämma när eller om du vill använda den hemliga nyckeln eller en token måste baseras på säkerhetsöverväganden. Att exponera den hemliga nyckeln kan vara acceptabelt om det görs avsiktligt och med försiktighet. Faktum är att detta är standardbeteendet eftersom detta gör att Direct Line kan ta reda på om klienten är legitim. Generellt sett är dock säkerhet ett problem om du försöker bevara användardata. Mer information finns i avsnittet Säkerhetsöverväganden.

Om du skapar ett tjänst-till-tjänst-program kan det vara enklast att ange hemligheten Authorization i rubriken för DIRECT Line API-begäranden. Om du skriver ett program där klienten körs i en webbläsare eller mobilapp kanske du vill byta ut din hemlighet mot en token (som bara fungerar för en enda konversation och upphör att gälla om den inte uppdateras) och ange token i Authorization rubriken för API-begäranden för direct line. Välj den säkerhetsmodell som passar dig bäst.

Kommentar

Dina autentiseringsuppgifter för Direct Line-klienten skiljer sig från robotens autentiseringsuppgifter. På så sätt kan du ändra dina nycklar oberoende av varandra och du kan dela klienttoken utan att avslöja robotens lösenord.

Hämta en direktlinjehemlighet

Du kan hämta en Direct Line-hemlighet via konfigurationssidan för Direct Line-kanalen för din robot i Azure-portalen:

Direct Line configuration

Generera en direktradstoken

Om du vill generera en direct line-token som kan användas för att komma åt en enda konversation hämtar du först Direct Line-hemligheten från konfigurationssidan för Direct Line-kanalen i Azure-portalen. Utfärda sedan den här begäran om att byta ut din Direct Line-hemlighet mot en direktradstoken:

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

I rubriken för den Authorization här begäran ersätter du SECRET med värdet för din Direct Line-hemlighet.

Följande kodfragment innehåller ett exempel på begäran och svar för generera token.

Begär

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

Nyttolasten för begäran, som innehåller tokenparametrarna, är valfri men rekommenderas. När du genererar en token som kan skickas tillbaka till direct line-tjänsten anger du följande nyttolast för att göra anslutningen säkrare. Genom att inkludera dessa värden kan Direct Line utföra ytterligare säkerhetsvalidering av användar-ID och namn, vilket förhindrar manipulering av dessa värden av skadliga klienter. Om du inkluderar dessa värden förbättras även Direct Line-möjligheten att skicka konversationsuppdateringsaktiviteten så att den kan generera konversationsuppdateringen omedelbart när användaren ansluter till konversationen. När den här informationen inte tillhandahålls måste användaren skicka innehåll innan Direct Line kan skicka konversationsuppdateringen.

{
  "user": {
    "id": "string",
    "name": "string"
  },
  "trustedOrigins": [
    "string"
  ]
}
Parameter Typ Description
user.id sträng Valfritt. Kanalspecifikt ID för användaren som ska kodas i token. För en Direct Line-användare måste detta börja med dl_. Du kan skapa ett unikt användar-ID för varje konversation och för bättre säkerhet bör du göra det här ID:t oformaterat.
user.name sträng Valfritt. Det visningsvänliga namnet på användaren som ska kodas i token.
trustedOrigins strängmatris Valfritt. En lista över betrodda domäner som ska bäddas in i token. Det här är de domäner som kan vara värdar för robotens Webbchatt-klient. Detta bör matcha listan på direktradskonfigurationssidan för din robot.

Response

Om begäran lyckas innehåller svaret en token som är giltig för en konversation och ett expires_in värde som anger antalet sekunder tills token upphör att gälla. För att token ska fortsätta vara användbar måste du uppdatera token innan det upphör att gälla.

HTTP/1.1 200 OK
[other headers]

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

Generera token jämfört med Starta konversation

Åtgärden Generera token (POST /v3/directline/tokens/generate) liknar åtgärden Starta konversation (POST /v3/directline/conversations) eftersom båda åtgärderna returnerar en token som kan användas för att komma åt en enda konversation. Men till skillnad från åtgärden Starta konversation startar åtgärden Generera token inte konversationen, kontaktar inte roboten och skapar ingen webSocket-URL för direktuppspelning.

Om du planerar att distribuera token till klienter och vill att de ska starta konversationen använder du åtgärden Generera token. Om du tänker starta konversationen omedelbart använder du åtgärden Starta konversation i stället.

Uppdatera en direktradstoken

En direktradstoken kan uppdateras ett obegränsat antal gånger, så länge den inte har upphört att gälla. Det går inte att uppdatera en token som har upphört att gälla. Om du vill uppdatera en direktradstoken utfärdar du den här begäran:

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

I rubriken för den Authorization här begäran ersätter du TOKEN_TO_BE_REFRESHED med den direktradstoken som du vill uppdatera.

Följande kodfragment innehåller ett exempel på begäran och svar för uppdateringstoken.

Begär

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

Svar

Om begäran lyckas innehåller svaret en ny token som är giltig för samma konversation som föregående token och ett expires_in värde som anger antalet sekunder tills den nya token upphör att gälla. För att den nya token ska förbli användbar måste du uppdatera token innan den upphör att gälla.

HTTP/1.1 200 OK
[other headers]

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

Azure AI Bot Service-autentisering

Informationen som visas i det här avsnittet baseras på artikeln Lägg till autentisering i din robot via Azure AI Bot Service .

Med Azure AI Bot Service-autentisering kan du autentisera användare till och få åtkomsttoken från olika identitetsprovidrar , till exempel Microsoft Entra ID, GitHub, Uber och så vidare. Du kan också konfigurera autentisering för en anpassad OAuth2-identitetsprovider . Allt detta gör att du kan skriva en kod för autentisering som fungerar i alla identitetsprovidrar och kanaler som stöds. Så här använder du följande funktioner:

  1. Konfigurera statiskt settings på din robot som innehåller information om din programregistrering med en identitetsprovider.
  2. Använd en OAuthCard, som backas upp av programinformationen som du angav i föregående steg, för att logga in på en användare.
  3. Hämta åtkomsttoken via Azure AI Bot Service API.

Säkerhetsfrågor

När du använder Azure AI Bot Service-autentisering med Webbchatt finns det några viktiga säkerhetsöverväganden som du måste tänka på.

  1. Personifiering. Personifiering är när en angripare övertygar roboten om att angriparen är någon annan. I Webbchatt kan en angripare personifiera någon annan genom att ändra användar-ID för sin Webbchatt-instans. För att förhindra personifiering rekommenderar vi att robotutvecklare gör användar-ID:t odokumenterat.

    Om du aktiverar förbättrade autentiseringsalternativ kan Azure AI Bot Service identifiera och avvisa ändringar i användar-ID ytterligare. Det innebär att användar-ID :t (Activity.From.Id) på meddelanden från Direct Line till roboten alltid är detsamma som det du initierade Webbchatt med. Den här funktionen kräver att användar-ID:t börjar med dl_.

    Kommentar

    När en User.Id tillhandahålls vid utbyte av en hemlighet för en token bäddas den User.Id in i token. Direct Line ser till att de meddelanden som skickas till roboten har det ID:t som aktivitetens From.Id. Om en klient skickar ett meddelande till Direct Line med en annan From.Id ändras det till ID:t i token innan meddelandet vidarebefordras till roboten. Så du kan inte använda ett annat användar-ID när en kanalhemlighet har initierats med ett användar-ID

  2. Användaridentiteter. Varje användare har flera användaridentiteter:

    1. Användarens identitet i en kanal.
    2. Användarens identitet i en identitetsprovider som roboten är intresserad av.

När en robot ber användaren A i en kanal att logga in på en identitetsprovider P måste inloggningsprocessen säkerställa att användare A är den som loggar in på P. Om en annan användare B tillåts logga in skulle användare A ha åtkomst till användare B:s resurs via roboten. I Webbchatt har vi två mekanismer för att säkerställa att rätt användare loggas in enligt beskrivningen härnäst.

  1. I slutet av inloggningen presenterades användaren tidigare med en slumpmässigt genererad 6-siffrig kod (magisk kod). Användaren måste skriva den här koden i konversationen som initierade inloggningen för att slutföra inloggningsprocessen. Den här mekanismen tenderar att resultera i en dålig användarupplevelse. Dessutom är den fortfarande känslig för nätfiskeattacker. En obehörig användare kan lura en annan användare att logga in och hämta den magiska koden via nätfiske.

  2. På grund av problemen med den tidigare metoden tog Azure AI Bot Service bort behovet av den magiska koden. Azure AI Bot Service garanterar att inloggningsprocessen endast kan slutföras i samma webbläsarsession som själva Webbchatt. Om du vill aktivera det här skyddet måste du som robotutvecklare börja Webbchatt med en direktradstoken som innehåller en lista över betrodda domäner som kan vara värd för robotens Webbchatt klient. Tidigare kunde du bara hämta den här token genom att skicka en odokumenterad valfri parameter till API:et för direktradstoken. Med förbättrade autentiseringsalternativ kan du nu statiskt ange listan över betrodda domäner (ursprung) på konfigurationssidan direktrad.

Mer information finns i Lägga till autentisering i din robot via Azure AI Bot Service.

Kodexempel

Följande .NET-kontrollant fungerar med förbättrade autentiseringsalternativ aktiverade och returnerar en direktradstoken och användar-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; }
}

Följande JavaScript-kontrollant fungerar med förbättrade autentiseringsalternativ aktiverade och returnerar en direktradstoken och användar-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');
        }
    });
});

Ytterligare information