Ověřování v rozhraní API direct line 3.0

Článek
10/27/2023

Klient může ověřovat požadavky na rozhraní API Direct Line 3.0 buď pomocí tajného klíče, který získáte ze stránky konfigurace kanálu Direct Line na portálu Bot Framework, nebo pomocí tokenu, který získáte za běhu. Tajný klíč nebo token by se měl zadat v Authorization hlavičce každého požadavku pomocí tohoto formátu:

Authorization: Bearer SECRET_OR_TOKEN

Tajné kódy a tokeny

Tajný kód Direct Line je hlavní klíč, který se dá použít pro přístup k jakékoli konverzaci, která patří přidruženému robotovi. Tajný kód lze také použít k získání tokenu. Platnost tajných kódů nevyprší.

Token Direct Line je klíč, který se dá použít pro přístup k jedné konverzaci. Platnost tokenu vyprší, ale dá se aktualizovat.

Rozhodnutí o tom, kdy nebo jestli použít tajný klíč nebo token , musí být založené na aspektech zabezpečení. Zveřejnění tajného klíče může být přijatelné, pokud je úmyslně provedeno a s opatrností. Ve skutečnosti se jedná o výchozí chování, protože umožňuje direct line zjistit, jestli je klient legitimní. Obecně ale platí, že zabezpečení je problém, pokud se pokoušíte zachovat uživatelská data. Další informace najdete v části Aspekty zabezpečení.

Pokud vytváříte aplikaci typu služba-služba, zadání tajného kódu v Authorization hlavičce požadavků rozhraní API direct line může být nejjednodušší přístup. Pokud píšete aplikaci, ve které klient běží ve webovém prohlížeči nebo mobilní aplikaci, můžete chtít vyměnit tajný kód za token (který funguje jenom pro jednu konverzaci a vyprší, pokud se neaktualizuje) a zadat token v Authorization hlavičce požadavků rozhraní API Direct Line. Zvolte model zabezpečení, který vám nejlépe vyhovuje.

Poznámka:

Přihlašovací údaje klienta Direct Line se liší od přihlašovacích údajů robota. To vám umožní nezávisle upravovat klíče a umožňuje sdílet tokeny klienta bez zveřejnění hesla robota.

Získání tajného kódu Direct Line

Tajný kód Direct Line můžete získat prostřednictvím stránky konfigurace kanálu Direct Line pro robota na webu Azure Portal:

Direct Line configuration

Vygenerování tokenu Direct Line

Pokud chcete vygenerovat token Direct Line, který se dá použít pro přístup k jedné konverzaci, nejprve získejte tajný kód Direct Line ze stránky konfigurace kanálu Direct Line na webu Azure Portal. Pak tento požadavek na výměnu tajného klíče Direct Line pro token Direct Line:

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

Authorization V hlavičce tohoto požadavku nahraďte SECRET hodnotou vašeho tajného kódu Direct Line.

Následující fragmenty kódu poskytují příklad požadavku a odpovědi vygenerovat token.

Požádat

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

Datová část požadavku, která obsahuje parametry tokenu, je volitelná, ale doporučuje se. Při generování tokenu, který lze odeslat zpět do služby Direct Line, zadejte následující datovou část, aby bylo připojení bezpečnější. Zahrnutím těchto hodnot může Direct Line provést dodatečné ověření zabezpečení ID uživatele a jména, což brání manipulaci s těmito hodnotami škodlivými klienty. Zahrnutím těchto hodnot se také zlepšuje schopnost Direct Line posílat aktivitu aktualizace konverzace, což umožňuje okamžitě po připojení uživatele ke konverzaci vygenerovat aktualizaci konverzace. Pokud tyto informace nejsou zadané, musí uživatel odeslat obsah, aby mohl direct line odeslat aktualizaci konverzace.

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

Parametr	Typ	Description
`user.id`	řetězec	Nepovinné. ID konkrétního kanálu uživatele, které se má kódovat v tokenu. Pro uživatele Direct Line to musí začínat `dl_`na . Pro každou konverzaci můžete vytvořit jedinečné ID uživatele a pro lepší zabezpečení byste měli toto ID nastavit jako nepřesné.
`user.name`	řetězec	Nepovinné. Zobrazovaný popisný název uživatele, který se má kódovat v tokenu.
`trustedOrigins`	Řetězcové pole	Nepovinné. Seznam důvěryhodných domén pro vložení do tokenu Jedná se o domény, které můžou hostovat klienta Webový chat robota. Měl by se shodovat se seznamem na stránce konfigurace Direct Line pro vašeho robota.

Odpověď

Pokud je požadavek úspěšný, odpověď obsahuje token hodnotu platnou pro jednu konverzaci a expires_in hodnotu, která označuje počet sekund, dokud nevyprší platnost tokenu. Aby token zůstal užitečný, musíte obnovit token, než vyprší.

HTTP/1.1 200 OK
[other headers]

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

Generování tokenů a zahájení konverzace

Operace Generovat token (POST /v3/directline/tokens/generate) se podobá operaci Zahájit konverzaci (POST /v3/directline/conversations) v tom, že obě operace vrací token možnost, která se dá použít pro přístup k jedné konverzaci. Na rozdíl od operace Zahájit konverzaci ale operace Generovat token nespustí konverzaci, nekontaktuje robota a nevytvoří streamovanou adresu URL protokolu WebSocket.

Pokud plánujete distribuovat token klientům a chcete, aby zahájili konverzaci, použijte operaci Generovat token. Pokud chcete konverzaci zahájit okamžitě, použijte místo toho operaci Zahájit konverzaci .

Aktualizace tokenu Direct Line

Token Direct Line se dá aktualizovat neomezeným počtem, pokud nevypršela jeho platnost. Token s vypršenou platností nejde aktualizovat. Pokud chcete aktualizovat token Direct Line, zadejte tento požadavek:

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

Authorization V hlavičce tohoto požadavku nahraďte TOKEN_TO_BE_REFRESHED tokenem Direct Line, který chcete aktualizovat.

Následující fragmenty kódu poskytují příklad požadavku a odpovědi obnovovacího tokenu.

Požádat

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

Odezva

Pokud je požadavek úspěšný, odpověď obsahuje novou token konverzaci platnou pro stejnou konverzaci jako předchozí token a expires_in hodnotu, která označuje počet sekund, dokud nevyprší platnost nového tokenu. Aby nový token zůstal užitečný, musíte ho před vypršením platnosti aktualizovat.

HTTP/1.1 200 OK
[other headers]

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

Ověřování azure AI Bot Service

Informace uvedené v této části vycházejí z článku o přidání ověřování do robota prostřednictvím služby Azure AI Bot Service .

Ověřování Azure AI Bot Service umožňuje ověřovat uživatele a získávat přístupové tokeny od různých zprostředkovatelů identity, jako je Microsoft Entra ID, GitHub, Uber atd. Můžete také nakonfigurovat ověřování pro vlastního zprostředkovatele identity OAuth2 . To vše vám umožní napsat jeden ověřovací kód , který funguje ve všech podporovaných zprostředkovatelích identit a kanálech. Pokud chcete použít tyto možnosti:

Staticky nakonfigurujte settings robota, který obsahuje podrobnosti o registraci vaší aplikace u zprostředkovatele identity.
OAuthCardK přihlášení uživatele použijte informace o aplikaci, které jste zadali v předchozím kroku.
Načtěte přístupové tokeny prostřednictvím rozhraní API služby Azure AI Bot Service.

Bezpečnostní aspekty

Pokud s Webový chat používáte ověřováníAzure AI Bot Service, je potřeba mít na paměti některé důležité aspekty zabezpečení.

Zosobnění. Zosobnění je, když útočník přesvědčí robota, že útočník je někdo jiný. V Webový chat může útočník zosobnit někoho jiného změnou ID uživatele Webový chat instance. Aby se zabránilo zosobnění, doporučujeme, aby vývojáři robotů znepřístupňovali ID uživatele.

Pokud povolíte rozšířené možnosti ověřování , azure AI Bot Service může dále zjišťovat a odmítat všechny změny ID uživatele. To znamená, že ID uživatele (Activity.From.Id) u zpráv z přímého řádku do robota bude vždy stejné jako ID uživatele, se kterým jste inicializovali Webový chat. Tato funkce vyžaduje, aby ID uživatele začínalo dl_.

Poznámka:

Když se při výměně tajného kódu pro token poskytne User.Id, User.Id se do tokenu vloží. Direct Line zajišťuje, aby zprávy odeslané robotovi měly toto ID jako From.Id aktivity. Pokud klient odešle zprávu do direct line s jinou From.Id, změní se na ID v tokenu před předáním zprávy robotovi. Proto nemůžete použít jiné ID uživatele po inicializaci tajného kódu kanálu s ID uživatele.
Identity uživatelů. Každý uživatel má více identit uživatelů:
1. Identita uživatele v kanálu.
2. Identita uživatele ve zprostředkovateli identity, o kterého se robot zajímá.

Když robot požádá uživatele A v kanálu, aby se přihlásil k poskytovateli identity P, musí proces přihlášení zajistit, aby uživatel A je ten, který se přihlašuje k P. Pokud se k přihlášení může přihlásit jiný uživatel B, uživatel A by měl přístup k prostředku uživatele B prostřednictvím robota. V Webový chat máme dva mechanismy pro zajištění toho, aby se správný uživatel přihlásil, jak je popsáno dále.

Na konci přihlášení se uživateli zobrazil náhodně vygenerovaný 6místný kód (magický kód). Uživatel musí zadat tento kód do konverzace, která iniciovala přihlášení, aby se dokončil proces přihlášení. Tento mechanismus má tendenci vést k špatnému uživatelskému prostředí. Kromě toho je stále náchylný k útokům phishing. Uživatel se zlými úmysly může oklamat jiného uživatele, aby se přihlásil a získal magický kód prostřednictvím útoku phishing.
Kvůli problémům s předchozím přístupem služba Azure AI Bot Service odebrala potřebu magického kódu. Služba Azure AI Bot Service zaručuje, že proces přihlašování je možné dokončit pouze ve stejné relaci prohlížeče jako samotný Webový chat. Pokud chcete tuto ochranu povolit jako vývojář robota, musíte spustit Webový chat pomocí tokenu Direct Line, který obsahuje seznam důvěryhodných domén, které můžou hostovat klienta Webový chat robota. Předtím byste tento token mohli získat pouze předáním nezdokumentovaného volitelného parametru rozhraní API tokenu Direct Line. Teď s rozšířenými možnostmi ověřování můžete staticky zadat seznam důvěryhodných domén (původu) na stránce konfigurace direct line.

Další informace najdete v tématu Přidání ověřování do robota prostřednictvím služby Azure AI Bot Service.

Příklady kódu

Následující kontroler .NET funguje s povolenými rozšířenými možnostmi ověřování a vrací token direct line a ID uživatele.

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

Následující kontroler JavaScriptu funguje s povolenými rozšířenými možnostmi ověřování a vrací token direct line a ID uživatele.

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

Ověřování v rozhraní API direct line 3.0

Tajné kódy a tokeny

Získání tajného kódu Direct Line

Vygenerování tokenu Direct Line

Požádat

Odpověď

Generování tokenů a zahájení konverzace

Aktualizace tokenu Direct Line

Požádat

Odezva

Ověřování azure AI Bot Service

Bezpečnostní aspekty

Příklady kódu

Další informace

Další materiály