Ajouter l’authentification unique à un bot

Article
12/21/2023

S'APPLIQUE À : SDK v4

Cet article explique comment utiliser la fonctionnalité d'authentification unique (SSO) dans un bot. Pour ce faire, cette fonctionnalité utilise un bot consommateur, également appelé bot racine ou parent, pour interagir avec une compétence ou un bot enfant. Cet article utilise les termes bot racine et bot de compétence.

Si vous incluez la prise en charge de l'authentification unique, un utilisateur peut se connecter au bot racine à l'aide d'un fournisseur d'identité et n'a pas besoin de se reconnecter lorsque le contrôle passe à une compétence.

Les bots racine et de compétence sont des bots distincts, qui s'exécutent sur des serveurs potentiellement différents, chacun avec ses propres mémoire et état. Pour plus d'informations sur les compétences, consultez les sections Vue d'ensemble des compétences et Implémenter une compétence. Pour plus d'informations sur l'authentification utilisateur, consultez Principes de base de l'authentification Bot Framework, Authentification utilisateur et Ajouter l'authentification à un bot.

Important

Quand vous utilisez l'authentification Azure AI Bot Service avec Chat Web, gardez à l'esprit certaines considérations de sécurité importantes. Pour plus d’informations, consultez la section Considérations relatives à la sécurité de l’article sur l’authentification REST.

Prérequis

Connaissance des principes de base du bot, de la gestion de l'état et de l'authentification unique.
Connaissance de la bibliothèque de dialogues et de la manière d'implémenter un flux de conversation séquentiel et de réutiliser les dialogues.
Connaissances du développement Azure et OAuth 2.0.
Visual Studio 2019 ou version ultérieure pour .NET
L'authentification unique avec un simple consommateur de compétences et des compétences en C#.

À propos de l’exemple

Cet article fait référence à deux bots : le RootBot et le SkillBot. Le RootBot transfère des activités au SkillBot. Ils modélisent ce scénario de compétence typique :

Un bot racine appelle un ou plusieurs bots de compétence.
Les bots racine et de compétence implémentent l’authentification de base décrite dans l’article Ajouter l’authentification à un bot.
L’utilisateur se connecte au bot racine.
Grâce à l'authentification unique et au fait qu'ils sont déjà connectés au bot racine, ils sont connectés au bot de compétences sans qu'une nouvelle interaction avec l'utilisateur ne soit nécessaire.

Pour obtenir une vue d'ensemble de la gestion de l'authentification par le Bot Framework, consultez Authentification de l'utilisateur. Pour obtenir des informations générales sur l'authentification unique, consultez Authentification unique.

Le RootBot prend en charge l'authentification unique. Il communique avec le SkillBot pour le compte de l'utilisateur, sans que celui-ci ait besoin de se réauthentifier auprès du _SkillBot.

Pour chaque projet de l’exemple, vous avez besoin des éléments suivants :

une application Microsoft Entra ID pour enregistrer une ressource bot dans Azure.
Une application de fournisseur d'identité Microsoft Entra ID pour l'authentification.

Remarque

Actuellement, seul le fournisseur d'identité Microsoft Entra ID est pris en charge.

Créez la ressource Azure RootBot

Créez une ressource Azure bot dans le portail Azure pour RootBot. Suivez les étapes décrites dans Créer une ressource Azure bot.
Copiez et enregistrez la clé secrète client et l’ID d’application de l’inscription de bot.

Créer l'identité d'identité Microsoft Entra pour RootBot

Microsoft Entra ID est un service d'identité en nuage qui vous permet de créer des applications qui signent en toute sécurité les utilisateurs à l'aide de protocoles standard tels que OAuth 2.0.

Créez une application d'identité pour le RootBot qui utilise Microsoft Entra ID pour authentifier l'utilisateur. Suivez les étapes décrites dans Créer le fournisseur d'identité Microsoft Entra ID.
Dans le volet gauche, sélectionnez Manifeste.
Affectez la valeur 2 à accessTokenAcceptedVersion.
Sélectionnez Enregistrer.
Dans le volet de gauche, sélectionnez Exposer une API.
Dans le volet droit, sélectionnez Ajouter une étendue.
À l'extrême droite de la section Ajouter une étendue, sélectionnez Enregistrer et continuer.
Dans la fenêtre qui s'affiche, sous Qui peut donner son consentement ?, sélectionnez Administrateurs et utilisateurs.
Entrez les autres informations requises.
Sélectionnez Ajouter une étendue.
Copiez et enregistrez la valeur d’étendue.

Créer un paramètre de connexion OAuth pour RootBot

Créez une connexion Microsoft Entra ID dans l'RootBotenregistrement du bot et saisissez les valeurs comme décrit dans Microsoft Entra ID ainsi que la valeur décrite ci-dessous.
Laissez l’URL d’échange de jeton vide.
Dans la zone Étendues, saisissez la valeur d'étendue RootBot que vous avez enregistrée au cours des étapes précédentes.

Remarque

Les étendues contiennent l'URL que l'utilisateur se connecte initialement au bot racine, tandis que l'URL d'échange de jeton est laissée vide.

Par exemple, supposons que l'appid de bot racine est rootAppId et que l'appid de bot de compétence est skillAppId. Les étendues du bot racine ressemblent à api://rootAppId/customScope, qui est utilisée pour connecter l'utilisateur. Les étendues de ce bot racine sont ensuite échangées avec api://skillAppId/customscope pendant l'authentification unique.
Copiez et enregistrez le nom de la connexion.

Créez la ressource Azure SkillBot

Créez une ressource Azure bot dans le portail Azure pour l'application SkillBot. Suivez les étapes décrites dans Créer une ressource Azure bot.
Copiez et enregistrez la clé secrète client et l’ID d’application de l’inscription de bot.

Créez l'identité d'identifiant Microsoft Entra pour SkillBot

Microsoft Entra ID est un service d'identité en nuage qui vous permet de créer des applications qui signent en toute sécurité les utilisateurs à l'aide de protocoles standard tels que OAuth 2.0.

Créez une application d'identité pour le SkillBot qui utilise Microsoft Entra ID en vue d'authentifier le bot. Suivez les étapes décrites dans Créer le fournisseur d'identité Microsoft Entra ID.
Dans le volet gauche, sélectionnez Manifeste.
Affectez la valeur 2 à accessTokenAcceptedVersion.
Sélectionnez Enregistrer.
Dans le volet de gauche, sélectionnez Exposer une API.
Dans le volet droit, sélectionnez Ajouter une étendue.
Dans la section Ajouter une étendue située à l'extrême droite, sélectionnez Enregistrer et continuer.
Dans la fenêtre qui s’affiche, sous Qui peut donner son consentement, sélectionnez Administrateurs et utilisateurs.
Entrez les autres informations requises.
Sélectionnez Ajouter une étendue.
Copiez et enregistrez la valeur d’étendue.
Sélectionnez Ajouter une application cliente. Dans la section tout à droite, dans la zone ID client, entrez l’ID d’application de l’identité RootBot que vous avez enregistrée. Veillez à utiliser l’identité RootBot et non l’ID d’application d’inscription.

Remarque

Pour les applications clientes, Azure AI Bot Service ne prend pas en charge l'authentification unique avec le fournisseur d'identité Microsoft Entra ID B2C.
Sous Étendue autorisée, cochez la case en regard de la valeur d’étendue.
Sélectionnez Ajouter une application.
Dans le volet de navigation de gauche, sélectionnez Autorisations d'API. Une bonne meilleure pratique consiste à définir explicitement les autorisations d'API pour l'application.
1. Dans le volet de droite, sélectionnez Ajouter une autorisation..
2. Sélectionnez API Microsoft, puis Microsoft Graph.
3. Choisissez Autorisations déléguées et vérifiez que les autorisations nécessaires sont sélectionnées. Cet exemple nécessite les autorisations indiquées ci-dessous.
  
  Remarque
  
  Les autorisations marquées comme Consentement administrateur requis nécessitent la connexion d’un utilisateur et d’un administrateur de locataire.
  - openid
  - profile
  - User.Read
  - User.ReadBasic.All
4. Sélectionnez Ajouter des autorisations.

Créer un paramètre de connexion OAuth pour SkillBot

Créez une connexion Microsoft Entra ID dans l'enregistrement du bot SkillBot et saisissez les valeurs comme décrit dans Microsoft Entra ID ainsi que les valeurs décrites ci-dessous.
Dans la zone URL d'échange de jeton, saisissez la valeur d'étendue SkillBot que vous avez enregistrée au cours des étapes précédentes.
Dans la zone Étendues, saisissez les valeurs suivantes séparées par un espace :profileUser.ReadUser.ReadBasic.Allopenid.
Copiez et enregistrez le nom de la connexion dans un fichier.

Tester la connexion

Sélectionnez l'entrée de la connexion pour ouvrir la connexion que vous avez créée.
En haut du volet Paramètre de connexion du fournisseur de service, sélectionnez Tester la connexion
La première fois, cette action doit ouvrir un nouvel onglet de navigateur répertoriant les autorisations que votre application demande et vous invite à accepter.
Cliquez sur Accepter.
Cette action doit vous rediriger vers une page indiquant que Tester la connexion à <votre-nom-de-connexion> a réussie.

Pour plus d'informations, consultez la vue d'ensemble de Microsoft Entra ID pour les développeurs (v1.0) et la vue d'ensemble de la plateforme d'identité Microsoft (v2.0). Pour plus d’informations sur les différences entre les points de terminaison v1 et v2, consultez Pourquoi opérer une mise à jour vers la Plateforme d’identités Microsoft (v2.0) ?. Pour plus d'informations, consultez Plateforme d'identité Microsoft (anciennement Microsoft Entra ID pour les développeurs).

Préparer le code des exemples

Vous devez mettre à jour le fichier appsettings.json dans les deux exemples comme décrit ci-dessous.

Clonez l'échantillon de l'authentification unique avec le consommateur de compétences simples et les compétences à partir du référentiel GitHub.

Ouvrez le fichier appsettings.json du projet SkillBot. Attribuez les valeurs suivantes à partir du fichier enregistré :

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

Ouvrez le fichier appsettings.json du projet RootBot. Attribuez les valeurs suivantes à partir du fichier enregistré :

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

Tester les exemples

Pour les tests, utilisez ce qui suit :

Commandes RootBot
- login permet à l'utilisateur de se connecter à l'enregistrement Microsoft Entra ID à l'aide de RootBot. Une fois connecté, l'authentification unique s'occupe aussi de la connexion à SkillBot. L'utilisateur n'a pas besoin de se reconnecter.
- token affiche le jeton de l’utilisateur.
- logout déconnecte l’utilisateur du RootBot.
Commandes SkillBot
- skill login permet au RootBot de se connecter au SkillBot pour le compte de l’utilisateur. Aucune carte de connexion n'est présentée à l'utilisateur s'il est déjà connecté, sauf si l'authentification unique échoue.
- skill token affiche le jeton de l’utilisateur à partir du SkillBot.
- skill logout déconnecte l’utilisateur du SkillBot.

Remarque

La première fois que les utilisateurs essaient d’utiliser l’authentification unique sur une compétence, une carte OAuth peut leur être présentée pour la connexion. Ceci est dû au fait qu'ils n'ont pas encore donné leur consentement à l'ID d'application Microsoft Entra ID de la compétence. Pour éviter cela, ils peuvent accorder le consentement de l'administrateur pour toutes les autorisations graphiques demandées par l'application Microsoft Entra ID.

Émulateur
Conversation web par chat

Si vous ne l'avez pas encore fait, installez Bot Framework Emulator. Consultez également Déboguer avec l'émulateur.

Vous devez configurer l'émulateur pour que l'échantillon de connexion du bot fonctionne. Utilisez les étapes ci-dessous : comme indiqué dans Configurer l'émulateur pour l'authentification.

Une fois que vous avez configuré le mécanisme d'authentification, vous pouvez effectuer les tests de l'exemple de bot réel.

Dans Visual Studio, ouvrez la solution SSOWithSkills.sln et configurez-la pour démarrer le débogage avec plusieurs processus.
Démarrez le débogage localement sur votre ordinateur. Sachez que, dans le fichier appsettings.json du projet RootBot, vous avez les paramètres suivants :
```
"SkillHostEndpoint": "http://localhost:3978/api/skills/"
"SkillEndpoint": "http://localhost:39783/api/messages"
```
Remarque

Ces paramètres impliquent que RootBot et SkillBot s’exécutent tous deux sur l’ordinateur local. L'émulateur communique avec RootBot sur le port 3978 et RootBot communique avec SkillBot sur le port 39783. Dès que vous démarrez le débogage, deux fenêtres de navigateur par défaut s’ouvrent : une sur le port 3978 et l’autre sur le port 39783.
Démarrez l’émulateur.
Lorsque vous vous connectez au bot, saisissez votre identifiant et votre mot de passe de l'application d'enregistrement RootBot.
Tapez hi pour commencer la conversation.
Entrez login. Le RootBot affiche une carte d’authentification Se connecter à AAD.
Sélectionnez Connexion. La boîte de dialogue contextuelle Confirmer l’ouverture de l’URL s’affiche.
Cliquez sur Confirmer. Vous serez connecté et le jeton RootBot s'affichera.
Entrez token pour réafficher le jeton.

Vous êtes maintenant prêt à communiquer avec le SkillBot. Une fois que vous avez signé en utilisant le RootBot, vous n'avez plus besoin de fournir vos informations d'identification jusqu'à ce que vous vous déconnectiez. Cela prouve que l'authentification unique fonctionne.
Saisissez l'identifiant de compétence dans la zone de l'émulateur. Il ne vous sera plus demandé de vous connecter. Au lieu de cela, le jeton SkillBot s’affiche.
Saisissez le jeton de compétence pour afficher à nouveau le jeton.
Vous pouvez maintenant entrer skill logout pour vous déconnecter du SkillBot. Ensuite, entrez logout pour vous déconnecter du SimpleRootBoot.

Déployez le bot racine et le bot de compétence sur Azure. Pour plus d'informations, consultez Tutoriel : approvisionner un bot dans Azure et Tutoriel : publier un bot de base.
Dans votre éditeur de code, par exemple Visual Studio, remplacez les adresses localhost dans le fichier RootBot de projet appsetting.js par les adresses Microsoft Entra ID comme indiqué ci-dessous.
```
"SkillHostEndpoint": "https://<your root bot deployed name>.azurewebsites.net/api/skills"
"SkillEndpoint": "https://<your skill bot deployed name>.azurewebsites.net/api/messages"
```
Dans votre navigateur, accédez au Portail Azure.
Ouvrez votre inscription de bot racine. Dans le volet gauche, sélectionnez sur Tester dans un Chat Web. La fenêtre de dialogue avec votre bot racine s'affiche avec le message d'accueil du bot.
Démarrez la conversation avec le bot en entrant par exemple hi. Le bot reproduira votre message.
Entrez login. Le RootBot affiche une carte d’authentification Se connecter à AAD.
Sélectionnez Connexion. Une page web avec un code de validation s’affiche.
Pour terminer la connexion, copiez le code et saisissez-le dans la zone de saisie. Le jeton RootBot s’affiche.
Entrez token pour réafficher le jeton.

Vous êtes maintenant prêt à communiquer avec le SkillBot. Une fois que vous vous êtes connecté au RootBot, vous n'avez plus besoin de fournir vos informations d'identification jusqu'à ce que vous vous déconnectiez. Cela prouve que l'authentification unique fonctionne.
Entrez skill login. Le jeton SkillBot s’affiche.
Saisissez le jeton de compétence pour afficher à nouveau le jeton. Cela indique que vous communiquez avec le SkillBot sans avoir à vous reconnecter. L’authentification unique fonctionne !
Vous pouvez maintenant entrer skill logout pour vous déconnecter du SkillBot. Ensuite, entrez logout pour vous déconnecter du SimpleRootBoot.

Informations supplémentaires

Le diagramme chronologique suivant s’applique aux exemples utilisés dans l’article et montre l’interaction entre les différents composants impliqués. ABS signifie Azure AI Bot Service.

Sequence diagram illustrating the skill token flow.

La première fois, l’utilisateur entre la commande login pour le RootBot.
Le RootBot envoie un OAuthCard invitant l’utilisateur à se connecter.
L'utilisateur saisit les identifiants d'authentification qui sont envoyés à ABS (Azure AI Bot Service).
ABS envoie le jeton d’authentification, généré en fonction des informations d’identification de l’utilisateur, au RootBot.
Le RootBot présente le jeton racine à l’utilisateur.
L’utilisateur entre la commande skill login pour le SkillBot.
Le SkillBot envoie un OAuthCard au RootBot.
Le RootBot demande un jeton échangeable à ABS.
L'authentification unique envoie le jeton de compétence SkillBot au RootBot.
Le RootBot présente le jeton de compétence à l’utilisateur. Notez que le jeton de compétence a été généré sans que l’utilisateur ait besoin de se connecter au SKillBot. Cela est dû à l’authentification unique.

L'exemple suivant montre comment l'échange de jetons se produit. Le code provient du fichier 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;
}

Partager via