Eenmalige aanmelding toevoegen aan een bot

Artikel
10/27/2023

VAN TOEPASSING OP: SDK v4

In dit artikel wordt beschreven hoe u de functie voor eenmalige aanmelding (SSO) in een bot gebruikt. Hiervoor gebruikt deze functie een consumentenbot, ook wel de hoofd- of bovenliggende bot genoemd, om te communiceren met een vaardigheid of onderliggende bot. In dit artikel worden de termen hoofdbot en vaardigheidsbot gebruikt.

Als u ondersteuning voor eenmalige aanmelding opneemt, kan een gebruiker zich aanmelden bij de hoofdbot met behulp van een id-provider en hoeft hij zich niet opnieuw aan te melden wanneer het besturingselement wordt doorgegeven aan een vaardigheid.

De hoofd- en vaardigheidsbots zijn afzonderlijke bots, die worden uitgevoerd op mogelijk verschillende servers, elk met een eigen afzonderlijk geheugen en een eigen status. Zie Vaardighedenoverzicht en Een vaardigheid implementeren voor meer informatie over vaardigheden. Zie basisbeginselen van Bot Framework-verificatie, gebruikersverificatie en verificatie toevoegen aan een bot voor meer informatie over gebruikersverificatie.

Belangrijk

Wanneer u Azure AI Bot Service-verificatie gebruikt met Webchat, zijn er enkele belangrijke beveiligingsoverwegingen waarmee u rekening moet houden. Zie de sectie beveiligingsoverwegingen in het artikel over REST-verificatie voor meer informatie.

Vereisten

Kennis van basisbeginselen van Bot, Status beheren en Over eenmalige aanmelding.
Kennis van de dialoogvensterbibliotheek en het implementeren van de sequentiële gespreksstroom en het opnieuw gebruiken van dialoogvensters
Kennis van Azure- en OAuth 2.0-ontwikkeling.
Visual Studio 2019 of hoger voor .NET.
De eenmalige aanmelding met eenvoudige vaardigheid consument en vaardigheid in C#.

Over het voorbeeld

Dit artikel verwijst naar twee bots: de RootBot en de SkillBot. De RootBot stuurt activiteiten door naar de SkillBot. Ze modelleren dit typische vaardigheidsscenario:

Een hoofdbot roept een of meer vaardigheidsbots aan.
Zowel de hoofd- als vaardigheidsbots implementeren de basisverificatie die wordt beschreven in het artikel Verificatie toevoegen aan een bot .
De gebruiker meldt zich aan bij de hoofdbot.
Vanwege eenmalige aanmelding en al zijn aangemeld bij de hoofdbot, worden ze aangemeld bij de vaardigheidsbot zonder tussenkomst van de gebruiker.

Zie Gebruikersverificatie voor een overzicht van hoe bot framework verificatie afhandelt. Zie Eenmalige aanmelding voor achtergrondinformatie voor eenmalige aanmelding.

RootBot biedt ondersteuning voor eenmalige aanmelding. Het communiceert namens de gebruiker met de SkillBot , zonder dat de gebruiker opnieuw moet worden geverifieerd bij de _SkillBot.

Voor elk project in het voorbeeld hebt u het volgende nodig:

Een Microsoft Entra ID-toepassing voor het registreren van een botresource in Azure.
Een Microsoft Entra ID-id-providertoepassing voor verificatie.

Notitie

Op dit moment wordt alleen de Id-provider van Microsoft Entra ID ondersteund.

De Azure RootBot-resource maken

Maak een Azure-botresource in Azure Portal voor de RootBot. Volg de stappen die worden beschreven in Een Azure-botresource maken.
Kopieer en sla de app-id voor botregistratie en het clientgeheim op.

De Microsoft Entra ID-identiteit voor RootBot maken

De Microsoft Entra-id is een cloudidentiteitsservice waarmee u toepassingen kunt bouwen die gebruikers veilig aanmelden met behulp van industriestandaardprotocollen zoals OAuth2.0.

Maak een identiteitstoepassing voor de RootBot toepassing die gebruikmaakt van Microsoft Entra ID om de gebruiker te verifiëren. Volg de stappen die worden beschreven in De Id-provider van Microsoft Entra-id maken.
Selecteer Manifest in het linkerdeelvenster.
Ingesteld accessTokenAcceptedVersion op 2.
Selecteer Opslaan.
Selecteer een API beschikbaar maken in het linkerdeelvenster.
Selecteer Een bereik toevoegen in het rechterdeelvenster.
Selecteer aan de rechterkant Een bereiksectie toevoegen de optie Opslaan en doorgaan.
Selecteer beheerders en gebruikers in het weergegeven venster onder Wie kan toestemming geven?.
Voer de resterende vereiste gegevens in.
Selecteer Bereik toevoegen.
Kopieer en sla de bereikwaarde op.

Een OAuth-verbindingsinstelling maken voor RootBot

Maak een Microsoft Entra ID-verbinding in de RootBot botregistratie en voer waarden in zoals beschreven in Microsoft Entra-id en de hieronder beschreven waarde.
Laat de Exchange-URL van het token leeg.
Voer in het vak Bereiken de RootBot bereikwaarde in die u in de vorige stappen hebt opgeslagen.

Notitie

Bereiken bevatten de URL die de gebruiker zich in eerste instantie aanmeldt bij de hoofdbot, terwijl tokenuitwisselings-URL leeg blijft.

Laten we er bijvoorbeeld van uitgaan dat de appid van de hoofdbot rootAppId is en dat de appid van de vaardigheidsbot skillAppId skillAppId is. De bereiken van de hoofdbot zien eruit als api://rootAppId/customScope, die wordt gebruikt om de gebruiker aan te melden. De bereiken van deze hoofdbot worden vervolgens uitgewisseld met api://skillAppId/customscope tijdens eenmalige aanmelding.
Kopieer en sla de naam van de verbinding op.

De Azure SkillBot-resource maken

Maak een Azure-botresource in Azure Portal voor de SkillBot. Volg de stappen die worden beschreven in Een Azure-botresource maken.
Kopieer en sla de app-id voor botregistratie en het clientgeheim op.

De Microsoft Entra ID-identiteit voor SkillBot maken

De Microsoft Entra-id is een cloudidentiteitsservice waarmee u toepassingen kunt bouwen die gebruikers veilig aanmelden met behulp van industriestandaardprotocollen zoals OAuth2.0.

Maak een identiteitstoepassing voor de SkillBot toepassing die gebruikmaakt van Microsoft Entra ID om de bot te verifiëren. Volg de stappen die worden beschreven in De Id-provider van Microsoft Entra-id maken.
Selecteer Manifest in het linkerdeelvenster.
Ingesteld accessTokenAcceptedVersion op 2.
Selecteer Opslaan.
Selecteer een API beschikbaar maken in het linkerdeelvenster.
Selecteer Een bereik toevoegen in het rechterdeelvenster.
Selecteer in de rechterbovenhoek Een bereiksectie toevoegen de optie Opslaan en doorgaan.
Selecteer beheerders en gebruikers in het weergegeven venster onder Wie kan toestemming geven.
Voer de resterende vereiste gegevens in.
Selecteer Bereik toevoegen.
Kopieer en sla de bereikwaarde op.
Selecteer Een clienttoepassing toevoegen. Voer in de sectie uiterst rechts in het vak Client-id de id-id van de RootBot-identiteit in die u eerder hebt opgeslagen. Zorg ervoor dat u de RootBot-identiteit gebruikt en niet de id van de registratie-app.

Notitie

Voor clienttoepassingen biedt Azure AI Bot Service geen ondersteuning voor eenmalige sing-on met de Microsoft Entra ID B2C-id-provider.
Schakel onder Geautoriseerd bereik het selectievakje in op de bereikwaarde.
Selecteer Toepassing toevoegen.
Selecteer API-machtigingen in het navigatiedeelvenster aan de linkerkant. Het is een best practice om expliciet de API-machtigingen voor de app in te stellen.
1. Selecteer een machtiging toevoegen in het rechterdeelvenster.
2. Selecteer Microsoft-API's en vervolgens Microsoft Graph.
3. Kies Gedelegeerde machtigingen en zorg ervoor dat de machtigingen die u nodig hebt, zijn geselecteerd. Voor dit voorbeeld zijn de onderstaande machtigingen vereist.
  
  Notitie
  
  Voor elke machtiging die is gemarkeerd als BEHEERDERSTOESTEMMING VEREIST , moeten zowel een gebruiker als een tenantbeheerder zich aanmelden.
  - openid
  - profiel
  - User.Read
  - User.ReadBasic.All
4. Selecteer Machtigingen toevoegen.

Een OAuth-verbindingsinstelling maken voor SkillBot

Maak een Microsoft Entra ID-verbinding in de SkillBot botregistratie en voer waarden in zoals beschreven in Microsoft Entra-id en de onderstaande waarden.
Voer in het vak Exchange-URL van token de SkillBot bereikwaarde in die u in de vorige stappen hebt opgeslagen.
Voer in het vak Bereiken de volgende waarden in, gescheiden door lege ruimte: profile User.ReadBasic.All User.Read openid.
Kopieer en sla deze op in een bestand met de naam van de verbinding.

Test de verbinding

Selecteer de verbindingsvermelding om de verbinding te openen die u hebt gemaakt.
Selecteer Verbinding testen bovenaan het deelvenster Verbindingsinstelling van de serviceprovider.
De eerste keer opent u een nieuw browsertabblad met de machtigingen die uw app aanvraagt en vraagt u om te accepteren.
Selecteer Accepteren.
U wordt dan omgeleid naar een pagina Test connection naar <de pagina Geslaagde verbinding>.

Zie het overzicht van Microsoft Entra ID voor ontwikkelaars (v1.0) en het overzicht van Het Microsoft Identity Platform (v2.0) voor meer informatie. Zie Waarom bijwerken naar Het Microsoft Identity Platform (v2.0)? voor informatie over de verschillen tussen de v1- en v2-eindpunten. Zie Microsoft Identity Platform (voorheen Microsoft Entra ID voor ontwikkelaars) voor volledige informatie.

De voorbeeldcode voorbereiden

U moet het appsettings.json bestand in beide voorbeelden bijwerken, zoals hieronder wordt beschreven.

Kloon de SSO met Simple Skill Consumer and Skill Sample vanuit de GitHub-opslagplaats.

Open het SkillBot projectbestand appsettings.json . Wijs de volgende waarden toe uit het opgeslagen bestand:

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

Open het RootBot projectbestand appsettings.json . Wijs de volgende waarden toe uit het opgeslagen bestand:

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

De voorbeelden testen

Gebruik het volgende om te testen:

RootBot Opdrachten
- login staat de gebruiker toe zich aan te melden bij de registratie van de Microsoft Entra-id met behulp van de RootBot. Zodra u zich hebt aangemeld, zorgt SSO ervoor dat u zich SkillBot ook aanmeldt. De gebruiker hoeft zich niet opnieuw aan te melden.
- token geeft het token van de gebruiker weer.
- logout registreert de gebruiker buiten de RootBot.
SkillBot Opdrachten
- skill login staat de gebruiker toe RootBot zich aan te melden bij de SkillBot, namens de gebruiker. De gebruiker wordt geen aanmeldingskaart weergegeven, als deze al is aangemeld, tenzij eenmalige aanmelding mislukt.
- skill token geeft het token van de gebruiker weer van de SkillBot.
- skill logout registreert de gebruiker uit de SkillBot

Notitie

De eerste keer dat gebruikers eenmalige aanmelding proberen uit te voeren op een vaardigheid, kunnen ze een OAuth-kaart zien om zich aan te melden. Dit komt doordat ze nog geen toestemming hebben gegeven voor de Microsoft Entra ID-app van de vaardigheid. Om dit te voorkomen, kunnen ze beheerderstoestemming verlenen voor eventuele grafiekmachtigingen die zijn aangevraagd door de Microsoft Entra ID-app.

Emulator
Webchat

Als u dit nog niet hebt gedaan, installeert u de Bot Framework Emulator. Zie ook Fouten opsporen met de emulator.

U moet de emulator configureren voor de aanmelding met het botvoorbeeld om te kunnen werken. Gebruik de onderstaande stappen: zoals wordt weergegeven in De emulator configureren voor verificatie.

Nadat u het verificatiemechanisme hebt geconfigureerd, kunt u het daadwerkelijke testvoorbeeld van de bot uitvoeren.

Open de oplossing in Visual Studio en configureer deze SSOWithSkills.sln om te beginnen met foutopsporing met meerdere processen.
Start de foutopsporing lokaal op uw computer. U ziet dat u in hetRootBot projectbestand appsettings.json de volgende instellingen hebt:
```
"SkillHostEndpoint": "http://localhost:3978/api/skills/"
"SkillEndpoint": "http://localhost:39783/api/messages"
```
Notitie

Deze instellingen impliceren dat, met beide RootBot en SkillBot worden uitgevoerd op de lokale computer. De emulator communiceert met RootBot poort 3978 en RootBot communiceert met SkillBot poort 39783. Zodra u de foutopsporing start, worden er twee standaardbrowservensters geopend. Een op poort 3978 en de andere op poort 39783.
Start de emulator.
Wanneer u verbinding maakt met de bot, voert u uw RootBot registratie-app-id en wachtwoord in.
Typ hi om het gesprek te starten.
Voer de aanmelding in. Er RootBot wordt een aanmeldingskaart voor AAD-verificatie weergegeven.
Selecteer Aanmelden. Het pop-updialoogvenster Bevestig dat de open URL wordt weergegeven.
Selecteer Bevestigen. U wordt aangemeld en het RootBot token wordt weergegeven.
Voer het token in om het token opnieuw weer te geven.

Nu bent u klaar om te communiceren met de SkillBot. Nadat u zich hebt aangemeld met behulp van de RootBotservice, hoeft u uw referenties pas opnieuw op te geven nadat u zich hebt afgemeld. Dit laat zien dat eenmalige aanmelding werkt.
Voer vaardigheidsaanmelding in het vak Emulator in. U wordt niet gevraagd u opnieuw aan te melden. In plaats daarvan wordt het SkillBot-token weergegeven.
Voer het vaardigheidstoken in om het token opnieuw weer te geven.
U kunt nu vaardigheidsuitloging invoeren om u af te melden bij de SkillBot. Voer vervolgens afmelding in om u af te melden bij de SimpleRootBoot.

Implementeer de hoofdbot en de vaardigheidsbot in Azure. Zie Zelfstudie: Een bot inrichten in Azure en zelfstudie: Een basisbot publiceren voor meer informatie.
Vervang in uw code-editor, bijvoorbeeld Visual Studio, de localhost-adressen in het RootBot projectbestand appsetting.js door de werkelijke Microsoft Entra-ip-adressen, zoals hieronder wordt weergegeven.
```
"SkillHostEndpoint": "https://<your root bot deployed name>.azurewebsites.net/api/skills"
"SkillEndpoint": "https://<your skill bot deployed name>.azurewebsites.net/api/messages"
```
Ga in een browser naar de Azure-portal.
Open de registratie van uw hoofdbot. Selecteer in het linkerdeelvenster Testen in Webchat. Het dialoogvenster met uw hoofdbot wordt weergegeven met het begroetingsbericht van de bot.
Start het gesprek met de bot door bijvoorbeeld hallo in te voeren. De bot echot uw bericht terug.
Voer de aanmelding in. Er RootBot wordt een aanmeldingskaart voor AAD-verificatie weergegeven.
Selecteer Aanmelden. Er wordt een webpagina met een validatiecode weergegeven.
Als u het aanmelden wilt voltooien, kopieert u de code en voert u deze in het invoervak in. Het RootBot token wordt weergegeven.
Voer het token in om het token opnieuw weer te geven.

Nu bent u klaar om te communiceren met de SkillBot. Nadat u zich hebt aangemeld RootBot, hoeft u uw referenties pas opnieuw op te geven nadat u zich hebt afgemeld. Dit laat zien dat eenmalige aanmelding werkt.
Voer aanmeldingsgegevens voor vaardigheden in. Het SkillBot-token wordt weergegeven.
Voer het vaardigheidstoken in om het token opnieuw weer te geven. Dit geeft aan dat u communiceert met de SkillBot verbinding zonder dat u zich opnieuw hoeft aan te melden. Eenmalige aanmelding in actie!
U kunt nu vaardigheidsuitloging invoeren om u af te melden bij de SkillBot. Voer vervolgens afmelding in om u af te melden bij de SimpleRootBoot.

Aanvullende informatie

Het volgende tijdsreeksdiagram is van toepassing op de voorbeelden die in het artikel worden gebruikt en toont de interactie tussen de verschillende betrokken onderdelen. ABS staat voor Azure AI Bot Service.

Sequentiediagram waarin de vaardigheidstokenstroom wordt geïllustreerd.

De eerste keer voert de gebruiker de login opdracht voor de RootBot in.
De RootBot verzendt een OAuthCard waarin de gebruiker wordt gevraagd zich aan te melden.
De gebruiker voert de verificatiereferenties in die worden verzonden naar de ABS (Azure AI Bot Service).
De ABS verzendt het verificatietoken, gegenereerd op basis van de referenties van de gebruiker, naar de RootBot.
De RootBot geeft het hoofdtoken weer dat de gebruiker kan zien.
De gebruiker voert de skill login opdracht voor de SkillBot in.
De SkillBot verzendt een OAuthCard naar de RootBot.
De RootBot vraagt om een uitwisselbaar token van ABS.
Met eenmalige aanmelding wordt het SkillBot-vaardigheidstoken naar de RootBot verzonden.
De RootBot geeft het vaardigheidstoken weer dat de gebruiker kan zien. U ziet dat het vaardigheidstoken is gegenereerd zonder dat de gebruiker zich moet aanmelden bij de SKillBot. Dit komt door eenmalige aanmelding.

In het volgende voorbeeld ziet u hoe de tokenuitwisseling plaatsvindt. De code is afkomstig uit het TokenExchangeSkillHandler.cs-bestand .

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

Delen via