Lägga till enkel inloggning i en robot

GÄLLER FÖR: SDK v4

Den här artikeln visar hur du använder funktionen enkel inloggning (SSO) i en robot. För att göra det använder den här funktionen en konsumentrobot, även kallad rotroboten eller den överordnade roboten, för att interagera med en kunskaps- eller underordnad robot. Den här artikeln använder termerna rotrobot och kunskapsrobot.

Om du har stöd för enkel inloggning kan en användare logga in på rotroboten med hjälp av en identitetsprovider och behöver inte logga in igen när kontrollen skickas till en färdighet.

Rotrobotarna och kunskapsrobotarna är separata robotar som körs på potentiellt olika servrar, var och en med sitt eget separata minne och tillstånd. Mer information om färdigheter finns i Kunskapsöversikt och Implementera en färdighet. Mer information om användarautentisering finns i Grunderna för Bot Framework-autentisering, Användarautentisering och Lägg till autentisering i en robot.

Viktigt!

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å. Mer information finns i avsnittet säkerhetsöverväganden i artikeln REST-autentisering.

Förutsättningar

• Kunskap om grunderna i roboten, hantera tillstånd och om enkel inloggning.
• Kunskap om dialogrutebiblioteket och hur du implementerar sekventiellt konversationsflöde och återanvändningsdialogrutor
• Kunskap om Azure- och OAuth 2.0-utveckling.
• Visual Studio 2019 eller senare för .NET.
• Enkel inloggning med enkel kunskapskonsument och kompetens i C#.

Om exemplet

Den här artikeln refererar till två robotar: RootBot och SkillBot. RootBot vidarebefordrar aktiviteter till SkillBot. De modellerar det här typiska kunskapsscenariot:

• En rotrobot anropar en eller flera kunskapsrobotar.
• Både rotrobotarna och kunskapsrobotarna implementerar den grundläggande autentisering som beskrivs i artikeln Lägg till autentisering i en robot .
• Användaren loggar in på rotroboten.
• På grund av enkel inloggning och att de redan är inloggade i rotroboten loggas de in på kunskapsroboten utan att användaren behöver interagera igen.

En översikt över hur Bot Framework hanterar autentisering finns i Användarautentisering. Bakgrundsinformation för enkel inloggning finns i Enkel inloggning.

RootBot stöder enkel inloggning. Den kommunicerar med SkillBot för användarens räkning, utan att användaren behöver autentiseras igen i _SkillBot.

För varje projekt i exemplet behöver du följande:

1. Ett Microsoft Entra-ID-program för att registrera en robotresurs i Azure.
2. Ett Microsoft Entra ID-identitetsproviderprogram för autentisering.

   Kommentar

   För närvarande stöds endast Microsoft Entra ID-identitetsprovidern .

Skapa Azure RootBot-resursen

1. Skapa en Azure-robotresurs i Azure Portal för RootBot. Följ stegen som beskrivs i Skapa en Azure-robotresurs.
2. Kopiera och spara robotregistreringsappens ID och klienthemligheten.

Skapa Microsoft Entra-ID-identiteten för RootBot

Microsoft Entra ID är en molnidentitetstjänst som gör att du kan skapa program som loggar in användare på ett säkert sätt med hjälp av branschstandardprotokoll som OAuth2.0.

1. Skapa ett identitetsprogram för RootBot det som använder Microsoft Entra-ID för att autentisera användaren. Följ stegen som beskrivs i Skapa Microsoft Entra ID-identitetsprovidern.

2. I den vänstra rutan väljer du Manifest.

3. Ange accessTokenAcceptedVersion till 2.

4. Välj Spara.

5. I den vänstra rutan väljer du Exponera ett API.

6. I den högra rutan väljer du Lägg till ett omfång.

7. Längst till höger Lägg till ett omfångsavsnitt väljer du Spara och fortsätt.

8. I fönstret som visas, under Vem kan samtycka?, väljer du Administratörer och användare.

9. Ange återstående nödvändig information.

10. Välj Lägg till definitionsområde.

11. Kopiera och spara omfångsvärdet.

Skapa en OAuth-anslutningsinställning för RootBot

1. Skapa en Microsoft Entra-ID-anslutning i robotregistreringen RootBot och ange värden enligt beskrivningen i Microsoft Entra-ID och värdet som beskrivs nedan.

2. Lämna Token Exchange-URL:en tom.

3. I rutan Omfång anger du det RootBot omfångsvärde som du sparade i föregående steg.

   Kommentar

   Omfång innehåller den URL som användaren först loggar in i rotroboten, medan tokenutbytes-URL:en lämnas tom.

   Anta till exempel att rotrobotappid är rootAppId och att kunskapsrobotappid är skillAppId. Rotrobotens omfång ser ut som api://rootAppId/customScope, som används för att logga in på användaren. Rotrobotens omfång utbyts sedan med api://skillAppId/customscope under enkel inloggning.

4. Kopiera och spara namnet på anslutningen.

Skapa Azure SkillBot-resursen

1. Skapa en Azure-robotresurs i Azure Portal för SkillBot. Följ stegen som beskrivs i Skapa en Azure-robotresurs.
2. Kopiera och spara robotregistreringsappens ID och klienthemligheten.

Skapa Microsoft Entra ID-identiteten för SkillBot

Microsoft Entra ID är en molnidentitetstjänst som gör att du kan skapa program som loggar in användare på ett säkert sätt med hjälp av branschstandardprotokoll som OAuth2.0.

1. Skapa ett identitetsprogram för SkillBot som använder Microsoft Entra-ID för att autentisera roboten. Följ stegen som beskrivs i Skapa Microsoft Entra ID-identitetsprovidern.

2. I den vänstra rutan väljer du Manifest.

3. Ange accessTokenAcceptedVersion till 2.

4. Välj Spara.

5. I den vänstra rutan väljer du Exponera ett API.

6. I den högra rutan väljer du Lägg till ett omfång.

7. I avsnittet Lägg till omfång längst till höger väljer du Spara och fortsätt.

8. I fönstret som visas under Vem kan samtycka? väljer du Administratörer och användare.

9. Ange återstående nödvändig information.

10. Välj Lägg till definitionsområde.

11. Kopiera och spara omfångsvärdet.

12. Välj Lägg till ett klientprogram. I det längst till höger-avsnittet går du till rutan Klient-ID och anger rotrobotens identitetsapp-ID som du sparade tidigare. Kontrollera att du använder RootBot-identiteten och inte registreringsappens ID.

    Kommentar

    För klientprogram stöder Azure AI Bot Service inte enkel sing-on med Microsoft Entra ID B2C-identitetsprovidern.

13. Markera kryssrutan efter omfångsvärdet under Auktoriserat omfång.

14. Välj Lägg till program.

15. I navigeringsfönstret till vänster väljer du API-behörigheter. Det är en bra idé att uttryckligen ange API-behörigheterna för appen.

    1. I den högra rutan väljer du Lägg till en behörighet.

    2. Välj Microsoft API:er och sedan Microsoft Graph.

    3. Välj Delegerade behörigheter och kontrollera att de behörigheter du behöver är markerade. Det här exemplet kräver de behörigheter som anges nedan.

       Kommentar

       Alla behörigheter som har markerats som ADMINISTRATÖRSMEDGIVANDE KRÄVS kräver att både en användare och en klientorganisationsadministratör loggar in.

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

    4. Välj Lägg till behörigheter.

Skapa en OAuth-anslutningsinställning för SkillBot

1. Skapa en Microsoft Entra-ID-anslutning i robotregistreringen SkillBot och ange värden enligt beskrivningen i Microsoft Entra-ID och de värden som beskrivs nedan.

2. I rutan Token Exchange URL anger du det SkillBot omfångsvärde som du sparade i föregående steg.

3. I rutan Omfång anger du följande värden avgränsade med tomt utrymme: profile User.ReadBasic.All User.Read openid.

4. Kopiera och spara i en fil namnet på anslutningen.

Testa anslutningen

1. Välj i anslutningsposten för att öppna anslutningen som du skapade.
2. Välj Testa anslutning överst i fönstret Anslutningsinställning för tjänstleverantör.
3. Första gången bör du öppna en ny webbläsarflik som visar de behörigheter som appen begär och uppmanar dig att acceptera.
4. Välj Godkänn.
5. Detta bör sedan omdirigera dig till en testanslutning till <sidan med ditt anslutningsnamn> Lyckades .

Mer information finns i översikten över Microsoft Entra-ID för utvecklare (v1.0) och Microsofts identitetsplattform (v2.0). Information om skillnaderna mellan v1- och v2-slutpunkterna finns i Varför uppdatera till Microsofts identitetsplattform (v2.0)?. Fullständig information finns i Microsofts identitetsplattform (tidigare Microsoft Entra-ID för utvecklare).

Förbereda exempelkoden

Du måste uppdatera filen i båda exemplen appsettings.json enligt beskrivningen nedan.

1. Klona enkel inloggning med exempel på enkel kompetenskonsument och kunskap från GitHub-lagringsplatsen.

2. SkillBot Öppna projektfilenappsettings.json. Tilldela följande värden från den sparade filen:

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

3. RootBot Öppna projektfilenappsettings.json. Tilldela följande värden från den sparade filen:

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

Testa exemplen

Använd följande för testning:

• RootBot Kommandon

  • login tillåter användaren att logga in på Microsoft Entra ID-registreringen med hjälp av RootBot. När du har loggat in tar SSO hand om inloggningen till den SkillBot också. Användaren behöver inte logga in igen.
  • token visar användarens token.
  • logout loggar ut användaren från RootBot.

• SkillBot Kommandon

  • skill loginRootBot tillåter att logga in SkillBotpå , för användarens räkning. Användaren visas inte ett inloggningskort, om det redan är loggat in, såvida inte enkel inloggning misslyckas.
  • skill token visar användarens token från SkillBot.
  • skill logout loggar ut användaren från SkillBot

Kommentar

Första gången användarna provar enkel inloggning på en färdighet kan de få ett OAuth-kort för att logga in. Detta beror på att de ännu inte har gett sitt medgivande till färdighetens Microsoft Entra-ID-app. För att undvika detta kan de bevilja administratörsmedgivande för alla grafbehörigheter som begärs av Microsoft Entra-ID-appen.

Emulator

Om du inte redan har gjort det installerar du Bot Framework-emulatorn. Se även Felsöka med emulatorn.

Du måste konfigurera emulatorn för att robotexempelinloggningen ska fungera. Följ stegen nedan: som du ser i Konfigurera emulatorn för autentisering.

När du har konfigurerat autentiseringsmekanismen kan du utföra den faktiska robotexempletestningen.

1. Öppna lösningen i Visual Studio och konfigurera den SSOWithSkills.sln så att den börjar felsöka med flera processer.

2. Börja felsöka lokalt på datorn. Observera att du har följande inställningar iRootBot projektfilen appsettings.json :

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

   Kommentar

   De här inställningarna innebär att, med båda RootBot och SkillBot körs på den lokala datorn. Emulatorn kommunicerar med RootBot på port 3978 och RootBot kommunicerar med SkillBot på port 39783. Så fort du börjar felsöka öppnas två standardfönster i webbläsaren. En på port 3978 och den andra på port 39783.

3. Starta emulatorn.

4. När du ansluter till roboten anger du ditt RootBot registreringsapp-ID och lösenord.

5. Skriv hi för att starta konversationen.

6. Ange inloggning. RootBot Visar ett inloggningskort för AAD-autentisering.

   

7. Välj Logga in. Popup-dialogrutan Bekräfta att öppna URL visas.

   

8. Välj Bekräfta. Du kommer att loggas in och RootBot token visas.

9. Ange token för att visa token igen.

   

   Nu är du redo att kommunicera med SkillBot. När du har signerat med behöver RootBotdu inte ange dina autentiseringsuppgifter igen förrän du har loggat ut. Detta visar att enkel inloggning fungerar.

10. Ange kunskapsinloggning i rutan Emulator. Du uppmanas inte att logga in igen. I stället visas SkillBot-token.

11. Ange kunskapstoken för att visa token igen.

12. Nu kan du ange färdighetsutloggning för att logga ut från SkillBot. Ange sedan utloggning för att logga ut från SimpleRootBoot.

Webbchatt

1. Distribuera rotroboten och kunskapsroboten till Azure. Mer information finns i Självstudie: Etablera en robot i Azure och Självstudie: Publicera en grundläggande robot.

2. I kodredigeraren, till exempel Visual Studio, ersätter du localhost-adresserna i RootBot projektfilen appsetting.js med de faktiska Microsoft Entra-ID:erna enligt nedan.

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

3. I en webbläsare går du till Azure-portalen.

4. Öppna din rotrobotregistrering. I den vänstra rutan väljer du Testa i Webbchatt. Dialogrutan med rotroboten visas med robothälsningsmeddelandet.

5. Starta konversationen med roboten genom att till exempel ange hej . Roboten kommer att upprepa ditt meddelande tillbaka.

6. Ange inloggning. RootBot Visar ett inloggningskort för AAD-autentisering.

   

7. Välj Logga in. En webbsida med en valideringskod visas.

8. Om du vill slutföra inloggningen kopierar du koden och anger den i indatarutan. Token RootBot visas.

9. Ange token för att visa token igen.

   

   Nu är du redo att kommunicera med SkillBot. När du har loggat in RootBotbehöver du inte ange dina autentiseringsuppgifter igen förrän du har loggat ut. Detta visar att enkel inloggning fungerar.

10. Ange kunskapsinloggning. SkillBot-token visas.

11. Ange kunskapstoken för att visa token igen. Detta anger att du kommunicerar med SkillBot utan att behöva logga in igen. Enkel inloggning i praktiken!

12. Nu kan du ange färdighetsutloggning för att logga ut från SkillBot. Ange sedan utloggning för att logga ut från SimpleRootBoot.

Ytterligare information

Följande tidssekvensdiagram gäller för de exempel som används i artikeln och visar interaktionen mellan de olika komponenter som ingår. ABS står för Azure AI Bot Service.

1. Första gången anger login användaren kommandot för RootBot.
2. RootBot skickar ett OAuthCard som ber användaren att logga in.
3. Användaren anger de autentiseringsuppgifter som skickas till ABS (Azure AI Bot Service).
4. ABS skickar autentiseringstoken, som genereras baserat på användarens autentiseringsuppgifter, till RootBot.
5. RootBot visar rottoken som användaren kan se.
6. Användaren anger skill login kommandot för SkillBot.
7. SkillBot skickar ett OAuthCard till RootBot.
8. RootBot ber om en utbytbar token från ABS.
9. Enkel inloggning skickar SkillBot-kunskapstoken till RootBot.
10. RootBot visar kunskapstoken som användaren kan se. Observera att kunskapstoken genererades utan att användaren behöver logga in på SKillBot. Detta beror på enkel inloggning.

I följande exempel visas hur tokenutbytet sker. Koden kommer från filen 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;
}