Ajouter l'authentification unique à un bot

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.

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 comment implémenter un flux de conversation séquentiel et réutiliser des 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 :

1. une application Microsoft Entra ID pour enregistrer une ressource bot dans Azure.
2. 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

1. Créez une ressource Azure bot dans le portail Azure pour RootBot. Suivez les étapes décrites dans Créer une ressource Azure bot.
2. 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.

1. 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.

2. Dans le volet gauche, sélectionnez Manifeste.

3. Affectez la valeur 2 à accessTokenAcceptedVersion.

4. Cliquez sur Enregistrer.

5. Dans le volet de gauche, sélectionnez Exposer une API.

6. Dans le volet droit, sélectionnez Ajouter une étendue.

7. À l'extrême droite de la section Ajouter une étendue, sélectionnez Enregistrer et continuer.

8. Dans la fenêtre qui s'affiche, sous Qui peut donner son consentement ?, sélectionnez Administrateurs et utilisateurs.

9. Entrez les autres informations requises.

10. Sélectionnez Ajouter une étendue.

11. Copiez et enregistrez la valeur d’étendue.

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

1. 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.

2. Laissez l’URL d’échange de jeton vide.

3. 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.

4. Copiez et enregistrez le nom de la connexion.

Créez la ressource Azure SkillBot

1. 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.
2. 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.

1. 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.

2. Dans le volet gauche, sélectionnez Manifeste.

3. Affectez la valeur 2 à accessTokenAcceptedVersion.

4. Cliquez sur Enregistrer.

5. Dans le volet de gauche, sélectionnez Exposer une API.

6. Dans le volet droit, sélectionnez Ajouter une étendue.

7. Dans la section Ajouter une étendue située à l'extrême droite, sélectionnez Enregistrer et continuer.

8. Dans la fenêtre qui s’affiche, sous Qui peut donner son consentement, sélectionnez Administrateurs et utilisateurs.

9. Entrez les autres informations requises.

10. Sélectionnez Ajouter une étendue.

11. Copiez et enregistrez la valeur d’étendue.

12. 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.

13. Sous Étendue autorisée, cochez la case en regard de la valeur d’étendue.

14. Sélectionnez Ajouter une application.

15. 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

1. 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.

2. 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.

3. Dans la zone Étendues, entrez les valeurs suivantes séparées par un espace vide : openidprofile User.Read User.ReadBasic.All .

4. Copiez et enregistrez le nom de la connexion dans un fichier.

Tester la connexion

1. Sélectionnez l'entrée de la connexion pour ouvrir la connexion que vous avez créée.
2. En haut du volet Paramètre de connexion du fournisseur de service, sélectionnez Tester la connexion
3. 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.
4. Sélectionnez Accepter.
5. 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.

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

2. 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>" ]
   }
   
   

3. 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.

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.

1. La première fois, l’utilisateur entre la commande login pour le RootBot.
2. Le RootBot envoie un OAuthCard invitant l’utilisateur à se connecter.
3. L'utilisateur saisit les identifiants d'authentification qui sont envoyés à ABS (Azure AI Bot Service).
4. ABS envoie le jeton d’authentification, généré en fonction des informations d’identification de l’utilisateur, au RootBot.
5. Le RootBot présente le jeton racine à l’utilisateur.
6. L’utilisateur entre la commande skill login pour le SkillBot.
7. Le SkillBot envoie un OAuthCard au RootBot.
8. Le RootBot demande un jeton échangeable à ABS.
9. L’authentification unique envoie le jeton de compétence SkillBot au RootBot.
10. 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;
}