Hitelesítés a Direct Line API 3.0-ban

Cikk
10/27/2023

Az ügyfél hitelesítheti a Direct Line API 3.0-s verziójára irányuló kérelmeket egy titkos kód használatával, amelyet a Bot Framework Portal Direct Line-csatorna konfigurációs oldaláról szerez be, vagy egy futtatókörnyezetben beszerzett jogkivonat használatával. A titkos kulcsot vagy a jogkivonatot az Authorization egyes kérések fejlécében kell megadni az alábbi formátumban:

Authorization: Bearer SECRET_OR_TOKEN

Titkos kódok és jogkivonatok

A Közvetlen vonal titkos kódja egy főkulcs, amely a társított robothoz tartozó beszélgetések elérésére használható. A jogkivonatok beszerzéséhez titkos kód is használható. A titkos kódok nem járnak le.

A közvetlen vonal jogkivonata olyan kulcs, amely egyetlen beszélgetés eléréséhez használható. A jogkivonat lejár, de frissíthető.

Annak eldöntése, hogy mikor vagy mikor érdemes használni a titkos kulcsot vagy a jogkivonatot, biztonsági szempontokon kell alapulnia. A titkos kulcs felfedése elfogadható lehet, ha szándékosan és körültekintően történik. Ami azt illeti, ez az alapértelmezett viselkedés, mivel így a Direct Line kideríti, hogy az ügyfél jogos-e. Általánosságban elmondható azonban, hogy a biztonság aggodalomra ad okot, ha meg szeretné őrizni a felhasználói adatokat. További információkért lásd a Biztonsági szempontok című szakaszt.

Ha szolgáltatásközi alkalmazást hoz létre, a Direct Line API-kérések fejlécében szereplő Authorization titkos kód megadása a legegyszerűbb módszer lehet. Ha olyan alkalmazást ír, amelyben az ügyfél webböngészőben vagy mobilalkalmazásban fut, érdemes lehet kicserélni a titkos kódját egy jogkivonatra (amely csak egyetlen beszélgetésre működik, és csak frissítés esetén jár le), és a jogkivonatot a Direct Line API-kérések fejlécében Authorization kell megadnia. Válassza ki az Önnek legmegfelelőbb biztonsági modellt.

Megjegyzés:

A Direct Line-ügyfél hitelesítő adatai eltérnek a robot hitelesítő adataitól. Ez lehetővé teszi a kulcsok egymástól függetlenül történő felülvizsgálatát, és lehetővé teszi az ügyféljogkivonatok megosztását a robot jelszavának felfedése nélkül.

Direct Line-titkos kód lekérése

A Direct Line-titkos kód az Azure Portalon a robot Közvetlen vonal csatorna konfigurációs lapján szerezhető be:

Direct Line configuration

Közvetlen vonal jogkivonat létrehozása

Ha olyan Direct Line-jogkivonatot szeretne létrehozni, amely egyetlen beszélgetés eléréséhez használható, először szerezze be a Direct Line-titkos kódot az Azure Portal Direct Line-csatorna konfigurációs oldaláról. Ezután adja ki ezt a kérést a Direct Line-kód közvetlen vonalbeli jogkivonatra való cseréjére:

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

A kérés fejlécében cserélje le Standard kiadás Authorization CRET-et a Direct Line titkos kód értékére.

Az alábbi kódrészletek példaként szolgálnak a Jogkivonat létrehozása kérelemre és válaszra.

Kérelem

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

A jogkivonat paramétereit tartalmazó kérelem hasznos adatai nem kötelezőek, de ajánlottak. A Direct Line szolgáltatásnak visszaküldhető jogkivonat létrehozásakor adja meg az alábbi hasznos adatokat, hogy biztonságosabbá tegye a kapcsolatot. Ezeknek az értékeknek a belefoglalásával a Direct Line további biztonsági ellenőrzést végezhet a felhasználói azonosító és a név alapján, megakadályozva az értékek rosszindulatú ügyfelek általi illetéktelen módosítását. Ezen értékek belefoglalása javítja a Direct Line azon képességét is, hogy a beszélgetésfrissítési tevékenységet elküldje, lehetővé téve, hogy azonnal létrehozza a beszélgetés frissítését, amikor a felhasználó csatlakozik a beszélgetéshez. Ha ez az információ nincs megadva, a felhasználónak tartalmat kell küldenie, mielőtt a Direct Line elküldené a beszélgetés frissítését.

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

Paraméter	Típus	Description
`user.id`	sztring	Opcionális. A jogkivonaton belül kódolandó felhasználó csatornaspecifikus azonosítója. Direct Line-felhasználó esetén ennek a kezdőbetűvel `dl_`kell kezdődnie. Minden beszélgetéshez létrehozhat egy egyedi felhasználói azonosítót, és a nagyobb biztonság érdekében ezt az azonosítót nem biztonságossá kell tennie.
`user.name`	sztring	Opcionális. A jogkivonaton belül kódolni kívánt felhasználó megjeleníthető neve.
`trustedOrigins`	sztringtömb	Opcionális. A jogkivonatba beágyazandó megbízható tartományok listája. Ezek azok a tartományok, amelyek üzemeltethetik a robot webchat-ügyfelet. Ennek egyeznie kell a robot Direct Line konfigurációs oldalán található listával.

Response

Ha a kérés sikeres, a válasz egy token beszélgetésre érvényes értéket tartalmaz, és egy expires_in értéket, amely azt jelzi, hogy hány másodpercig jár le a jogkivonat. Ahhoz, hogy a jogkivonat hasznos maradjon, frissítenie kell a jogkivonatot , mielőtt lejár.

HTTP/1.1 200 OK
[other headers]

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

Jogkivonat létrehozása és beszélgetés indítása

A Jogkivonat létrehozása művelet (POST /v3/directline/tokens/generate) hasonló a Beszélgetés indítása művelethez (POST /v3/directline/conversations), mert mindkét művelet egy token olyan műveletet ad vissza, amely egyetlen beszélgetés eléréséhez használható. A Beszélgetés indítása művelettel ellentétben azonban a Token létrehozása művelet nem indítja el a beszélgetést, nem lép kapcsolatba a robottal, és nem hoz létre streamelési WebSocket URL-címet.

Ha azt tervezi, hogy elosztja a jogkivonatot az ügyfeleknek, és azt szeretné, hogy kezdeményezze a beszélgetést, használja a Token létrehozása műveletet. Ha azonnal el szeretné indítani a beszélgetést, használja inkább a Beszélgetés indítása műveletet.

Közvetlen vonal jogkivonatának frissítése

A Direct Line-jogkivonat korlátlan számú alkalommal frissíthető, feltéve, hogy még nem járt le. Lejárt jogkivonat nem frissíthető. Direct Line-jogkivonat frissítéséhez adja ki ezt a kérést:

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

A kérés fejlécében cserélje le TOKEN_TO_BE_REFRESHED Authorization a frissíteni kívánt Direct Line-jogkivonatra.

Az alábbi kódrészletek a jogkivonat frissítésére vonatkozó kérésre és válaszra mutatnak példát.

Kérelem

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

Válasz

Ha a kérés sikeres, a válasz tartalmaz egy újat token , amely érvényes az előző jogkivonattal megegyező beszélgetésre, és egy expires_in értéket, amely azt jelzi, hogy hány másodpercig tart az új jogkivonat lejárata. Ahhoz, hogy az új jogkivonat hasznos maradjon, frissítenie kell a jogkivonatot , mielőtt lejár.

HTTP/1.1 200 OK
[other headers]

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

Azure AI Bot Service-hitelesítés

Az ebben a szakaszban bemutatott információk az Azure AI Bot Service-en keresztüli hitelesítés hozzáadása a robothoz című cikken alapulnak.

Az Azure AI Bot Service-hitelesítés lehetővé teszi a felhasználók hitelesítését különböző identitásszolgáltatóktól, például a Microsoft Entra ID-től, a GitHubtól, az Ubertől stb. Egyéni OAuth2-identitásszolgáltató hitelesítését is konfigurálhatja. Mindez lehetővé teszi, hogy egy olyan hitelesítési kódot írjon, amely az összes támogatott identitásszolgáltatón és csatornán működik. A következő képességek használata:

Statikusan konfigurálja settings a robotot, amely tartalmazza az alkalmazás regisztrációjának részleteit egy identitásszolgáltatónál.
Használjon egy OAuthCard, az előző lépésben megadott alkalmazásinformációk által alátámasztott biztonsági másolatot egy felhasználó bejelentkezéséhez.
Hozzáférési jogkivonatok lekérése az Azure AI Bot Service API-val.

Biztonsági szempontok

Ha azure AI Bot Service-hitelesítést használ webchat, figyelembe kell vennie néhány fontos biztonsági szempontot.

Megszemélyesítés. Megszemélyesítés az, amikor a támadó meggyőzi a robotot, hogy a támadó valaki más. A webchat a támadó megszemélyesíthet valakit a webchat-példány felhasználói azonosítójának módosításával. A megszemélyesítés megakadályozása érdekében javasoljuk, hogy a robotfejlesztők használhatatlanná tegyék a felhasználói azonosítót.

Ha engedélyezi a bővített hitelesítési beállításokat, az Azure AI Bot Service további észleli és elutasítja a felhasználói azonosítók módosítását. Ez azt jelenti, hogy a Direct Line és a robot közötti üzenetek felhasználói azonosítója (Activity.From.Id) mindig ugyanaz lesz, mint amellyel inicializálta a webchat. Ehhez a funkcióhoz a felhasználói azonosítónak a következővel dl_kell kezdődnie: .

Megjegyzés:

Ha egy User.Id egy jogkivonat titkos kulcsának cseréje során van megadva, az User.Id beágyazódik a jogkivonatba. A Direct Line gondoskodik arról, hogy a robotnak küldött üzenetek a tevékenység From.Id azonosítóval rendelkezzenek. Ha egy ügyfél egy másik From.Id rendelkező üzenetet küld a Direct Line-nak, az a jogkivonatban szereplő azonosítóra változik, mielőtt továbbítanák az üzenetet a robotnak. Így nem használhat másik felhasználói azonosítót, miután a csatorna titkos kódját felhasználói azonosítóval inicializálták
Felhasználói identitások. Minden felhasználó több felhasználói identitást használ:
1. A felhasználó identitása egy csatornában.
2. A felhasználó identitása egy identitásszolgáltatóban, amely iránt a robot érdeklődik.

Amikor egy robot arra kéri a csatornán lévő A felhasználót, hogy jelentkezzen be a P identitásszolgáltatóba, a bejelentkezési folyamatnak biztosítania kell, hogy az A felhasználó jelentkezzen be a P-be. Ha egy másik B felhasználó is bejelentkezhet, akkor az A felhasználónak hozzáférése lenne a B felhasználó erőforrásához a roboton keresztül. A webchat két mechanizmussal biztosítjuk, hogy a megfelelő felhasználó a következő módon jelentkezzen be.

A bejelentkezés végén, a múltban a felhasználó egy véletlenszerűen generált 6 jegyű kóddal (magic code) jelent meg. A felhasználónak be kell írnia ezt a kódot a bejelentkezést kezdeményező beszélgetésbe a bejelentkezési folyamat befejezéséhez. Ez a mechanizmus általában rossz felhasználói élményt eredményez. Emellett továbbra is érzékeny az adathalászati támadásokra. A rosszindulatú felhasználók becsaphatnak egy másik felhasználót, hogy jelentkezzen be, és adathalászattal szerezze be a mágikus kódot.
Az előző megközelítéssel kapcsolatos problémák miatt az Azure AI Bot Service eltávolította a mágikus kód szükségességét. Az Azure AI Bot Service garantálja, hogy a bejelentkezési folyamat csak ugyanabban a böngésző-munkamenetben hajtható végre, mint maga a webchat. A védelem engedélyezéséhez robotfejlesztőként egy Direct Line-jogkivonattal kell kezdenie webchat, amely tartalmazza a robot webchat-ügyfél üzemeltetésére alkalmas megbízható tartományok listáját. Korábban csak úgy szerezhette be ezt a jogkivonatot, hogy átad egy nem dokumentált opcionális paramétert a Direct Line token API-nak. A továbbfejlesztett hitelesítési beállításokkal mostantól statikusan megadhatja a megbízható tartomány (forrás) listáját a Direct Line konfigurációs oldalán.

További információ: Hitelesítés hozzáadása a robothoz az Azure AI Bot Service-en keresztül.

Kódpéldák

Az alábbi .NET-vezérlő engedélyezve van a továbbfejlesztett hitelesítési lehetőségekkel, és direct line tokent és felhasználói azonosítót ad vissza.

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

Az alábbi JavaScript-vezérlő engedélyezve van a továbbfejlesztett hitelesítési lehetőségekkel, és direct line tokent és felhasználói azonosítót ad vissza.

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

Megosztás a következőn keresztül:

Hitelesítés a Direct Line API 3.0-ban

Titkos kódok és jogkivonatok

Direct Line-titkos kód lekérése

Közvetlen vonal jogkivonat létrehozása

Kérelem

Response

Jogkivonat létrehozása és beszélgetés indítása

Közvetlen vonal jogkivonatának frissítése

Kérelem

Válasz

Azure AI Bot Service-hitelesítés

Biztonsági szempontok

Kódpéldák

További információk

További források