Partager via

Ajouter une authentification à un bot

  • Article

S'APPLIQUE À : SDK v4

Le kit de développement logiciel (SDK) Azure AI Bot Service v4 facilite le développement de bots pouvant accéder à des ressources en ligne nécessitant une authentification de l'utilisateur. Votre bot n'a pas besoin de gérer les jetons d'authentification, car Azure le fait pour vous à l'aide d'OAuth 2.0 pour générer un jeton en fonction des informations d'identification de chaque utilisateur. Votre bot utilise le jeton généré par Azure pour accéder à ces ressources. Ainsi, l'utilisateur n'a pas besoin de fournir un ID et un mot de passe au bot pour accéder à une ressource sécurisée. Il les fournit uniquement à un fournisseur d'identité approuvé.

Pour obtenir une vue d'ensemble de la gestion de de ce type d'authentification par le Bot Framework, consultez Authentification de l'utilisateur.

Cet article fait référence à deux exemples. L’un d’eux montre comment obtenir un jeton d’authentification. L'autre est plus complexe et montre comment accéder à Microsoft Graph pour le compte de l'utilisateur. Dans les deux cas, vous pouvez utiliser Azure AD v1 ou v2 comme un fournisseur d'identité pour obtenir un jeton OAuth pour le bot. Cet article explique comment effectuer les tâches suivantes :

  • Créer une ressource de bot Azure
  • Créez le fournisseur d'identité Microsoft Entra ID
  • Enregistrez le fournisseur d'identité Microsoft Entra ID auprès du bot
  • Préparer le code du bot

Quand vous aurez terminé cet article, vous disposerez d'un bot pouvant répondre à quelques tâches simples. Dans l'exemple de Microsoft Graph, vous pouvez envoyer un e-mail, vous présenter et consulter les derniers e-mails. Vous n'avez pas besoin de publier le bot pour tester les fonctionnalités OAuth. Cependant, le bot aura besoin d'un ID d'application Azure et d'un mot de passe valides.

Remarque

Les kits SDK JavaScript, C# et Python Bot Framework continueront d’être pris en charge. Toutefois, le kit de développement logiciel (SDK) Java est mis hors service avec une prise en charge finale à long terme se terminant en novembre 2023.

Les bots existants créés avec le kit de développement logiciel (SDK) Java continueront de fonctionner.

Pour la nouvelle génération de bots, envisagez d’utiliser Microsoft Copilot Studio et lisez-en plus sur le choix de la solution copilote appropriée.

Pour plus d'informations, consultez Les futures versions de bot.

Considérations relatives à Web Chat et à Direct Line

Important

Vous devez utiliser Direct Line avec l'authentification améliorée activée pour atténuer les risques de sécurité lors de la connexion à un bot à l'aide du contrôle Chat Web. Pour plus d'informations, consultez l'authentification améliorée Direct Line.

Prérequis

  • Connaissance des fondamentaux sur les bots, de la gestion de l’état, de la bibliothèque de dialogues, de la façon d’implémenter un flux de conversation séquentiel et de la façon de réutiliser les dialogues

  • Connaissances du développement Azure et OAuth 2.0.

  • Visual Studio 2017 ou version ultérieure pour .NET

  • Node.js pour JavaScript

  • Python 3.8+ pour Python.

  • L’un des exemples ci-après

    Exemple Version de Bot Builder Montre ce qui suit
    Authentification en C# ou JavaScript ou Java ou Python v4 Prise en charge d’OAuthCard
    Authentification pour Microsoft Graph en C# ou JavaScript ou Java ou Python v4 Prise en charge d'API Microsoft Graph avec OAuth 2.0
    Authentification pour Microsoft Teams en C# ou JavaScript ou Java ou Python v4 Prise en charge d'API Microsoft Graph avec OAuth 2.0

    Pour exécuter les échantillons référencés dans cet article, vous avez besoin de :

    • Une application Microsoft Entra ID avec laquelle enregistrer une ressource bot dans Azure. Cette application permet au bot d’accéder à une ressource sécurisée externe telle que Microsoft Graph. Elle permet également à l’utilisateur de communiquer avec le bot par le biais de plusieurs canaux comme Webchat.
    • Une application Microsoft Entra ID séparée pour fonctionner comme fournisseur d'identité. Cette application fournit les informations d’identification nécessaires pour établir une connexion OAuth entre le bot et la ressource sécurisée. Notez que cet article utilise Active Directory comme fournisseur d’identité. De nombreux autres fournisseurs sont également pris en charge.

Important

Chaque fois que vous enregistrez un bot dans Azure, une application Microsoft Entra ID lui est attribuée. Toutefois, cette application sécurise l’accès du canal vers le bot. Vous avez besoin d'une application Microsoft Entra ID supplémentaire pour chaque ressource externe sécurisée à laquelle vous souhaitez que le bot accède au nom de l'utilisateur.

Créer la ressource

Créez la ressource Azure Bot, qui vous permettra d'inscrire votre bot auprès du Azure AI Bot Service.

Conseil

De nouvelles ressources de bot d'application Web et d'inscription de canaux bot ne peuvent pas être créées. Cependant, toutes les ressources existantes configurées et déployées continueront à fonctionner. Les bots créés à partir d'un modèle VSIX ou Yeoman à partir du kit de développement logiciel (SDK) version 4.14.1.2 ou ultérieure contiennent des modèles ARM qui généreront une ressource Azure Bot.

  1. Accédez au portail Azure.

  2. Dans le volet de droite, sélectionnez Créer une ressource.

  3. Dans la zone de recherche, saisissez bot, et appuyez sur Entrée.

  4. Sélectionnez la carte Azure Bot.

    Sélectionner une ressource de bot Azure

  5. Sélectionnez Créer.

  6. Saisissez des valeurs dans les champs obligatoires, puis révisez et mettez à jour les paramètres.

    1. Fournissez des informations sous Détails du projet. Indiquez si votre bot aura une résidence globale ou locale des données. Actuellement, la fonctionnalité de résidence des données locale est disponible pour les ressources de la région « westeurope » et « centralindia ». Pour plus d'informations, consultez la rubrique Régionalisation dans Azure AI Bot Service.

      Paramètres de détails du projet pour une ressource Azure Bot

    2. Fournissez des informations sous ID d'application Microsoft. Sélectionnez comment l'identité de votre bot sera gérée dans Azure et si vous souhaitez créer une nouvelle identité ou utiliser une identité existante.

      Paramètres d’ID d’application Microsoft pour une ressource Azure Bot

  7. Sélectionnez Revoir + créer.

  8. Si la validation est réussie, sélectionnez Créer.

  9. Une fois le déploiement terminé, sélectionnez Accéder à la ressource. Vous devez consultez le bot et les ressources associées répertoriées dans le groupe de ressources que vous avez sélectionné.

  10. Si vous n'avez pas encore le kit de développement logiciel (SDK) Bot Framework, sélectionnez Télécharger à partir de GitHub pour apprendre à utiliser les packages pour votre langage préféré.

    Créer un bot dans le Kit de développement logiciel (SDK)

Vous êtes désormais prêt à créer votre bot avec le kit de développement logiciel (SDK) Bot Framework.

Conseil

Lorsqu'Azure crée une nouvelle ressource Azure Bot à locataire unique ou multilocataire avec un nouvel identifiant d'application, elle génère également un mot de passe.

Informations sur l'identité du bot

Suivez ces étapes pour ajouter des informations d'identité au fichier de configuration de votre bot. Le fichier diffère selon le langage de programmation que vous utilisez pour créer le bot.

Important

La version Java du Kit de développement logiciel (SDK) Bot Framework prend uniquement en charge les bots multilocataires. Les versions C#, JavaScript et Python prennent en charge les trois types d’applications pour la gestion de l’identité du bot.

Langage Nom de fichier Notes
C# appsettings.json Prend en charge les trois types d'applications pour gérer l'identité de votre bot.
JavaScript .env Prend en charge les trois types d'applications pour gérer l'identité de votre bot.
Java application.properties Prend uniquement en charge les bots multilocataires.
Python config.py Prend en charge les trois types d'applications pour gérer l'identité de votre bot.

Les informations d'identité que vous devez ajouter dépendent du type d'application du bot. Fournissez les valeurs suivantes dans votre fichier de configuration :

Disponible pour les bots C#, JavaScript et Python.

Propriété Valeur
MicrosoftAppType UserAssignedMSI
MicrosoftAppId ID client de l'identité managée affectée par l'utilisateur.
MicrosoftAppPassword Non applicable. Laissez cette valeur vide pour un bot d'identité managée affecté par l'utilisateur.
MicrosoftAppTenantId L'identifiant du locataire de l'identité managée affectée par l'utilisateur.

Pour mettre à jour votre service d'application

Si vous disposez d'une ressource App Service existante (application Web) pour votre bot et que ce dernier est une application d'identité managée affectée par l'utilisateur, vous devrez peut-être mettre à jour le service d'application de votre bot :

  1. Accédez au panneau App Service de l'application Web de votre bot.
  2. Sous Paramètres, sélectionnez Identité.
  3. Sous l'onglet Identité, sélectionnez Affecté par l'utilisateur, puis + Ajouter.
  4. Sur le panneau Ajouter l'identité managée affectée par l'utilisateur :

    1. Sélectionnez votre abonnement.

    2. Pour les identités managées affectées par l'utilisateur, sélectionnez l'identité managée pour votre bot. Si l'identité managée a été générée automatiquement pour vous, elle aura le même nom que votre bot.

    3. Sélectionnez Ajouter pour utiliser cette identité pour votre bot.

      Panneau Identité App Service avec l’identité managée pour le bot sélectionné.

Pour obtenir l'identifiant de locataire ou d'application

Pour obtenir l'identifiant de l'application ou du locataire de votre bot :

  1. Accédez au panneau des ressources Azure Bot pour votre bot.
  2. Accédez au panneau Configuration du bot. Dans ce panneau, vous pouvez copier l'ID d'application Microsoft ou l'identifiant du locataire d'application du bot.

Pour générer un nouveau mot de passe

Les bots à locataire unique et à plusieurs locataires disposent d'un secret d'application ou d'un mot de passe dont vous avez besoin pour certaines opérations. Azure AI Bot Service masque votre secret de bot. Toutefois, le propriétaire de la ressource App Service du bot peut générer un nouveau mot de passe :

  1. Accédez au panneau des ressources Azure Bot pour votre bot.
  2. Accédez au panneau Configuration du bot.
  3. Sélectionnez Gérer, à côté de l'ID d'application Microsoft, pour accéder au panneau Certificats + secrets du service d'application.
  4. Suivez les instructions du panneau pour créer une clé secrète client et enregistrer la valeur dans un lieu sûr.

Service d'identité Microsoft Entra ID

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

Vous pouvez utiliser l’un de ces deux services d’identité :

  1. Plateforme de développeur Microsoft Entra ID (v1.0). Cette plateforme est également connue sous le nom de point de terminaison Azure AD v1. Elle vous permet de créer des applications qui connectent de manière sécurisée les utilisateurs ayant un compte professionnel ou scolaire Microsoft. Pour plus d'informations, consultez la vue d'ensemble de Microsoft Entra ID pour les développeurs (v1.0).
  2. Plateforme d’identités Microsoft (v2.0). Aussi connu sous le nom de point de terminaison Microsoft Entra ID, qui est une évolution de la plateforme Azure AD (v1.0). Elle vous permet de générer des applications qui se connectent à tous les fournisseurs d’identité Microsoft et obtiennent des jetons pour appeler des API Microsoft comme Microsoft Graph ou d’autres API que des développeurs ont créées. Pour plus d'informations, consultez Vue d'ensemble de la plateforme d'identités 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).

Créez le fournisseur d'identité Microsoft Entra ID

Cette section montre comment créer un fournisseur d'identité Microsoft Entra ID qui utilise OAuth 2.0 pour authentifier le bot. Vous pouvez utiliser des points de terminaison Azure AD v1 ou Microsoft Entra ID.

Conseil

Vous devez créer et enregistrer l'application Microsoft Entra ID dans un locataire dans lequel vous pouvez consentir à déléguer les autorisations demandées par une application.

  1. Ouvrez le volet Microsoft Entra ID dans le portail Azure. Si vous n'êtes pas dans le bon locataire, sélectionnez Changer d'annuaire pour basculer vers le bon locataire. (Pour plus d'informations sur la création d'un locataire, consultez Accéder au portail et créer un locataire.)

  2. Ouvrez le panneau Inscriptions d’applications.

  3. Dans le volet Inscriptions d'applications, sélectionnez Nouvelle inscription.

  4. Renseignez les champs obligatoires et créez l’inscription d’application.

    1. Donnez un nom à votre application.

    2. Sélectionnez les Types de comptes pris en charge par votre application. (Toutes ces options fonctionnent avec cet exemple.)

    3. Pour l'URI de redirection, sélectionnez Web et définissez l'URL sur l'une des URL de redirection OAuth prises en charge.

    4. Sélectionnez Inscrire.

      • Une fois l'application créée, Azure affiche la page Vue d'ensemble de l'application.
      • Enregistrez la valeur ID d’application (client). Vous utiliserez cette valeur ultérieurement comme Identifiant client lorsque vous créez le chaîne de connexion et inscrivez le fournisseur d'identifiant Microsoft Entra ID auprès de l'inscription du bot.
      • Enregistrez la valeur de l'identifiant de l'annuaire (du locataire). Vous utiliserez cette valeur pour enregistrer cette application fournisseur avec votre bot.

  5. Dans le volet de navigation, sélectionnez Certificats et secrets pour créer un secret pour votre application.

    1. Sous Secrets client, sélectionnez Nouveau secret client.
    2. Ajoutez une description pour différencier ce secret des autres secrets que vous allez peut-être créer pour cette application, par exemple bot login.
    3. Pour Expire, choisissez une durée après laquelle le secret expirera.
    4. Sélectionnez Ajouter.
    5. Avant de quitter certificats et secrets, enregistrez le secret. Vous utiliserez cette valeur ultérieurement comme clé secrète client lorsque vous enregistrerez votre application Microsoft Entra ID avec votre bot.

  6. Dans le volet de navigation, sélectionnez Autorisations d'API pour ouvrir le volet Autorisations d'API. Une bonne meilleure pratique consiste à définir explicitement les autorisations d'API pour l'application.

    1. Sélectionnez Ajouter une autorisation pour afficher le volet Autorisations d'API de demande.

    2. Pour cet exemple, sélectionnez API Microsoft et 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 ces autorisations.

      Remarque

      Pour votre bot, évitez les autorisations qui sont marquées comme Consentement administrateur requis, car elles nécessitent la connexion d’un utilisateur et d’un administrateur de locataires.

      • openid
      • profile
      • Mail.Read
      • Mail.Send
      • User.Read
      • User.ReadBasic.All

    4. Sélectionnez Ajouter des autorisations. (La première fois qu'un utilisateur accède à cette application par le biais du bot, il doit donner son consentement.)

Vous avez maintenant une application Microsoft Entra ID configurée.

Remarque

Vous attribuez l'ID client d'application et la clé secrète client lorsque vous créez le chaîne de connexion et enregistrez le fournisseur d'identité avec l'inscription du bot. Consultez la section suivante.

Enregistrez le fournisseur d'identité Microsoft Entra ID auprès du bot

L'étape suivante consiste à inscrire votre fournisseur d'identité auprès de votre bot.

  1. Ouvrez la page de ressources Azure Bot de votre bot dans le portail Azure.

  2. Sélectionnez Paramètres.

  3. Sous Paramètres de connexion OAuth près du bas de la page, sélectionnez Ajouter un paramètre.

  4. Remplissez le formulaire comme suit :

    1. Nom. Saisissez un nom pour votre connexion. Vous l’utiliserez dans le code de votre bot.

    2. Fournisseur de services Sélectionnez Microsoft Entra ID pour afficher les champs spécifiques à Microsoft Entra ID.

    3. ID client. Saisissez l'ID client d'application que vous avez enregistré pour votre fournisseur d'identité Microsoft Entra ID.

    4. Clé secrète client. Saisissez le secret que vous avez enregistré pour votre fournisseur d'identité Microsoft Entra ID.

      Conseil

      Si vous souhaitez utiliser des certificats, vous pouvez sélectionner AAD v2 avec le fournisseur Certificats. Vous devez donner au Bot Service Token Store (appid : 5b404cf4-a79d-4cfe-b866-24bf8e1a4921) l'autorisation d'obtenir le certificat.

    5. URL d'échange de jeton. Laissez-le vide, car il est utilisé pour l'authentification unique dans Microsoft Entra ID uniquement.

    6. Identifiant de locataire. Saisissez l'identifiant de annuaire (locataire) que vous avez enregistré précédemment pour votre ID d'application Microsoft Entra ID ou commun en fonction des types de comptes pris en charge sélectionnés lors de la création de l'application Azure DD. Pour déterminer la valeur à attribuer, suivez ces critères :

      • Lors de la création de l'application Microsoft Entra ID, si vous avez sélectionné Comptes dans cet annuaire organisationnel uniquement (Microsoft uniquement : un seul locataire), saisissez l'identifiant du locataire que vous avez enregistré plus tôt pour l'application Microsoft Entra ID.
      • Cependant, si vous avez sélectionné Comptes dans n'importe quel annuaire organisationnel (Tout annuaire Microsoft Entra ID, multilocataire et comptes personnels Microsoft par exemple Xbox, Outlook.com) ou Comptes dans n'importe quel annuaire organisationnel (Annuaire Microsoft Entra ID - multilocataire), saisissez common au lieu d'un identifiant de locataire. Dans le cas contraire, l'application Microsoft Entra ID procédera à une vérification par l'intermédiaire du locataire dont l'identifiant a été sélectionné et exclura les comptes Microsoft personnels.

      Il s’agit du locataire associé aux utilisateurs qui peuvent être authentifiés. Pour plus d’informations, consultez Location dans Microsoft Entra ID.

    7. Pour les étendues, saisissez les noms des autorisations que vous avez choisies lors de l'enregistrement de la demande. À des fins de test, vous pouvez simplement saisir : openid profile.

      Remarque

      Pour Microsoft Entra ID, le champ des étendues contient une liste de valeurs sensibles à la casse et séparées par des espaces.

  5. Cliquez sur Enregistrer.

Remarque

Ces valeurs permettent à votre application d’accéder aux données Office 365 via l’API Microsoft Graph. De même, l'URL d'échange de jetons doit être laissée vide car elle est utilisée pour l'authentification unique dans Microsoft Entra ID uniquement.

Tester votre 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.

Vous pouvez maintenant utiliser ce nom de connexion dans le code de votre bot pour récupérer des jetons utilisateur.

Préparer le code du bot

Vous avez besoin de l'identifiant de l'application de votre bot et du mot de passe associé pour effectuer cette procédure.

  1. Clonez à partir du référentiel GitHub l'échantillon avec lequel vous souhaitez travailler : Authentification bot ou authentification bot pour Microsoft Graph.

  2. Mettez à jour appsettings.json :

    • Définissez ConnectionName sur le nom du paramètre de connexion OAuth que vous avez ajouté à votre bot.

    • Définissez MicrosoftAppId et MicrosoftAppPassword sur l’ID d’application et le secret d’application de votre bot.

      En fonction des caractères contenus dans le secret de votre bot, vous pouvez être amené à placer le mot de passe dans une séquence d’échappement XML. Par exemple, les esperluettes (&) doivent être encodées sous la forme &amp;.

    {
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "MicrosoftAppTenantId": "",
  "ConnectionName": ""
}

    Pour utiliser OAuth dans le bot avec résidence des données dans le cloud public, vous devez ajouter les configurations suivantes dans vos appsettings

    "OAuthUrl": "<Regional-OAuth-Uri>",
"ToChannelFromBotOAuthScope": "https://api.botframework.com",
"ToChannelFromBotLoginUrlTemplate": "https://api.botframework.com",
"PublicAzureChannel": "https://api.botframework.com",
"ToBotFromChannelOpenIdMetadataUrl": "https://login.botframework.com/v1/.well-known/openidconfiguration",
"ToBotFromEmulatorOpenIdMetadataUrl": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
"ToBotFromChannelTokenIssuer": "https://api.botframework.com",
"ToChannelFromBotLoginUrl": "https://login.microsoftonline.com/botframework.com",

    Où <Regional-OAuth-Url> est l'une des URI suivantes :

    URI Description
    https://europe.api.botframework.com Pour les bots cloud public disposant d'une résidence de données en Europe.
    https://unitedstates.api.botframework.com Pour les bots cloud public avec résidence des données dans le États-Unis.
    https://india.api.botframework.com Pour les bots cloud public avec résidence des données en Inde.

  3. Mettez à jour Startup.cs :

    Pour utiliser OAuth dans des clouds Azure non publics, comme le cloud gouvernemental, vous devez ajouter le code suivant dans le fichier Startup.cs.

    string uri = "<uri-to-use>";
MicrosoftAppCredentials.TrustServiceUrl(uri);
OAuthClientConfig.OAuthEndpoint = uri;

    Où <uri-to-use> est l'une des URI suivantes :

    URI Description
    https://api.botframework.azure.us Pour les États-Unis bots cloud gouvernementaux sans résidence des données.
    https://api.botframework.com Pour les bots cloud public sans résidence des données. Il s'agit de l'URI par défaut et ne nécessite pas de modification de Startup.cs.

Pour obtenir l’ID d’application Microsoft et les valeurs de mot de passe de l’application Microsoft, consultez Obtenir le mot de passe d’inscription.

Remarque

Vous pourriez maintenant publier ce code de bot dans votre abonnement Azure (faites un clic droit sur le projet et choisissez Publier), mais ce n'est pas nécessaire pour cet article. Vous devriez définir une configuration de publication qui utilise l’application et le plan d’hébergement que vous avez utilisés quand vous avez configuré le bot dans le portail Azure.

Tester le bot dans l'émulateur

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

Pour que l'échantillon de connexion du bot fonctionne, vous devez configurer l'émulateur comme indiqué dans Configurer l'émulateur pour l'authentification.

Test

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

Remarque

Vous pouvez être invité à entrer un code magique, en raison de la façon dont l’exemple de bot est implémenté. Ce code magique fait partie du RFC#7636 et est là pour ajouter un élément de sécurité supplémentaire. La suppression du code magique présente un risque accru pour la sécurité. Cela peut être atténué à l'aide de Direct Line avec l'authentification améliorée activée. Pour plus d'informations, consultez Authentification améliorée de Bot Framework.

  1. Exécutez l’exemple de bot localement sur votre machine.
  2. Démarrez Emulator.
  3. Vous devez fournir l'identifiant et le mot de passe d'application de votre bot pour vous y connectez.
    • Vous recevez l’ID et le mot de passe d’application en vous inscrivant à l’application Azure. Il s’agit des mêmes valeurs que celles que vous avez attribuées à l’application bot dans le fichier appsettings.json ou .env. Dans l'émulateur, vous attribuez ces valeurs dans le fichier de configuration ou la première fois que vous vous connectez au bot.
    • Si vous deviez ajouter une séquence d’échappement XML à votre mot de passe dans le code de votre bot, vous devez également le faire ici.
  4. Tapez help pour afficher la liste des commandes disponibles pour le bot, puis testez les fonctionnalités d’authentification.
  5. Une fois connecté, vous n’avez pas besoin de refournir vos informations d’identification jusqu’à ce que vous vous déconnectiez.
  6. Pour vous déconnecter et annuler votre authentification, tapez logout.

Remarque

L'authentification de bot nécessite l'utilisation du service de connecteur Bot. Le service accède aux informations de votre ressource Azure Bot.

Exemple d’authentification

Dans l’exemple Authentification du bot, le dialogue est conçu pour récupérer le jeton utilisateur après la connexion de l’utilisateur.

Exemple de conversation avec l’exemple de bot d’authentification.

Exemple d'authentification pour Microsoft Graph

Dans l'échantillon d'authentification du bot pour Microsoft Graph, le dialogue est conçue pour accepter un ensemble limité de commandes une fois l'utilisateur connecté.

Exemple de conversation avec l’exemple de bot d’authentification Microsoft Graph.

Informations supplémentaires

Quand un utilisateur demande au bot de faire quelque chose qui nécessite sa connexion au bot, celui-ci peut utiliser OAuthPrompt pour lancer la récupération d’un jeton pour une connexion donnée. L’élément OAuthPrompt crée un flux de récupération de jeton qui comprend les étapes suivantes :

  1. Vérifiez si Azure AI Bot Service dispose déjà d'un jeton pour l'utilisateur actuel et la connexion actuelle. S'il existe un jeton, celui-ci est retourné.
  2. Si Azure AI Bot Service n'a pas de jeton mis en cache, un OAuthCard est créé, qui est un bouton de connexion que l'utilisateur peut sélectionner sur.
  3. Une fois que l'utilisateur a sélectionné sur le bouton de connexion OAuthCard, Azure AI Bot Service envoie directement au bot le jeton de l'utilisateur ou lui présente un code d'authentification à 6 chiffres à saisir dans la fenêtre de conversation.
  4. Si un code d’authentification est présenté à l’utilisateur, le bot l’échange contre le jeton de l’utilisateur.

Les sections suivantes décrivent la façon dont l’exemple implémente certaines tâches courantes de l’authentification.

Utiliser une invite OAuth pour connecter l’utilisateur et obtenir un jeton

Diagramme d’architecture pour l’exemple C#.

Dialogs\MainDialog.cs

Ajoutez une invite OAuth à MainDialog dans son constructeur. Ici, la valeur du nom de connexion a été récupérée dans le fichier appsettings.json.

AddDialog(new OAuthPrompt(
    nameof(OAuthPrompt),
    new OAuthPromptSettings
    {
        ConnectionName = ConnectionName,
        Text = "Please Sign In",
        Title = "Sign In",
        Timeout = 300000, // User has 5 minutes to login (1000 * 60 * 5)
    }));

Dans une étape de dialogue, utilisez BeginDialogAsync pour démarrer l’invite OAuth qui demande à l’utilisateur de se connecter.

  • Si l’utilisateur est déjà connecté, un événement de réponse de jeton est généré, sans que l’utilisateur soit sollicité.
  • Sinon, l’utilisateur est invité à se connecter. Azure AI Bot Service envoie l'événement de réponse au jeton après que l'utilisateur a tenté de se connecter.
return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

À l’étape de dialogue suivante, vérifiez la présence d’un jeton dans le résultat de l’étape précédente. S'il n'est pas nul, l'utilisateur s'est connecté avec succès.

// Get the token from the previous step. Note that we could also have gotten the
// token directly from the prompt itself. There is an example of this in the next method.
var tokenResponse = (TokenResponse)stepContext.Result;

Attendre un TokenResponseEvent

Lorsque vous démarrez une invite OAuth, un événement de réponse de jeton est attendu à partir duquel elle va récupérer le jeton de l’utilisateur.

Bots\AuthBot.cs

AuthBot dérive de ActivityHandler et gère explicitement les activités d’événement de réponse de jeton. Ici, nous poursuivons le dialogue actif, ce qui permet à l’invite OAuth de traiter l’événement et de récupérer le jeton.

protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with Token Response Event Activity.");

    // Run the Dialog with the new Token Response Event Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

Déconnecter l’utilisateur

La meilleure pratique consiste à laisser les utilisateurs se déconnecter explicitement, au lieu de compter sur la fin de la connexion.

Dialogs\LogoutDialog.cs

private async Task<DialogTurnResult> InterruptAsync(DialogContext innerDc, CancellationToken cancellationToken = default(CancellationToken))
{
    if (innerDc.Context.Activity.Type == ActivityTypes.Message)
    {
        var text = innerDc.Context.Activity.Text.ToLowerInvariant();

        if (text == "logout")
        {
            // The UserTokenClient encapsulates the authentication processes.
            var userTokenClient = innerDc.Context.TurnState.Get<UserTokenClient>();
            await userTokenClient.SignOutUserAsync(innerDc.Context.Activity.From.Id, ConnectionName, innerDc.Context.Activity.ChannelId, cancellationToken).ConfigureAwait(false);

            await innerDc.Context.SendActivityAsync(MessageFactory.Text("You have been signed out."), cancellationToken);
            return await innerDc.CancelAllDialogsAsync(cancellationToken);
        }
    }

    return null;
}

Ajout de Teams Authentication

OAuth est géré différemment dans Teams que dans d'autres canaux. L'échantillon de bot d'authentification Teams (en C#, JavaScript, Java ou Python) montre comment implémenter correctement l'authentification pour Teams.

Pour aller plus loin