Ajouter l’authentification à votre bot Teams

Article
01/16/2024

Vous pouvez créer des bots dans Microsoft Teams qui accèdent aux ressources pour le compte de l’utilisateur, comme un service de messagerie. Vous pouvez utiliser l’authentification du Kit de développement logiciel (SDK) Azure Bot Service v4, basée sur OAuth 2.0. Cette méthode facilite le développement d’un bot qui peut utiliser des jetons d’authentification basés sur les informations d’identification de l’utilisateur. La clé est l’utilisation de fournisseurs d’identité.

OAuth 2.0 est une norme ouverte pour l’authentification et l’autorisation utilisées par Microsoft Entra ID et de nombreux autres fournisseurs d’identité. Une compréhension de base du flux d’octroi implicite OAuth 2.0 est une condition préalable à l’utilisation de l’authentification dans les onglets Microsoft Teams.

Consultez OAuth 2 Simplifié pour une compréhension de base, et OAuth 2.0 pour la spécification complète.

Pour plus d’informations sur la façon dont Azure Bot Service gère l’authentification, consultez l’authentification utilisateur dans une conversation.

Voici les titres des sections de cet article :

Comment créer un bot prenant en charge l’authentification. Vous allez utiliser cs-auth-sample pour gérer les informations d’identification de connexion utilisateur et la génération du jeton d’authentification.
Comment déployer le bot sur Azure et l’associer à un fournisseur d’identité. Le fournisseur émet un jeton basé sur les informations d’identification de connexion de l’utilisateur. Le bot peut utiliser le jeton pour accéder aux ressources, telles qu’un service de messagerie, qui nécessitent une authentification. Pour plus d’informations, consultez Flux d’authentification Microsoft Teams pour les bots.
Comment intégrer le bot dans Microsoft Teams. Une fois le bot intégré, vous pouvez vous connecter et échanger des messages avec celui-ci dans une conversation.

Configuration requise

Connaissance des principes de base du bot, de la gestion de l’état, de la bibliothèque de dialogues et de la façon d’implémenter un flux de conversation séquentiel.
Connaissance du développement Azure et OAuth 2.0
Les versions actuelles de Microsoft Visual Studio et Git.
Accédez à votre compte Azure. Si nécessaire, vous pouvez créer un compte gratuit Azure.

L’exemple suivant :

Échantillon	Version de BotBuilder	Démontre
Authentification de bot dans cs-auth-sample	v3, v4	Prise en charge d’OAuthCard
Authentification de bot dans js-auth-sample	v3, v4	Prise en charge d’OAuthCard
Authentification de bot dans py-auth-sample	v3, v4	Prise en charge d’OAuthCard

Créer le groupe de ressources

Le groupe de ressources et le plan de service ne sont pas strictement nécessaires, mais ils vous permettent de libérer facilement les ressources que vous créez. Il est recommandé de garder vos ressources organisées et gérables.

Vous utilisez un groupe de ressources pour créer des ressources individuelles pour Bot Framework. Pour des raisons de performances, assurez-vous que ces ressources se trouvent dans la même région Azure.

Dans votre navigateur, connectez-vous au portail Microsoft Azure.
Dans le volet de navigation gauche, sélectionnez Groupes de ressources.
Dans le coin supérieur gauche de la fenêtre affichée, sélectionnez Ajouter un onglet pour créer un groupe de ressources. Fournissez les détails suivants :
1. Abonnement. Utilisez votre abonnement existant.
2. Groupe de ressources Entrez le nom de l’image et le groupe de ressources. Par exemple, TeamsResourceGroup. N’oubliez pas que le nom doit être unique.
3. Dans le menu déroulant Région , sélectionnez USA Ouest ou une région proche de vos applications.
4. Sélectionnez le bouton Vérifier et créer . Vous devriez voir une bannière qui lit Validation réussie.
5. Sélectionnez le bouton Créer. La création du groupe de ressources peut prendre quelques minutes.

Conseil

Comme avec les ressources que vous allez créer plus loin dans ce didacticiel, il est judicieux d’épingler ce groupe de ressources à votre tableau de bord pour faciliter l’accès. Si vous le souhaitez, sélectionnez l’icône 📌 d’épingle en haut à droite du tableau de bord.

Créer le plan de service

Dans le Portail Azure, dans le volet de navigation gauche, sélectionnez Créer une ressource.
Dans la zone de recherche, tapez App Service Plan. Sélectionnez la carte plan App Service dans les résultats de la recherche.
Sélectionnez Créer.
Fournissez les informations suivantes :
1. Abonnement. Vous pouvez utiliser un abonnement existant.
2. Groupe de ressources Sélectionnez la base de données de mappages que vous avez créée précédemment.
3. Nom. Entrez le nom du plan de service. Par exemple, TeamsServicePlan. N’oubliez pas que le nom doit être unique, au sein du groupe.
4. Système d’exploitation Sélectionnez Windows ou votre système d’exploitation applicable.
5. Région Sélectionnez USA Ouest ou une région proche de vos applications.
6. Niveau tarifaire Sélectionnez Standard S1, qui est la valeur par défaut.
7. Sélectionnez le bouton Vérifier et créer . Vous devriez voir une bannière qui lit Validation réussie.
8. Sélectionnez Créer. La création du plan App Service peut prendre quelques minutes. Le plan est répertorié dans le groupe de ressources.

Créer une inscription de ressource Azure Bot

L’inscription de ressource Azure Bot inscrit votre service web en tant que bot auprès de Bot Framework, qui vous fournit un ID d’application Microsoft et un mot de passe d’application (clé secrète client).

Importante

Vous devez uniquement inscrire votre bot s’il n’est pas hébergé dans Azure. Si vous avez créé un bot via le Portail Azure il est déjà inscrit auprès du service. Si vous avez créé votre bot via Bot Framework ou le portail des développeurs, votre bot n’est pas inscrit dans Azure.

Visitez Portail Azure et recherchez Azure Bot dans la section Créer une ressource.
Ouvrez Le bot Azure , puis sélectionnez Créer.
Entrez le nom du handle du bot dans le champ Descripteur de bot.
Sélectionnez votre abonnement dans la liste déroulante.
Sélectionnez votre groupe de ressources dans la liste déroulante.
Sélectionnez Type d’application en tant que multilocataire pour l’ID d’application Microsoft.
Sélectionnez Examiner et créer.
Si la validation réussit, sélectionnez Créer.

Azure provisionne votre bot en quelques instants.
Sélectionnez Accéder à la ressource. Le bot et les ressources associées sont répertoriés dans le groupe de ressources.

Votre bot Azure est créé.

Pour créer une clé secrète client :

Dans Paramètres, sélectionnez Configuration. Enregistrez l’ID d’application Microsoft (ID client) pour référence ultérieure.
En regard de Id d’application Microsoft, sélectionnez Gérer.
Dans la section Secrets client , sélectionnez Nouvelle clé secrète client. Une fenêtre de clé secrète client s’affiche.
Entrez Description , puis sélectionnez Ajouter.
Dans la colonne Valeur , sélectionnez Copier dans le Presse-papiers et enregistrez l’ID de clé secrète client pour référence ultérieure.

Pour ajouter le canal Microsoft Teams :

Accéder à l’Accueil
Ouvrez votre bot à partir de la section Ressources récentes .
Sélectionnez Canaux dans le volet gauche, puis Microsoft Teams .
Cochez la case pour accepter les conditions d’utilisation du service, puis sélectionnez Accepter.
Sélectionnez Enregistrer.

Pour plus d’informations, consultez Créer un robot pour Microsoft Teams

Créer un fournisseur d’identité

Vous avez besoin d’un fournisseur d’identité pour l’authentification. Dans cette procédure, vous utilisez un fournisseur de Microsoft Entra. Vous pouvez également utiliser d’autres fournisseurs d’identité pris en charge par l’ID Microsoft Entra.

Dans le Portail Azure, dans le volet de navigation gauche, sélectionnez ID Microsoft Entra.

Conseil

Vous devez créer et inscrire cette ressource Microsoft Entra dans un locataire dans lequel vous pouvez donner votre consentement pour déléguer les autorisations demandées par une application. Pour obtenir des instructions sur la création d’un locataire, consultez Accéder au portail et créer un locataire.
Dans le panneau gauche, sélectionnez ...
Dans le volet droit, sélectionnez l’onglet Nouvelle inscription, en haut à gauche.
Fournissez les informations suivantes :
1. Nom. Entrez le nom pour la nouvelle application de service. BotTeamsIdentity en est un exemple. N’oubliez pas que le nom doit être unique.
2. Sélectionnez les types de comptes pris en charge pour votre application. Sélectionnez Comptes dans n’importe quel annuaire organisationnel (n’importe quel locataire d’ID Microsoft Entra - Multilocataire) et comptes Microsoft personnels (par exemple, Skype, Xbox).
3. Pour l’URI de redirection :
  ✓Sélectionnez Web.
  ✓ Définissez l’URL sur https://token.botframework.com/.auth/web/redirect.
4. Sélectionner Inscription.
Une fois créée, Azure affiche la page Vue d’ensemble de l’application. Copiez et enregistrez les informations suivantes dans un fichier :
1. La valeur de l’ID d’application (client) Vous utiliserez cette valeur ultérieurement comme ID client lorsque vous inscrirez cette application d’identité Azure auprès de votre bot.
2. La valeur d’ID d’annuaire (locataire) Vous utiliserez cette valeur plus tard comme ID de locataire pour inscrire cette application d’identité Azure auprès de votre bot.
Dans le volet gauche, sélectionnez Certificats & secrets pour créer une clé secrète client pour votre application.
1. Sous Clés secrètes client, sélectionnez ➕ Nouvelle clé secrète client.
2. Ajoutez une description pour identifier ce secret auprès d’autres personnes que vous devrez peut-être créer pour cette application, comme l’application d’identité bot dans Teams.
3. Configurez la Date d’expiration de votre sélection.
4. Sélectionnez Ajouter.
5. Avant de quitter cette page, enregistrez le secret. Vous utiliserez cette valeur plus tard comme clé secrète client lorsque vous inscrirez votre application Microsoft Entra auprès de votre bot.

Configurer la connexion du fournisseur d’identité et l’inscrire auprès du bot

Remarque

Il existe deux options pour les fournisseurs de services : Azure Active Directory v1 et Azure Active Directory v2. Les différences entre les deux fournisseurs sont résumées ici, mais en général, la version v2 offre plus de flexibilité en ce qui concerne la modification des autorisations des bots. API Graph autorisations sont répertoriées dans le champ étendues, et à mesure que de nouvelles autorisations sont ajoutées, les bots permettent aux utilisateurs de donner leur consentement aux nouvelles autorisations lors de la prochaine connexion. Pour la version 1, le consentement du bot doit être supprimé par l’utilisateur pour que de nouvelles autorisations soient requises dans la boîte de dialogue OAuth.

Microsoft Azure Active Directory (Azure AD) v1

Dans le Portail Azure, sélectionnez votre groupe de ressources dans le tableau de bord.
Sélectionnez le lien d’inscription de votre bot.
Ouvrez la page de ressources et sélectionnez Configuration sous Paramètres.
Sélectionnez le bouton Ajouter des paramètres de connexion OAuth sur l’écran Configuration. L’image suivante affiche la sélection correspondante dans la page de ressources :
Remplissez le formulaire comme suit :
1. Nom. Entrez un nom descriptif pour la connexion. Vous utilisez ce nom dans votre bot dans le appsettings.json fichier . Par exemple, BotTeamsAuthADv1.
2. Fournisseur de services Sélectionnez Azure Active Directory. Une fois que vous avez sélectionné cette option, les champs spécifiques à Azure Active Directory s’affichent.
3. ID client. Entrez l’ID d’application (client) que vous avez enregistré pour votre application de fournisseur d’identité Azure.
4. Clé secrète client Entrez le secret que vous avez enregistré pour votre application de fournisseur d’identité Azure.
5. Grant type Entrez authorization_code.
6. URL de connexion. Entrez https://login.microsoftonline.com.
7. ID de locataire, entrez l’ID d’annuaire (locataire) que vous avez enregistré précédemment pour votre application d’identité Azure ou commun en fonction du type de compte pris en charge sélectionné lors de la création de l’application de fournisseur d’identité. Pour déterminer la valeur à attribuer, suivez ces critères :
  - Si vous avez sélectionné Comptes dans cet annuaire organisationnel uniquement (Microsoft uniquement - Locataire unique) ou Comptes dans un annuaire organisationnel (Tout locataire d’ID Microsoft Entra - Multilocataire), entrez l’ID de locataire que vous avez enregistré précédemment pour l’application Microsoft Entra. Il s’agit du locataire associé aux utilisateurs qui peuvent être authentifiés.
  - Si vous avez sélectionné Comptes dans un annuaire organisationnel (tout locataire d’ID Microsoft Entra - Multilocataire) et comptes Microsoft personnels (par exemple, Skype, Xbox), entrez le mot commun au lieu d’un ID de locataire. Sinon, l’application Microsoft Entra vérifie via le locataire dont l’ID a été sélectionné et exclut les comptes Microsoft personnels.
h. Pour l’URL de ressource, entrez https://graph.microsoft.com/. Cette URL n’est pas utilisée dans l’exemple de code actuel.
i. Laissez les étendues vides. L’image suivante est un exemple.
Sélectionnez Enregistrer.

Microsoft Azure Active Directory (Azure AD) v2

Dans le Portail Azure, sélectionnez votre bot Azure dans le tableau de bord.
Dans la page de ressources, sélectionnez Configuration sous Paramètres.
Sélectionnez le bouton Ajouter des paramètres de connexion OAuth sur l’écran Configuration.
L’image suivante affiche la sélection correspondante dans la page de ressources :
Remplissez le formulaire comme suit :
1. Nom. Entrez un nom descriptif pour la connexion. Vous allez utiliser ce nom dans votre bot dans le appsettings.json fichier. Par exemple, BotTeamsAuthADv2.
2. Fournisseur de services Sélectionnez Azure Active Directory v2. Une fois que vous avez sélectionné cette option, les champs spécifiques à Azure AD v2 s’affichent.
3. ID client. Entrez l’ID d’application (client) que vous avez enregistré pour votre application de fournisseur d’identité Azure.
4. Clé secrète client Entrez le secret que vous avez enregistré pour votre application de fournisseur d’identité Azure.
5. Jeton URL Exchange Laissez ce champ vide.
6. ID de locataire, entrez l’ID d’annuaire (locataire) que vous avez enregistré précédemment pour votre application d’identité Azure ou commun en fonction du type de compte pris en charge sélectionné lors de la création de l’application de fournisseur d’identité. Pour déterminer la valeur à attribuer, suivez ces critères :
  - Si vous avez sélectionné Comptes dans cet annuaire organisationnel uniquement (Microsoft uniquement - Locataire unique) ou Comptes dans un annuaire organisationnel (Tout locataire d’ID Microsoft Entra - Multilocataire), entrez l’ID de locataire que vous avez enregistré précédemment pour l’application Microsoft Entra. Il s’agit du locataire associé aux utilisateurs qui peuvent être authentifiés.
  - Si vous avez sélectionné Comptes dans un annuaire organisationnel (tout locataire d’ID Microsoft Entra - Multilocataire) et comptes Microsoft personnels (par exemple, Skype, Xbox), entrez le mot commun au lieu d’un ID de locataire. Sinon, l’application Microsoft Entra vérifie via le locataire dont l’ID a été sélectionné et exclut les comptes Microsoft personnels.
7. Pour Étendues, entrez une liste délimitée par des espaces d’autorisations de graphe requises par cette application, telles que User.Read, User.ReadBasic.All ou Mail.Read.
Sélectionnez Enregistrer.

Tester la connexion

Sélectionnez l’entrée de connexion pour ouvrir la connexion que vous avez créée.
Sélectionnez Tester la connexion en haut du panneau Paramètres de connexion du fournisseur de services.
Pour la première fois, il ouvre une nouvelle fenêtre de navigateur vous demandant de sélectionner un compte. Sélectionnez le sous-réseau que vous souhaitez utiliser.
Ensuite, autorisez le fournisseur d’identité à utiliser vos données (informations d’identification). L’image suivante est un exemple.
Sélectionnez Accepter.
Une page Tester la connexion à <votre-nom> de connexion réussie s’ouvre. Actualisez la page si vous obtenez une erreur. L’image suivante est un exemple.

Le code du bot utilise le nom de connexion pour récupérer les jetons d’authentification utilisateur.

Préparer l’exemple de code du bot

Une fois les paramètres préliminaires terminés, concentrons-nous sur la création du bot à utiliser dans cet article.

Cloner cs-auth-sample
Ouvrez Visual Studio.
Dans la barre d’outils, sélectionnez Fichier > Ouvrir > le projet/la solution et ouvrez le projet de bot.
En C#, Mettez à jour appsettings.json comme suit :
- Définissez ConnectionName le nom de la connexion du fournisseur d’identité que vous avez ajoutée à l’inscription du bot. Le nom que nous avons utilisé dans cet exemple est BotTeamsAuthADv1.
- Définissez MicrosoftAppId l’ID d’application du bot que vous avez enregistré au moment de l’inscription du bot.
- Définissez MicrosoftAppPassword la clé secrète client que vous avez enregistrée au moment de l’inscription du bot.
Selon les caractères de votre secret de bot, vous devrez peut-être placer le mot de passe dans un échappement XML. Par exemple, tous les ampersands (&) doivent être encodés en tant que &.
```
{
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "ConnectionName": "",
```
Dans l’Explorateur de solutions, accédez au TeamsAppManifest dossier, ouvrez manifest.json et définissez id l’ID botIdd’application du bot que vous avez enregistré au moment de l’inscription du bot. Pour plus d'informations, voir app manifest

Cloner node-auth-sample.
Dans une console, accédez au projet :

cd samples/bot-teams-authentication/nodejs
Installer des modules

npm install
Mettez à jour la configuration de .env comme suit :
- Définissez MicrosoftAppId l’ID d’application du bot que vous avez enregistré au moment de l’inscription du bot.
- Définissez MicrosoftAppPassword la clé secrète client que vous avez enregistrée au moment de l’inscription du bot.
- Définissez le connectionName nom de la connexion du fournisseur d’identité. Selon les caractères de votre secret de bot, vous devrez peut-être placer le mot de passe dans un échappement XML. Par exemple, tous les ampersands (&) doivent être encodés en tant que &.
```
MicrosoftAppId=
MicrosoftAppPassword=
connectionName=
MicrosoftAppType= MultiTenant # Set this to SingleTenant if you are using a single tenant app registration
MicrosoftAppTenantId= common # Set your tenantId here if you are using single tenant app registration.
```
Dans le teamsAppManifest dossier, ouvrez manifest.json et définissez id sur votre ID d’application Microsoft et botId sur l’ID d’application du bot que vous avez enregistré au moment de l’inscription du bot.

Clonez py-auth-sample à partir du dépôt GitHub.
Mettre à jour config.py :
- Définissez ConnectionName le nom du paramètre de connexion OAuth que vous avez ajouté à votre bot.
- Définissez et MicrosoftAppPassword définissez MicrosoftAppId l’ID d’application et le secret d’application de votre bot.
  
  Selon les caractères de votre secret de bot, vous devrez peut-être placer le mot de passe dans un échappement XML. Par exemple, tous les ampersands (&) doivent être encodés en tant que &.
```
APP_ID = os.environ.get("MicrosoftAppId", "")
APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
CONNECTION_NAME = os.environ.get("ConnectionName", "")
```

Déployer le bot sur Azure

Pour déployer le bot, suivez les étapes décrites dans Comment déployer votre bot sur Azure.

Dans Visual Studio, vous pouvez également effectuer les étapes suivantes :

Dans Visual Studio Explorateur de solutions, sélectionnez et maintenez la touche enfoncée (ou cliquez avec le bouton droit) sur le nom du projet.
Dans le menu déroulant, sélectionnez Publier.
Dans la fenêtre affichée, sélectionnez le nouveau lien.
Dans la fenêtre de boîte de dialogue, sélectionnez App Service et Créer.
Sélectionnez le bouton Publier.
Dans la fenêtre de dialogue suivante, entrez les informations requises.
Sélectionnez Créer.
Si le déploiement se termine correctement, vous devriez le voir reflété dans Visual Studio. Une page s’ouvre dans votre navigateur par défaut avec le message Votre bot est prêt !. L’URL est similaire à https://botteamsauth.azurewebsites.net/. Enregistrez-le dans un fichier.
Dans votre navigateur, accédez à la Portail Azure.
Vérifiez votre groupe de ressources. Le bot est répertorié avec les autres ressources. L’image suivante est un exemple.
Dans le groupe de ressources, sélectionnez le nom d’inscription du bot (lien).
Dans le panneau gauche, sélectionnez Paramètres
Dans la zone Point de terminaison de messagerie, entrez l’URL que vous venez d’obtenir, suivie de api/messages. Par exemple : https://botteamsauth.azurewebsites.net/api/messages.

Remarque

Un seul point de terminaison de messagerie est autorisé pour un bot.
Sélectionnez le bouton Enregistrer dans le coin supérieur gauche.

Tester le bot à l’aide de la Emulator

Si vous ne l’avez pas déjà fait, installez le Microsoft Bot Framework Emulator. Voir aussi Déboguer avec le Emulator

Pour que l’exemple de connexion au bot fonctionne, vous devez configurer l’émulateur.

Configurer le Emulator pour l’authentification

Si un bot nécessite une authentification, vous devez configurer le Emulator. Pour configurer :

Démarrez le Emulator.
Dans l’émulateur, sélectionnez l’icône ⚙ d’engrenage en bas à gauche ou l’onglet Paramètres de l’émulateur en haut à droite.
Cochez la case en utilisant les jetons d’authentification version 1.0.
Entrez le chemin local de l’outil ngrok . Consultez le wiki d’intégration du tunneling Bot Framework Emulator/ngrok. Pour plus d’informations sur les outils, consultez ngrok.
Cochez la case en exécutant ngrok lorsque le Emulator démarre.
Sélectionnez le bouton Enregistrer .

Lorsque le bot affiche une carte de connexion et que l’utilisateur sélectionne le bouton de connexion, le Emulator ouvre une page que l’utilisateur peut utiliser pour se connecter avec le fournisseur d’authentification. Une fois que l’utilisateur le fait, le fournisseur génère un jeton utilisateur et l’envoie au bot. Après cela, le bot peut agir pour le compte de l’utilisateur.

Tester le bot de conversation

Une fois que vous avez configuré le mécanisme d’authentification, vous pouvez effectuer le test réel du bot.

Exécutez l’exemple de bot localement sur votre ordinateur, par exemple via Visual Studio.
Démarrez le Emulator.
Sélectionnez le bouton Ouvrir le bot .
Dans l’URL du bot, entrez l’URL locale du bot. Généralement dans http://localhost:3978/api/messages
Dans l’ID d’application Microsoft, entrez l’ID d’application du bot à partir de appsettings.json.
Dans le mot de passe de l’application Microsoft, entrez le mot de passe d’application du bot à partir du appsettings.json.
Sélectionnez Connexion.
Une fois le bot opérationnel, entrez un texte pour afficher la carte de connexion.
Sélectionnez le bouton Se connecter.
Une boîte de dialogue contextuelle s’affiche pour Confirmer l’URL d’ouverture pour authentifier l’utilisateur du bot (vous).
Sélectionner Confirmer.
Si vous y êtes invité, sélectionnez le compte de l’utilisateur applicable.
Selon la configuration que vous avez utilisée pour l’émulateur, vous obtenez l’une des options suivantes :
1. Utilisation du code de vérification de connexion
  ✓ Une fenêtre s’ouvre affichant le code de validation.
  ✓ Copiez et entrez le code de validation dans la zone de conversation pour terminer la connexion.
2. Utilisation de jetons d’authentification
  ✓ Vous êtes connecté en fonction de vos informations d’identification.
L’image suivante est un exemple de l’interface utilisateur du bot après vous être connecté :
Si vous sélectionnez Oui lorsque le bot vous demande Voulez-vous afficher votre jeton ?, vous obtenez la réponse suivante :
Entrez déconnexion dans la zone de conversation d’entrée pour vous déconnecter. Il libère le jeton utilisateur, et le bot ne sera pas en mesure d’agir en votre nom tant que vous ne vous reconnectez pas.

Remarque

L’authentification de bot nécessite l’utilisation du service Bot Connector. Le service accède aux informations d’inscription des bots pour votre bot.

Tester le bot de conversation

Dans votre navigateur, accédez à la Portail Azure.
Recherchez votre groupe de ressources.
Sélectionnez le lien de ressource. La page de ressource s’affiche.
Dans la page de ressources, sélectionnez Tester dans Chat Web. Le bot démarre et affiche les salutations prédéfinies.
Tapez n’importe quoi dans la zone de conversation.
Sélectionnez la zone Connexion .
Une boîte de dialogue contextuelle s’affiche pour Confirmer l’URL d’ouverture pour authentifier l’utilisateur du bot (vous).
Sélectionner Confirmer.
Si vous y êtes invité, sélectionnez le compte de l’utilisateur applicable. L’image suivante est un exemple de l’interface utilisateur du bot après vous être connecté :
Sélectionnez le bouton Oui pour afficher votre jeton d’authentification. L’image suivante est un exemple.
Entrez déconnexion dans la zone de conversation d’entrée pour vous déconnecter.

Remarque

Si vous rencontrez des problèmes de connexion, essayez de tester à nouveau la connexion comme décrit dans les étapes précédentes. Cela peut recréer le jeton d’authentification. Avec le client Bot Framework Chat Web dans Azure, vous devrez peut-être vous connecter plusieurs fois avant d’établir correctement l’authentification.

Installer et tester le bot dans Teams

Dans votre projet de bot, assurez-vous que le TeamsAppManifest dossier contient les manifest.json fichiers et color.png les outline.png fichiers.
Dans Explorateur de solutions, accédez au TeamsAppManifest dossier . Modifiez manifest.json en affectant les valeurs suivantes :
1. Vérifiez que l’ID d’application de bot que vous avez reçu au moment de l’inscription du bot est affecté id et botId.
2. Affectez cette valeur : validDomains: [ "token.botframework.com" ].
Sélectionnez et compressez les fichiers, manifest.jsonet outline.png les color.pngfichiers.
Ouvrez Microsoft Teams.
Dans le volet gauche, en bas, sélectionnez l’icône Applications.
Dans le volet droit, en bas, sélectionnez Télécharger une application personnalisée.
Accédez au TeamsAppManifest dossier et chargez le manifeste compressé. La fenêtre suivante s’affiche :
Sélectionnez le bouton Ajouter à une équipe.
Dans la fenêtre suivante, sélectionnez l’équipe dans laquelle vous souhaitez utiliser le bot.
Sélectionnez le bouton Configurer un bot .
Sélectionnez les trois points (●●●) dans le volet gauche. Sélectionnez ensuite l’icône Portail des développeurs .
Sélectionnez l’onglet Éditeur de manifeste . L’icône du bot que vous avez chargé doit s’afficher.
En outre, vous devriez être en mesure de voir le bot répertorié en tant que contact dans la liste de conversation que vous pouvez utiliser pour échanger des messages avec le bot.

Test du bot localement dans Teams

Teams est un produit entièrement basé sur le cloud. Il nécessite que tous les services auxquels il accède soient disponibles à partir du cloud à l’aide de points de terminaison HTTPS. Par conséquent, pour permettre au bot (notre exemple) de fonctionner dans Teams, vous devez soit publier le code dans le cloud de votre choix, soit rendre une instance en cours d’exécution localement accessible en externe via un outil de tunneling. Nous vous recommandons ngrok, qui crée une URL adressable en externe pour un port que vous ouvrez localement sur votre ordinateur. Pour configurer ngrok en vue de l’exécution locale de votre application Teams, procédez comme suit :

Dans une fenêtre de terminal, accédez au répertoire où vous avez ngrok.exe installé. Nous vous suggérons de définir le chemin de la variable d’environnement pour qu’il pointe vers celui-ci.
Exécutez, par exemple, ngrok http 3978 --host-header=localhost:3978. Remplacez le numéro de port en fonction des besoins. Il lance ngrok pour écouter le port que vous spécifiez. En retour, il vous donne une URL adressable en externe, valide tant que ngrok est en cours d’exécution. L’image suivante est un exemple.
Copiez l’adresse HTTPS de transfert similaire à : https://dea822bf.ngrok.io/.
Ajoutez /api/messages pour obtenir https://dea822bf.ngrok.io/api/messages, qui est le point de terminaison de messages pour le bot s’exécutant localement sur votre ordinateur et accessible sur le web dans une conversation dans Teams.
Une dernière étape à effectuer consiste à mettre à jour le point de terminaison des messages du bot déployé. Dans l’exemple, nous avons déployé le bot dans Azure. Procédons donc comme suit :
1. Dans votre navigateur, accédez à la Portail Azure.
2. Sélectionnez votre inscription de bot.
3. Dans le panneau gauche, sélectionnez Paramètres
4. Dans le volet droit, dans la zone de point de terminaison de messagerie, entrez l’URL ngrok, dans notre exemple. https://dea822bf.ngrok.io/api/messages
Démarrez votre bot localement, par exemple en mode de débogage Visual Studio.
Testez le bot en cours d’exécution localement à l’aide de la conversation web test du portail Bot Framework. Comme le Emulator, ce test ne vous permet pas d’accéder à Teams fonctionnalité spécifique.
Dans la fenêtre de terminal où ngrok s’exécute l’exécution, vous pouvez voir le trafic HTTP entre le bot et le client de conversation web. Si vous souhaitez obtenir une vue plus détaillée, dans une fenêtre de navigateur, entrez http://127.0.0.1:4040 ce que vous avez obtenu à partir de la fenêtre de terminal précédente. L’image suivante est un exemple.

Remarque

Si vous arrêtez et redémarrez ngrok, l’URL change. Pour utiliser ngrok dans votre projet, et en fonction des fonctionnalités que vous utilisez, vous devez mettre à jour toutes les références d’URL.

Informations supplémentaires

TeamsAppManifest/manifest.json

Ce manifeste contient les informations nécessaires à Teams pour se connecter au bot :

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.8/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "version": "1.0.0",
  "id": "",
  "developer": {
    "name": "TeamsBotAuth",
    "websiteUrl": "https://www.microsoft.com",
    "privacyUrl": "https://www.teams.com/privacy",
    "termsOfUseUrl": "https://www.teams.com/termsofuse"
  },
  "icons": {
    "color": "color.png",
    "outline": "outline.png"
  },
  "name": {
    "short": "TeamsBotAuth",
    "full": "Teams Bot Authentication"
  },
  "description": {
    "short": "TeamsBotAuth",
    "full": "Teams Bot Authentication"
  },
  "accentColor": "#FFFFFF",
  "bots": [
    {
      "botId": "",
      "scopes": [
        "groupchat",
        "team"
      ],
      "supportsFiles": false,
      "isNotificationOnly": false
    }
  ],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [ "token.botframework.com" ]
}

Avec l’authentification, Teams se comporte légèrement différemment des autres canaux.

Gestion de l’activité Invoke

Une activité d’appel est envoyée au bot plutôt qu’à l’activité d’événement utilisée par d’autres canaux, ce qui est effectué en sous-classant le gestionnaire d’activités.

Bots/DialogBot.cs

    public class DialogBot<T> : TeamsActivityHandler where T : Dialog
    {
        protected readonly BotState ConversationState;
        protected readonly Dialog Dialog;
        protected readonly ILogger Logger;
        protected readonly BotState UserState;

        public DialogBot(ConversationState conversationState, UserState userState, T dialog, ILogger<DialogBot<T>> logger)
        {
            ConversationState = conversationState;
            UserState = userState;
            Dialog = dialog;
            Logger = logger;
        }

        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default(CancellationToken))
        {
            await base.OnTurnAsync(turnContext, cancellationToken);

            // Save any state changes that might have occurred during the turn.
            await ConversationState.SaveChangesAsync(turnContext, false, cancellationToken);
            await UserState.SaveChangesAsync(turnContext, false, cancellationToken);
        }

        protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            Logger.LogInformation("Running dialog with Message Activity.");

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

Bots/TeamsBot.cs

L’activité Invoke doit être transférée vers la boîte de dialogue si OAuthPrompt est utilisé.

protected override async Task OnTeamsSigninVerifyStateAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with signin/verifystate from an Invoke Activity.");

    // The OAuth Prompt needs to see the Invoke Activity in order to complete the login process.

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

TeamsActivityHandler.cs


protected virtual Task OnInvokeActivityAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    switch (turnContext.Activity.Name)
    {
        case "signin/verifyState":
            return OnSigninVerifyStateAsync(turnContext, cancellationToken);

        default:
            return Task.CompletedTask;
    }
}

protected virtual Task OnSigninVerifyStateAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    return Task.CompletedTask;
}

bots/dialogBot.js

const { TeamsActivityHandler } = require('botbuilder');
class DialogBot extends TeamsActivityHandler {
    /**
     *
     * @param {ConversationState} conversationState
     * @param {UserState} userState
     * @param {Dialog} dialog
     */
    constructor(conversationState, userState, dialog) {
        super();
        if (!conversationState) {
            throw new Error('[DialogBot]: Missing parameter. conversationState is required');
        }
        if (!userState) {
            throw new Error('[DialogBot]: Missing parameter. userState is required');
        }
        if (!dialog) {
            throw new Error('[DialogBot]: Missing parameter. dialog is required');
        }

        this.conversationState = conversationState;
        this.userState = userState;
        this.dialog = dialog;
        this.dialogState = this.conversationState.createProperty('DialogState');

        this.onMessage(async (context, next) => {
            console.log('Running dialog with Message Activity.');

            // Run the Dialog with the new message Activity.
            await this.dialog.run(context, this.dialogState);

            await next();
        });
    }

    /**
     * Override the ActivityHandler.run() method to save state changes after the bot logic completes.
     */
    async run(context) {
        await super.run(context);

        // Save any state changes. The load happened during the execution of the Dialog.
        await this.conversationState.saveChanges(context, false);

bots/teamsBot.js

L’activité Invoke doit être transférée vers la boîte de dialogue si OAuthPrompt est utilisé.

const { DialogBot } = require('./dialogBot');

class TeamsBot extends DialogBot {
    /**
     *
     * @param {ConversationState} conversationState
     * @param {UserState} userState
     * @param {Dialog} dialog
     */
    constructor(conversationState, userState, dialog) {
        super(conversationState, userState, dialog);

        this.onMembersAdded(async (context, next) => {
            const membersAdded = context.activity.membersAdded;
            for (let cnt = 0; cnt < membersAdded.length; cnt++) {
                if (membersAdded[cnt].id !== context.activity.recipient.id) {
                    await context.sendActivity('Welcome to TeamsBot. Type anything to get logged in. Type \'logout\' to sign-out.');
                }
            }

            await next();
        });
    }
    
    async handleTeamsSigninVerifyState(context, query) {
        console.log('Running dialog with signin/verifystate from an Invoke Activity.');
        await this.dialog.run(context, this.dialogState);
    }

    async handleTeamsSigninTokenExchange(context, query) {

dialogues/mainDialog.js

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

Si l’utilisateur est déjà connecté, il génère un événement de réponse de jeton, sans demander à l’utilisateur.
Sinon, il invite l’utilisateur à se connecter. Azure Bot Service envoie l’événement de réponse de jeton après que l’utilisateur a tenté de se connecter.


async promptStep(stepContext) {
    try {

Dans 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 null, l’utilisateur s’est correctement connecté.


async promptStep(stepContext) {
    try {
        return await stepContext.beginDialog(OAUTH_PROMPT);
    } catch (err) {
        console.error(err);
    }
}

async loginStep(stepContext) {
    // 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.
    const tokenResponse = stepContext.result;
    if (!tokenResponse || !tokenResponse.token) {
        await stepContext.context.sendActivity('Login was not successful please try again.');

boîtes de dialogue/logoutDialog.js

async interrupt(innerDc) {
    if (innerDc.context.activity.type === ActivityTypes.Message) {
        const text = innerDc.context.activity.text.toLowerCase();
        if (text === 'logout') {
            const userTokenClient = innerDc.context.turnState.get(innerDc.context.adapter.UserTokenClientKey);

            const { activity } = innerDc.context;
            await userTokenClient.signOutUser(activity.from.id, this.connectionName, activity.channelId);

            await innerDc.context.sendActivity('You have been signed out.');
            return await innerDc.cancelAllDialogs();
        }

bots/dialog_bot.py

def __init__(
    self,
    conversation_state: ConversationState,
    user_state: UserState,
    dialog: Dialog,
):
    if conversation_state is None:
        raise Exception(
            "[DialogBot]: Missing parameter. conversation_state is required"
        )
    if user_state is None:
        raise Exception("[DialogBot]: Missing parameter. user_state is required")
    if dialog is None:
        raise Exception("[DialogBot]: Missing parameter. dialog is required")

    self.conversation_state = conversation_state
    self.user_state = user_state
    self.dialog = dialog

async def on_turn(self, turn_context: TurnContext):
    await super().on_turn(turn_context)

    # Save any state changes that might have occurred during the turn.
    await self.conversation_state.save_changes(turn_context, False)
    await self.user_state.save_changes(turn_context, False)

async def on_message_activity(self, turn_context: TurnContext):
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

bots/teams_bot.py

L’activité Invoke doit être transférée vers la boîte de dialogue si OAuthPrompt est utilisé.

async def on_teams_signin_verify_state(self, turn_context: TurnContext):
    # Run the Dialog with the new Token Response Event Activity.
    # The OAuth Prompt needs to see the Invoke Activity in order to complete the login process.
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

dialogs/main_dialog.py

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

Si l’utilisateur est déjà connecté, il génère un événement de réponse de jeton, sans demander à l’utilisateur.
Sinon, il invite l’utilisateur à se connecter. Azure Bot Service envoie l’événement de réponse de jeton après que l’utilisateur a tenté de se connecter.

async def prompt_step(self, step_context: WaterfallStepContext) -> DialogTurnResult:
    return await step_context.begin_dialog(OAuthPrompt.__name__)

Dans 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 null, l’utilisateur s’est correctement connecté.

async def login_step(self, step_context: WaterfallStepContext) -> DialogTurnResult:
    # 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.
    if step_context.result:
        await step_context.context.send_activity("You are now logged in.")
        return await step_context.prompt(
            ConfirmPrompt.__name__,
            PromptOptions(
                prompt=MessageFactory.text("Would you like to view your token?")
            ),
        )

dialogs/logout_dialog.py

text = inner_dc.context.activity.text.lower()
if text == "logout":
    bot_adapter: BotFrameworkAdapter = inner_dc.context.adapter
    await bot_adapter.sign_out_user(inner_dc.context, self.connection_name)
    await inner_dc.context.send_activity("You have been signed out.")
    return await inner_dc.cancel_all_dialogs()

Exemple de code

Cette section fournit un exemple de Kit de développement logiciel (SDK) Bot Authentication v3.

Exemple de nom	Description	.NET	Node.js	Python	Manifeste
Authentification de bot	Cet exemple montre comment bien démarrer avec l’authentification dans un bot pour Teams.	View	View	View	View
Authentification unique Tab, Bot et Message Extension (ME)	Cet exemple montre Microsoft Entra authentification unique pour Tab, Bot et ME : recherche, action, déploiement de lien.	View	View	N/A	View

Ajouter l’authentification à votre bot Teams

Configuration requise

Créer le groupe de ressources

Créer le plan de service

Créer une inscription de ressource Azure Bot

Créer un fournisseur d’identité

Configurer la connexion du fournisseur d’identité et l’inscrire auprès du bot

Microsoft Azure Active Directory (Azure AD) v1

Microsoft Azure Active Directory (Azure AD) v2

Tester la connexion

Préparer l’exemple de code du bot

Déployer le bot sur Azure

Tester le bot à l’aide de la Emulator

Configurer le Emulator pour l’authentification

Tester le bot de conversation

Tester le bot de conversation

Installer et tester le bot dans Teams

Test du bot localement dans Teams

Informations supplémentaires

TeamsAppManifest/manifest.json

Gestion de l’activité Invoke

TeamsActivityHandler.cs

Exemple de code

Voir aussi

Commentaires

Ressources supplémentaires