Přidání jednotného přihlašování do robota

Článek
10/27/2023

PLATÍ PRO: SDK v4

Tento článek ukazuje, jak používat funkci jednotného přihlašování (SSO) v robotovi. K tomu tato funkce používá k interakci s dovednostmi nebo podřízenými roboty robota příjemce( označovaného také jako kořenový nebo nadřazený robot). Tento článek používá termíny kořenového robota a robota dovedností.

Pokud zahrnete podporu jednotného přihlašování, může se uživatel přihlásit k kořenovému robotovi pomocí zprostředkovatele identity a při průchodu kontrolou dovednosti se nebude muset znovu přihlásit.

Kořenové roboty a roboti dovedností jsou samostatní roboti, kteří běží na potenciálně různých serverech, z nichž každý má vlastní samostatnou paměť a stav. Další informace o dovednostech najdete v tématu Přehled dovedností a Implementace dovednosti. Další informace o ověřování uživatelů najdete v tématu Základy ověřování služby Bot Framework, Ověřování uživatelů a Přidání ověřování do robota.

Důležité

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í. Další informace najdete v části Aspekty zabezpečení v článku o ověřování REST.

Předpoklady

Znalost základů robotů, správy stavu a jednotného přihlašování
Znalost knihovny dialogových oken a implementace sekvenčního toku konverzace a opakovaného použití dialogů
Znalost vývoje pro Azure a OAuth 2.0
Visual Studio 2019 nebo novější pro .NET
Jednotné přihlašování s jednoduchými dovednostmi a dovednostmi v jazyce C#.

Informace o ukázce

Tento článek odkazuje na dva roboty: RootBot a SkillBot. RootBot předává aktivity do SkillBotu. Modelují tento typický scénář dovedností:

Kořenový robot volá jednoho nebo více robotů dovedností.
Kořenový robot i robot dovednosti implementují základní ověřování popsané v článku o přidání ověřování do robota .
Uživatel se přihlásí k kořenovému robotovi.
Vzhledem k jednotnému přihlašování a přihlášení k kořenovému robotovi se přihlásí k robotovi dovedností, aniž by musel znovu komunikovat s uživatelem.

Přehled toho, jak bot Framework zpracovává ověřování, najdete v tématu Ověřování uživatelů. Základní informace o jednotném přihlašování najdete v tématu Jednotné přihlašování.

RootBot podporuje jednotné přihlašování. Komunikuje jménem uživatele s SkillBotem , aniž by se uživatel musel znovu ověřit v _SkillBot.

Pro každý projekt v ukázce potřebujete následující:

Aplikace Microsoft Entra ID pro registraci prostředku robota v Azure.
Aplikace zprostředkovatele identity Microsoft Entra ID pro ověřování.

Poznámka:

V současné době se podporuje pouze zprostředkovatel identity Microsoft Entra ID .

Vytvoření prostředku Azure RootBot

Vytvořte prostředek robota Azure na webu Azure Portal pro službu RootBot. Postupujte podle kroků popsaných v tématu Vytvoření prostředku robota Azure.
Zkopírujte a uložte ID aplikace pro registraci robota a tajný klíč klienta.

Vytvoření identity Microsoft Entra ID pro RootBot

Microsoft Entra ID je cloudová služba identit, která umožňuje vytvářet aplikace, které bezpečně přihlašují uživatele pomocí standardních oborových protokolů, jako je OAuth2.0.

Vytvořte aplikaci identity pro RootBot uživatele, která k ověření uživatele používá ID Microsoft Entra. Postupujte podle kroků popsaných v tématu Vytvoření zprostředkovatele identity Microsoft Entra ID.
V levém podokně vyberte Manifest.
Nastavte accessTokenAcceptedVersion na hodnotu 2.
Zvolte Uložit.
V levém podokně vyberte Zveřejnit rozhraní API.
V pravém podokně vyberte Přidat obor.
Úplně vpravo Přidejte oddíl oboru , vyberte Uložit a pokračovat.
V zobrazeném okně v části Kdo může souhlasit?, vyberte Správa a uživatele.
Zadejte zbývající požadované informace.
Vyberte Přidat rozsah.
Zkopírujte a uložte hodnotu oboru.

Vytvoření nastavení připojení OAuth pro RootBot

V registraci robota vytvořte připojení RootBot Microsoft Entra ID a zadejte hodnoty popsané v ID Microsoft Entra a níže popsanou hodnotu.
Ponechte adresu URL výměny tokenů prázdnou.
Do pole Obory zadejte RootBot hodnotu oboru, kterou jste uložili v předchozích krocích.

Poznámka:

Obory obsahují adresu URL, kterou se uživatel původně přihlásí k kořenovému robotovi, zatímco adresa URL výměny tokenů je prázdná.

Předpokládejme například, že kořenový appid robota je rootAppId a id appid robota dovednosti je skillAppId. Obory kořenového robota budou vypadat jako api://rootAppId/customScope, které slouží k přihlášení uživatele. Rozsahy tohoto kořenového robota se pak vyměňují s api://skillAppId/customscope během jednotného přihlašování.
Zkopírujte a uložte název připojení.

Vytvoření prostředku Azure SkillBot

Vytvořte prostředek robota Azure na webu Azure Portal pro službu SkillBot. Postupujte podle kroků popsaných v tématu Vytvoření prostředku robota Azure.
Zkopírujte a uložte ID aplikace pro registraci robota a tajný klíč klienta.

Vytvoření identity Microsoft Entra ID pro SkillBot

Microsoft Entra ID je cloudová služba identit, která umožňuje vytvářet aplikace, které bezpečně přihlašují uživatele pomocí standardních oborových protokolů, jako je OAuth2.0.

Vytvořte aplikaci identity, SkillBot která k ověření robota používá ID Microsoft Entra. Postupujte podle kroků popsaných v tématu Vytvoření zprostředkovatele identity Microsoft Entra ID.
V levém podokně vyberte Manifest.
Nastavte accessTokenAcceptedVersion na hodnotu 2.
Zvolte Uložit.
V levém podokně vyberte Zveřejnit rozhraní API.
V pravém podokně vyberte Přidat obor.
V úplně pravé části Přidat obor vyberte Uložit a pokračovat.
V zobrazeném okně může v části Kdo souhlasit? Vyberte Správa a uživatele.
Zadejte zbývající požadované informace.
Vyberte Přidat rozsah.
Zkopírujte a uložte hodnotu oboru.
Vyberte Přidat klientskou aplikaci. V úplně pravé části zadejte do pole ID klienta ID aplikace RootBot identity, které jste si uložili dříve. Ujistěte se, že používáte identitu RootBot , a ne ID registrační aplikace.

Poznámka:

V případě klientských aplikací azure AI Bot Service nepodporuje jeden sing-on s zprostředkovatelem identity Microsoft Entra ID B2C.
V části Autorizovaný obor zaškrtněte políčko podle hodnoty oboru.
Vyberte Přidat aplikaci.
V navigačním podokně vlevo vyberte oprávnění rozhraní API. Osvědčeným postupem je explicitně nastavit oprávnění rozhraní API pro aplikaci.
1. V pravém podokně vyberte Přidat oprávnění.
2. Vyberte rozhraní Microsoft API a pak Microsoft Graph.
3. Zvolte Delegovaná oprávnění a ujistěte se, že jsou vybraná potřebná oprávnění. Tato ukázka vyžaduje níže uvedená oprávnění.
  
  Poznámka:
  
  Všechna oprávnění označená jako SOUHLAS SPRÁVCE VYŽADUJÍ přihlášení uživatele i správce tenanta.
  - Openid
  - Profil
  - User.Read
  - User.ReadBasic.All
4. Vyberte Přidat oprávnění.

Vytvoření nastavení připojení OAuth pro SkillBot

V registraci robota vytvořte připojení SkillBot Microsoft Entra ID a zadejte hodnoty popsané v ID Microsoft Entra a níže popsané hodnoty.
Do pole Adresa URL výměny tokenů zadejte SkillBot hodnotu oboru, kterou jste uložili v předchozích krocích.
Do pole Obory zadejte následující hodnoty oddělené prázdným mezerou:openidprofileUser.ReadUser.ReadBasic.All .
Zkopírujte a uložte do souboru název připojení.

Test připojení

Výběrem položky připojení otevřete připojení, které jste vytvořili.
V horní části podokna Nastavení Připojení poskytovatele služeb vyberte testovací Připojení ion.
Při prvním spuštění by se měla otevřít nová karta prohlížeče se seznamem oprávnění, která vaše aplikace požaduje, a vyzvat vás k přijetí.
Zvolte Přijmout.
To by vás pak mělo přesměrovat na testovací Připojení ion na <stránku s názvem> úspěšného připojení.

Další informace najdete v přehledu Microsoft Entra ID pro vývojáře (v1.0) a přehled platformy Microsoft Identity Platform (v2.0). Informace o rozdílech mezi koncovými body v1 a v2 najdete v tématu Proč aktualizovat platformu Microsoft Identity Platform (v2.0)?. Úplné informace najdete v tématu Microsoft Identity Platform (dříve Microsoft Entra ID pro vývojáře).

Příprava ukázkového kódu

Soubor musíte aktualizovat appsettings.json v obou ukázkách, jak je popsáno níže.

Naklonujte jednotné přihlašování pomocí ukázky Simple Skill Consumer a Skill z úložiště GitHub.

SkillBot Otevřete soubor projektuappsettings.json. Přiřaďte z uloženého souboru následující hodnoty:

{
    "MicrosoftAppId": "<SkillBot registration app ID>",
    "MicrosoftAppPassword": "<SkillBot registration password>",
    "ConnectionName": "<SkillBot connection name>",
    "AllowedCallers": [ "<RootBot registration app ID>" ]
}

RootBot Otevřete soubor projektuappsettings.json. Přiřaďte z uloženého souboru následující hodnoty:

{
    "MicrosoftAppId": "<RootBot registration app ID>",
    "MicrosoftAppPassword": "<RootBot registration password>",
    "ConnectionName": "<RootBot connection name>",
    "SkillHostEndpoint": "http://localhost:3978/api/skills/",
    "BotFrameworkSkills": [
            {
            "Id": "SkillBot",
            "AppId": "<SkillBot registration app ID>",
            "SkillEndpoint": "http://localhost:39783/api/messages"
            }
        ]
}

Testování ukázek

K testování použijte následující:

RootBot Příkazy
- login umožňuje uživateli přihlásit se k registraci MICROSOFT Entra ID pomocí nástroje RootBot. Po přihlášení se jednotné přihlašování postará také o SkillBot přihlášení. Uživatel se nemusí znovu přihlásit.
- token zobrazí token uživatele.
- logout zaprokoluje uživatele z aplikace RootBot.
SkillBot Příkazy
- skill loginRootBot umožňuje, aby se uživatel přihlásil SkillBotjménem uživatele. Pokud se jednotné přihlašování nezdaří, nezobrazí se přihlašovací karta.
- skill token zobrazí token uživatele z objektu SkillBot.
- skill logout zaprokoluje uživatele mimo SkillBot

Poznámka:

Při prvním pokusu o jednotné přihlašování se můžou uživatelé přihlásit pomocí karty OAuth. Je to proto, že ještě neudělili souhlas s aplikací Microsoft Entra ID dovednosti. Aby se tomu zabránilo, můžou udělit souhlas správce pro všechna oprávnění grafu požadovaná aplikací Microsoft Entra ID.

Emulátor
Webový chat

Pokud jste to ještě neudělali, nainstalujte bot Framework Emulator. Viz také Ladění pomocí emulátoru.

Aby ukázkové přihlášení robota fungovalo, budete muset nakonfigurovat emulátor. Použijte následující postup: jak je znázorněno v části Konfigurace emulátoru pro ověřování.

Po nakonfigurování ověřovacího mechanismu můžete provést vlastní ukázkové testování robota.

V sadě Visual Studio otevřete SSOWithSkills.sln řešení a nakonfigurujte ho tak, aby se spustilo ladění s několika procesy.
Spusťte ladění místně na svém počítači. Všimněte si, že vRootBot souboru projektu appsettings.json máte následující nastavení:
```
"SkillHostEndpoint": "http://localhost:3978/api/skills/"
"SkillEndpoint": "http://localhost:39783/api/messages"
```
Poznámka:

Tato nastavení znamenají, že s oběma RootBot a SkillBot spuštěnými na místním počítači. Emulátor komunikuje RootBot na portu 3978 a RootBot komunikuje s portem SkillBot 39783. Jakmile spustíte ladění, otevřou se dvě výchozí okna prohlížeče. Jeden na portu 3978 a druhý na portu 39783.
Spusťte emulátor.
Když se k robotovi připojíte, zadejte ID a heslo vaší RootBot registrační aplikace.
Zadáním hi zahájíte konverzaci.
Zadejte přihlášení. Zobrazí RootBot se přihlašovací karta pro ověřování AAD.
Vyberte Přihlásit se. Automaticky otevírané dialogové okno Potvrďte, že se zobrazí otevřená adresa URL .
Vyberte Potvrdit. Budete přihlášení a zobrazí se RootBot token.
Zadejte token pro opětovné zobrazení tokenu.

Teď jste připraveni komunikovat s .SkillBot Po přihlášení pomocí přihlašovacích RootBotúdajů nemusíte znovu zadávat přihlašovací údaje, dokud se neodhlásíte. To ukazuje, že jednotné přihlašování funguje.
Do pole Emulátor zadejte přihlašovací jméno dovednosti. Nebudete vyzváni, abyste se znovu přihlásili. Místo toho se zobrazí token SkillBot.
Zadejte token dovednosti a znovu ho zobrazte.
Nyní můžete zadat odhlášení dovednosti odhlásit se od SkillBot. Pak zadejte odhlášení , abyste se odhlasi z SimpleRootBootaplikace .

Nasaďte kořenového robota a robota dovedností do Azure. Další informace najdete v tématu Kurz: Zřízení robota v Azure a kurz: Publikování základního robota.
V editoru kódu, například Visual Studio, nahraďte adresy localhost v RootBot souboru projektu appsetting.js skutečnými soubory Microsoft Entra IDdresses, jak je znázorněno níže.
```
"SkillHostEndpoint": "https://<your root bot deployed name>.azurewebsites.net/api/skills"
"SkillEndpoint": "https://<your skill bot deployed name>.azurewebsites.net/api/messages"
```
V prohlížeči přejděte na web Azure Portal.
Otevřete registraci kořenového robota. V levém podokně vyberte Test v Webový chat. V dialogovém okně s kořenovým robotem se zobrazí zpráva s pozdravem robota.
Zahajte konverzaci s robotem tak, že zadáte například ahoj . Robot vrátí vaši zprávu zpět.
Zadejte přihlášení. Zobrazí RootBot se přihlašovací karta pro ověřování AAD.
Vyberte Přihlásit se. Zobrazí se webová stránka s ověřovacím kódem.
Pokud chcete dokončit přihlášení, zkopírujte kód a zadejte ho do vstupního pole. Zobrazí se RootBot token.
Zadejte token pro opětovné zobrazení tokenu.

Teď jste připraveni komunikovat s .SkillBot Jakmile se přihlásíte RootBot, nebudete muset znovu zadávat přihlašovací údaje, dokud se neodhlásíte. To ukazuje, že jednotné přihlašování funguje.
Zadejte přihlašovací jméno dovednosti. Zobrazí se token SkillBot.
Zadejte token dovednosti a znovu ho zobrazte. To vám řekne, že komunikujete s SkillBot bez nutnosti se znovu přihlásit. Jednotné přihlašování v akci!
Nyní můžete zadat odhlášení dovednosti odhlásit se od SkillBot. Pak zadejte odhlášení , abyste se odhlasi z SimpleRootBootaplikace .

Další informace

Následující diagram časového pořadí se vztahuje na ukázky použité v článku a ukazuje interakci mezi různými komponentami, které jsou součástí. ABS je zkratka pro Azure AI Bot Service.

Sequence diagram illustrating the skill token flow.

Uživatel poprvé zadá login příkaz pro RootBot.
RootBot odešle OAuthCard s žádostí uživatele, aby se přihlásil.
Uživatel zadá ověřovací přihlašovací údaje, které se posílají do služby ABS (Azure AI Bot Service).
ABS odešle ověřovací token vygenerovaný na základě přihlašovacích údajů uživatele do rootBotu.
RootBot zobrazí kořenový token pro uživatele, který se má zobrazit.
Uživatel zadá skill login příkaz pro SkillBot.
SkillBot odešle do rootBotu OAuthCard.
RootBot požádá o vyměnitelný token z ABS.
Jednotné přihlašování odešle token dovednosti SkillBotdo rootBotu.
RootBot zobrazí token dovednosti, který může uživatel zobrazit. Všimněte si, že token dovednosti se vygeneroval, aniž by se uživatel musel přihlásit k nástroji SKillBot. Důvodem je jednotné přihlašování.

Následující příklad ukazuje, jak probíhá výměna tokenů. Kód je ze souboru TokenExchangeSkillHandler.cs .

private async Task<bool> InterceptOAuthCards(ClaimsIdentity claimsIdentity, Activity activity)
{
    var oauthCardAttachment = activity.Attachments?.FirstOrDefault(a => a?.ContentType == OAuthCard.ContentType);
    if (oauthCardAttachment != null)
    {
        var targetSkill = GetCallingSkill(claimsIdentity);
        if (targetSkill != null)
        {
            var oauthCard = ((JObject)oauthCardAttachment.Content).ToObject<OAuthCard>();

            if (!string.IsNullOrWhiteSpace(oauthCard?.TokenExchangeResource?.Uri))
            {
                using (var context = new TurnContext(_adapter, activity))
                {
                    context.TurnState.Add<IIdentity>("BotIdentity", claimsIdentity);

                    // AAD token exchange
                    try
                    {
                        var result = await _tokenExchangeProvider.ExchangeTokenAsync(
                            context,
                            _connectionName,
                            activity.Recipient.Id,
                            new TokenExchangeRequest() { Uri = oauthCard.TokenExchangeResource.Uri }).ConfigureAwait(false);

                        if (!string.IsNullOrEmpty(result?.Token))
                        {
                            // If token above is null, then SSO has failed and hence we return false.
                            // If not, send an invoke to the skill with the token. 
                            return await SendTokenExchangeInvokeToSkill(activity, oauthCard.TokenExchangeResource.Id, result.Token, oauthCard.ConnectionName, targetSkill, default).ConfigureAwait(false);
                        }
                    }
                    catch
                    {
                        // Show oauth card if token exchange fails.
                        return false;
                    }

                    return false;
                }
            }
        }
    }
    return false;
}

Sdílet prostřednictvím