Egyszeri bejelentkezés hozzáadása robothoz

A KÖVETKEZŐKRE VONATKOZIK: SDK v4

Ez a cikk bemutatja, hogyan használható az egyszeri bejelentkezés (SSO) funkció egy robotban. Ehhez ez a funkció egy fogyasztói robotot ( más néven gyökér- vagy szülőrobotot) használ egy képesség- vagy gyermekrobottal való interakcióhoz. Ez a cikk a gyökérrobot és a készségrobot kifejezéseket használja.

Ha SSO-támogatással rendelkezik, a felhasználók identitásszolgáltatóval jelentkezhetnek be a gyökérrobotba, és nem kell újra bejelentkeznie, amikor a vezérlés átad egy képességet.

A gyökér- és képességrobotok különálló robotok, amelyek potenciálisan különböző kiszolgálókon futnak, és mindegyik saját külön memóriával és állapottal rendelkezik. A készségekkel kapcsolatos további információkért tekintse meg a készségek áttekintését és a képesség implementálását ismertető témakört. A felhasználói hitelesítéssel kapcsolatos további információkért tekintse meg a Bot Framework hitelesítési alapjait, a felhasználói hitelesítést és a hitelesítés hozzáadása robothoz című témakört.

Fontos

Ha azure AI Bot Service-hitelesítést használ webchat, figyelembe kell vennie néhány fontos biztonsági szempontot. További információkért tekintse meg a REST-hitelesítésről szóló cikk biztonsági szempontokat ismertető szakaszát.

Előfeltételek

• A robot alapismereteinek, az állapotkezelésnek és az egyszeri bejelentkezésnek a ismerete.
• A Párbeszédtár ismerete és a szekvenciális beszélgetési folyamat implementálása és a párbeszédpanelek újrafelhasználása
• Az Azure és az OAuth 2.0 fejlesztésének ismerete.
• Visual Studio 2019 vagy újabb a .NET-hez.
• Az egyszeri bejelentkezés egyszerű képességfelhasználóval és C#-beli szakértelemmel.

Tudnivalók a mintáról

Ez a cikk két robotra hivatkozik: a RootBotra és a SkillBotra. A RootBot továbbítja a tevékenységeket a SkillBotnak. Ezt a tipikus készségforgatókönyvet modellezhetik:

• A gyökérrobot egy vagy több készségrobotot hív meg.
• A gyökér- és képességrobotok egyaránt implementálják a Hitelesítés hozzáadása robothoz című cikkben leírt alapszintű hitelesítést.
• A felhasználó bejelentkezik a gyökérrobotba.
• Az egyszeri bejelentkezés és a gyökérrobotba való bejelentkezés miatt a rendszer anélkül jelentkezik be a képességrobotba, hogy újra felhasználói beavatkozást kellene igényelnie.

A Bot Framework hitelesítésének kezelésével kapcsolatos áttekintésért tekintse meg a felhasználói hitelesítést. Az egyszeri bejelentkezés háttérinformációiért lásd az egyszeri bejelentkezést.

A RootBot támogatja az egyszeri bejelentkezést. A felhasználó nevében kommunikál a SkillBottal anélkül, hogy a felhasználónak újra hitelesítenie kellene magát a _SkillBot.

A mintában szereplő összes projekthez a következőkre van szükség:

1. Egy Microsoft Entra ID-alkalmazás, amely regisztrál egy roboterőforrást az Azure-ban.
2. Egy Microsoft Entra id identitásszolgáltatói alkalmazás hitelesítéshez.

   Feljegyzés

   Jelenleg csak a Microsoft Entra-azonosítójú identitásszolgáltató támogatott.

Az Azure RootBot-erőforrás létrehozása

1. Azure-roboterőforrás létrehozása az Azure Portalon a RootBot. Kövesse az Azure-roboterőforrás létrehozása című cikkben leírt lépéseket.
2. Másolja és mentse a robotregisztrációs alkalmazás azonosítóját és az ügyfél titkos kódját.

A Microsoft Entra ID-identitás létrehozása a RootBothoz

A Microsoft Entra ID egy felhőalapú identitásszolgáltatás, amely lehetővé teszi olyan alkalmazások létrehozását, amelyek biztonságosan bejelentkeznek a felhasználókba az olyan iparági szabvány protokollok használatával, mint az OAuth2.0.

1. Hozzon létre egy identitásalkalmazást, amely a RootBot Microsoft Entra-azonosítót használja a felhasználó hitelesítéséhez. Kövesse a Microsoft Entra id-identitásszolgáltató létrehozása című cikkben leírt lépéseket.

2. A bal oldali panelen válassza a Jegyzék elemet.

3. Állítsa be accessTokenAcceptedVersion a 2 értéket.

4. Válassza a Mentés lehetőséget.

5. A bal oldali panelen válassza az API-k felfedése lehetőséget.

6. A jobb oldali panelen válassza a Hatókör hozzáadása lehetőséget.

7. A jobb szélső Hatókör hozzáadása szakaszban válassza a Mentés és folytatás lehetőséget.

8. A megjelenített ablakban, a Ki tud hozzájárulni? területen válassza a Rendszergazdák és felhasználók lehetőséget.

9. Adja meg a többi szükséges információt.

10. Válassza a Hatókör hozzáadása lehetőséget.

11. Másolja és mentse a hatókör értékét.

OAuth-kapcsolatbeállítás létrehozása a RootBothoz

1. Hozzon létre egy Microsoft Entra-azonosító kapcsolatot a RootBot robotregisztrációban, és adja meg a Microsoft Entra ID-ban és az alább leírt értékben leírt értékeket.

2. Hagyja üresen a token Exchange URL-címét .

3. A Hatókörök mezőbe írja be az RootBot előző lépésekben mentett hatókörértéket.

   Feljegyzés

   A hatókörök tartalmazzák azt az URL-címet, amelyet a felhasználó először bejelentkezik a gyökérrobotba, míg a tokencsere URL-címe üres marad.

   Tegyük fel például, hogy a gyökérrobot-alkalmazásazonosító rootAppId, a skill bot appid pedig skillAppId. A gyökérrobot hatókörei úgy fognak kinézni, mint a api://rootAppId/customScope, amely a felhasználó bejelentkezésére szolgál. Ez a gyökérrobot hatókörei az egyszeri bejelentkezés során api://skillAppId/customscope lesznek kicserélve.

4. Másolja és mentse a kapcsolat nevét.

Az Azure SkillBot-erőforrás létrehozása

1. Azure-roboterőforrás létrehozása az Azure Portalon a SkillBot. Kövesse az Azure-roboterőforrás létrehozása című cikkben leírt lépéseket.
2. Másolja és mentse a robotregisztrációs alkalmazás azonosítóját és az ügyfél titkos kódját.

A Microsoft Entra ID-identitás létrehozása a SkillBothoz

A Microsoft Entra ID egy felhőalapú identitásszolgáltatás, amely lehetővé teszi olyan alkalmazások létrehozását, amelyek biztonságosan bejelentkeznek a felhasználókba az olyan iparági szabvány protokollok használatával, mint az OAuth2.0.

1. Hozzon létre egy identitásalkalmazást, amely a SkillBot Microsoft Entra ID-t használja a robot hitelesítéséhez. Kövesse a Microsoft Entra id-identitásszolgáltató létrehozása című cikkben leírt lépéseket.

2. A bal oldali panelen válassza a Jegyzék elemet.

3. Állítsa be accessTokenAcceptedVersion a 2 értéket.

4. Válassza a Mentés lehetőséget.

5. A bal oldali panelen válassza az API-k felfedése lehetőséget.

6. A jobb oldali panelen válassza a Hatókör hozzáadása lehetőséget.

7. A jobb szélső Hatókör hozzáadása szakaszban válassza a Mentés és folytatás lehetőséget.

8. A megjelenített ablakban, a Ki tud hozzájárulni? területen válassza a Rendszergazdák és felhasználók lehetőséget.

9. Adja meg a többi szükséges információt.

10. Válassza a Hatókör hozzáadása lehetőséget.

11. Másolja és mentse a hatókör értékét.

12. Válassza az Ügyfélalkalmazás hozzáadása lehetőséget. A jobb szélső szakaszban, az Ügyfélazonosító mezőben adja meg a Korábban mentett RootBot identitásalkalmazás-azonosítót . Győződjön meg arról, hogy a RootBot-identitást használja, és nem a regisztrációs alkalmazás azonosítóját.

    Feljegyzés

    Ügyfélalkalmazások esetén az Azure AI Bot Service nem támogatja az egyszeri adást a Microsoft Entra ID B2C-identitásszolgáltatóval.

13. Az Engedélyezett hatókör csoportban jelölje be a jelölőnégyzetet a hatókör értéke szerint.

14. Válassza az Alkalmazás hozzáadása lehetőséget.

15. A bal oldali navigációs panelen válassza az API-engedélyeket. Ajánlott eljárás az alkalmazás API-engedélyeinek explicit beállítása.

    1. A jobb oldali panelen válassza az Engedély hozzáadása lehetőséget.

    2. Válassza a Microsoft API-kat , majd a Microsoft Graphot.

    3. Válassza a Delegált engedélyek lehetőséget , és győződjön meg arról, hogy a szükséges engedélyek ki vannak választva. Ehhez a mintához az alábbi engedélyek szükségesek.

       Feljegyzés

       A RENDSZERGAZDAI HOZZÁJÁRULÁS KÖTELEZŐként megjelölt engedélyekhez a felhasználónak és a bérlő rendszergazdának is be kell jelentkeznie.

       • openid
       • profil
       • User.Read
       • User.ReadBasic.All

    4. Jelölje be az Engedélyek hozzáadása lehetőséget.

OAuth-kapcsolatbeállítás létrehozása a SkillBothoz

1. Hozzon létre egy Microsoft Entra-azonosító kapcsolatot a SkillBot robotregisztrációban, és adja meg a Microsoft Entra ID-ban és az alább leírt értékeket.

2. A Token Exchange URL-címmezőjében adja meg az SkillBot előző lépésekben mentett hatókörértéket.

3. A Hatókörök mezőbe írja be a következő értékeket üres szóközzel elválasztva: profile User.ReadBasic.All User.Read openid.

4. Másolja és mentse egy fájlba a kapcsolat nevét.

A kapcsolat tesztelése

1. Válassza ki a kapcsolati bejegyzést a létrehozott kapcsolat megnyitásához.
2. Válassza a Kapcsolat tesztelése lehetőséget a Szolgáltatói kapcsolat beállítása panel tetején.
3. Első alkalommal meg kell nyitnia egy új böngészőlapot, amely felsorolja az alkalmazás által kért engedélyeket, és kérni fogja, hogy fogadja el.
4. Válassza az Elfogadás lehetőséget.
5. Ennek ezután át kell irányítania egy tesztkapcsolatra a <kapcsolat neve> Sikeres lapra.

További információ: Microsoft Entra ID for developers (v1.0) – áttekintés és Microsoft Identitásplatform (2.0-s verzió) áttekintése. A v1 és a v2 végpontok közötti különbségekről további információt a Miért frissít a Microsoft Identitásplatform (2.0-s verzió)?. További információ: Microsoft Identitásplatform (korábban Microsoft Entra-azonosító fejlesztőknek).

A mintakód előkészítése

A fájlt mindkét appsettings.json mintában frissítenie kell az alábbiak szerint.

1. Klónozza az egyszeri bejelentkezést a GitHub-adattárból származó Egyszerű képességfelhasználó és szakértelem mintával.

2. Nyissa meg a SkillBot projektfájlt appsettings.json . Rendelje hozzá a következő értékeket a mentett fájlból:

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

3. Nyissa meg a RootBot projektfájlt appsettings.json . Rendelje hozzá a következő értékeket a mentett fájlból:

   {
       "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"
               }
           ]
   }
   

A minták tesztelése

A teszteléshez használja a következőket:

• RootBot Parancsok

  • login segítségével a felhasználó bejelentkezhet a Microsoft Entra-azonosító regisztrációjába a RootBot. Bejelentkezés után az egyszeri bejelentkezés gondoskodik a bejelentkezésről SkillBot is. A felhasználónak nem kell újra bejelentkeznie.
  • token megjeleníti a felhasználó jogkivonatát.
  • logout kijelentkezteti a felhasználót a RootBotrendszerből.

• SkillBot Parancsok

  • skill login lehetővé teszi a RootBot felhasználó nevében történő SkillBotbejelentkezést. A felhasználó nem jelenik meg bejelentkezési kártyán, ha már bejelentkezett, kivéve, ha az egyszeri bejelentkezés sikertelen.
  • skill token megjeleníti a felhasználó jogkivonatát a SkillBot.
  • skill logout kijelentkezteti a felhasználót a SkillBot

Feljegyzés

Amikor a felhasználók először próbálják ki az egyszeri bejelentkezést egy képességen, előfordulhat, hogy OAuth-kártyával jelentkeznek be. Ennek az az oka, hogy még nem járultak hozzá a képesség Microsoft Entra ID alkalmazásához. Ennek elkerülése érdekében rendszergazdai hozzájárulást adhatnak a Microsoft Entra ID alkalmazás által kért gráfengedélyekhez.

Emulátor

Ha még nem tette meg, telepítse a Bot Framework Emulatort. Lásd még : Hibakeresés az Emulátorsal.

Konfigurálnia kell az Emulatort a robotminta-bejelentkezés működéséhez. Kövesse az alábbi lépéseket: az Emulátor konfigurálása hitelesítéshez című témakörben leírtak szerint.

A hitelesítési mechanizmus konfigurálása után elvégezheti a tényleges robotminta-tesztelést.

1. A Visual Studióban nyissa meg a SSOWithSkills.sln megoldást, és konfigurálja úgy, hogy több folyamattal kezdje el a hibakeresést.

2. Kezdje el helyileg a hibakeresést a számítógépen. Figyelje meg, hogy aRootBot projektfájlban appsettings.json a következő beállításokat használja:

   "SkillHostEndpoint": "http://localhost:3978/api/skills/"
   "SkillEndpoint": "http://localhost:39783/api/messages"
   

   Feljegyzés

   Ezek a beállítások azt jelentik, hogy mindkettővel RootBot és SkillBot a helyi gépen futnak. Az Emulator a RootBot 3978-at, a 39783-at pedig RootBot SkillBot a 39783-at. Amint elkezdi a hibakeresést, két alapértelmezett böngészőablak nyílik meg. Az egyik a 3978-as porton, a másik a 39783-at.

3. Indítsa el az Emulátort.

4. Amikor csatlakozik a robothoz, adja meg a RootBot regisztrációs alkalmazás azonosítóját és jelszavát.

5. Írja be hi a beszélgetés indításához.

6. Adja meg a bejelentkezést. Ekkor RootBot megjelenik egy bejelentkezés az AAD-hitelesítési kártyára.

   

7. Válassza a Bejelentkezés lehetőséget. Megjelenik az előugró párbeszédpanel , amelyen a Megnyitás megerősítése URL-cím jelenik meg.

   

8. Válassza a Megerősítés elemet. A rendszer bejelentkezik, és megjelenik a RootBot jogkivonat.

9. A jogkivonat ismételt megjelenítéséhez adja meg a jogkivonatot .

   

   Most már készen áll a kommunikációra a SkillBot. Miután bejelentkezett a RootBothasználatával, nem kell újból megadnia a hitelesítő adatait, amíg ki nem jelentkezik. Ez azt mutatja, hogy az egyszeri bejelentkezés működik.

10. Írja be a készségbeléptetést az Emulátor mezőbe. A rendszer nem fogja kérni, hogy jelentkezzen be újra. Ehelyett megjelenik a SkillBot-jogkivonat.

11. Adja meg a képesség jogkivonatát a jogkivonat ismételt megjelenítéséhez.

12. Most már beírhatja a képességnaplót a kijelentkezéshez.SkillBot Ezután adja meg a kijelentkezés elemet a kijelentkezéshez.SimpleRootBoot

webchat

1. Telepítse a gyökérrobotot és a képességrobotot az Azure-ban. További információ : Oktatóanyag: Robot üzembe helyezése az Azure-ban és oktatóanyag: Alapszintű robot közzététele.

2. A kódszerkesztőben, például a Visual Studióban cserélje le a projektfájl appsetting.js localhost-címét RootBot a tényleges Microsoft Entra IDdresses-címekre az alább látható módon.

   "SkillHostEndpoint": "https://<your root bot deployed name>.azurewebsites.net/api/skills"
   "SkillEndpoint": "https://<your skill bot deployed name>.azurewebsites.net/api/messages"
   

3. Nyissa meg a böngészőjében az Azure Portalt.

4. Nyissa meg a gyökérrobot-regisztrációt. A bal oldali panelen válassza a Tesztelés lehetőséget a webchat. A gyökérrobotot tartalmazó párbeszédpanel a robot üdvözlő üzenetével jelenik meg.

5. Indítsa el a beszélgetést a robottal például a hi beírásával. A robot vissza fogja visszhangozni az üzenetet.

6. Adja meg a bejelentkezést. Ekkor RootBot megjelenik egy bejelentkezés az AAD-hitelesítési kártyára.

   

7. Válassza a Bejelentkezés lehetőséget. Megjelenik egy érvényesítési kódot tartalmazó weblap.

8. A bejelentkezés befejezéséhez másolja ki a kódot, és írja be a beviteli mezőbe. Megjelenik RootBot a jogkivonat.

9. A jogkivonat ismételt megjelenítéséhez adja meg a jogkivonatot .

   

   Most már készen áll a kommunikációra a SkillBot. Miután bejelentkezett, RootBotnem kell újból megadnia a hitelesítő adatait, amíg ki nem jelentkezik. Ez azt mutatja, hogy az egyszeri bejelentkezés működik.

10. Adja meg a képesség bejelentkezését. Megjelenik a SkillBot-jogkivonat.

11. Adja meg a képesség jogkivonatát a jogkivonat ismételt megjelenítéséhez. Ez azt jelzi, hogy anélkül kommunikál a SkillBot felhasználóval, hogy újra be kellene jelentkeznie. SSO működés közben!

12. Most már beírhatja a képességnaplót a kijelentkezéshez.SkillBot Ezután adja meg a kijelentkezés elemet a kijelentkezéshez.SimpleRootBoot

További információk

Az alábbi idősordiagram a cikkben használt mintákra vonatkozik, és a különböző érintett összetevők közötti interakciót mutatja be. Az ABS az Azure AI Bot Service-t jelenti.

1. Az első alkalommal a felhasználó megadja a login RootBot parancsát.
2. A RootBot egy OAuthCardot küld, amely arra kéri a felhasználót, hogy jelentkezzen be.
3. A felhasználó megadja az ABS-nek (Azure AI Bot Service) küldött hitelesítési hitelesítő adatokat.
4. Az ABS elküldi a felhasználó hitelesítő adatai alapján létrehozott hitelesítési jogkivonatot a RootBotnak.
5. A RootBot megjeleníti a felhasználó számára megjelenítendő gyökérjogkivonatot.
6. A felhasználó megadja a skill login SkillBot parancsát.
7. A SkillBot OAuthCardot küld a RootBotnak.
8. A RootBot egy cserélhető jogkivonatot kér az ABS-től.
9. Az egyszeri bejelentkezés elküldi a SkillBot skill tokent a RootBotnak.
10. A RootBot megjeleníti a felhasználó számára megjelenítendő képességkódot. Figyelje meg, hogy a képesség jogkivonata anélkül lett létrehozva, hogy a felhasználónak be kellene jelentkeznie az SKillBotba. Ennek oka az egyszeri bejelentkezés.

Az alábbi példa bemutatja, hogyan történik a tokencsere. A kód a TokenExchangeSkillHandler.cs fájlból származik.

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