Ajouter l’authentification à votre bot Teams

Vous pouvez créer des robots dans Microsoft Teams qui accèdent aux ressources pour le compte d’utilisateurs (par exemple, un service de messagerie) en utilisant l’authentification du Kit de développement logiciel (SDK) Teams 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 d’authentification et d’autorisation utilisée 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.

Voici les titres des sections de cet article :

• Comment créer un bot compatible avec l’authentification : utilisez cs-auth-sample pour gérer les informations d’identification de connexion des utilisateurs et générer le jeton d’authentification.
• Comment déployer le bot dans 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 à des ressources, telles qu’un service de messagerie, qui nécessite une authentification.
• Comment intégrer le bot dans Microsoft Teams : une fois le bot intégré, vous pouvez vous connecter et échanger des messages avec lui dans une conversation.

Configuration requise

• Connaissance des concepts de base des bots et du SDK Teams.

• Connaissance du développement Azure et OAuth 2.0

• Versions les plus récentes de Microsoft Visual Studio et de Git.

• Accédez à votre compte Azure. Si nécessaire, vous pouvez créer un compte gratuit Azure.

• L’exemple suivant :

  Échantillon
  Démarrage rapide de l’authentification du bot dans cs-auth-sample
  Démarrage rapide de l’authentification du bot dans js-auth-sample
  Démarrage rapide de l’authentification du bot dans py-auth-sample

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. Nous vous recommandons de garder vos ressources organisées et gérables.

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

1. Dans votre navigateur, connectez-vous au portail Microsoft Azure.
2. Dans le volet de navigation gauche, sélectionnez Groupes de ressources.
3. 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. TeamsResourceGroup en est un exemple. 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.

Créer le plan de service

1. Dans le Portail Azure, dans le volet de navigation gauche, sélectionnez Créer une ressource.
2. Dans la zone de recherche, tapez App Service Plan. Sélectionnez la carte plan App Service dans les résultats de la recherche.
3. Sélectionnez Créer.
4. 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. TeamsServicePlan en est un exemple. 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 de bot Azure inscrit votre service web en tant que bot auprès du Azure Bot Service, qui vous fournit un ID d’application Microsoft et un mot de passe d’application (secret client).

1. Visitez Portail Azure et recherchez Azure Bot dans la section Créer une ressource.

2. Ouvrez Le bot Azure , puis sélectionnez Créer.

3. Entrez le nom du handle du bot dans le champ Descripteur de bot.

4. Sélectionnez votre abonnement dans la liste déroulante.

5. Sélectionnez votre groupe de ressources dans la liste déroulante.

6. Sélectionnez le type d’application comme locataire unique. Malgré son nom, ce choix ne limite pas l’installation et l’utilisation du bot dans un locataire.

   

7. Sélectionnez Examiner et créer.

   

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

   Azure provisionne votre bot.

   

9. 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 :

1. Dans Paramètres, sélectionnez Configuration. Enregistrez l’ID d’application Microsoft (ID client) pour référence ultérieure.

   

2. En regard de l’ID d’application Microsoft, sélectionnez Gérer.

   

3. Dans la section Clés secrètes client , sélectionnez Nouvelle clé secrète client. La fenêtre Ajouter une clé secrète client s’affiche.

   

4. Entrez Description , puis sélectionnez Ajouter.

   

5. 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 :

1. Accéder à l’Accueil

   

2. Ouvrez votre bot à partir de la section Ressources récentes .

3. Sélectionnez Canaux dans le volet gauche, puis Microsoft Teams .

   

4. Cochez la case pour accepter les conditions d’utilisation, puis sélectionnez Accepter.
   

   

5. 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 Microsoft Entra ID.

1. Dans le portail Azure, dans le panneau de navigation de gauche, sélectionnez Microsoft Entra ID.

   Conseil

   Vous devez créer et enregistrer cette ressource Microsoft Entra dans un client 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 client, consultez Accéder au portail et créer un locataire.

2. Dans le panneau gauche, sélectionnez ...

3. Dans le volet droit, sélectionnez l’onglet Nouvelle inscription, en haut à gauche.

4. 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 des comptes dans n’importe quel répertoire organisationnel (tout locataire Microsoft Entra ID - multilocataire) et des 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.

5. Une fois qu’Azure a créé l’application, il 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) Utilisez cette valeur plus tard comme ID client lorsque vous inscrivez cette application d’identité Azure avec votre bot.
   2. La valeur d’ID d’annuaire (locataire) Utilisez cette valeur plus tard comme ID de locataire lorsque vous inscrivez cette application d’identité Azure avec votre bot.

6. 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. Utilisez cette valeur ultérieurement comme clé secrète client lorsque vous inscrivez votre application Microsoft Entra auprès de votre bot.

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

Microsoft Azure Active Directory (Azure AD) v1

1. Dans le Portail Azure, sélectionnez votre groupe de ressources dans le tableau de bord.

2. Sélectionnez le lien d’inscription de votre bot.

3. Ouvrez la page de ressources et sélectionnez Configuration sous Paramètres.

4. 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 :

   

5. 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 cette option sélectionnée, 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 les critères suivants :

      • Si vous avez sélectionné Comptes dans ce répertoire organisationnel uniquement (Microsoft uniquement - Locataire unique) ou Comptes dans n’importe quel répertoire organisationnel (Tout locataire Microsoft Entra ID - 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 répertoire organisationnel (Tout locataire Microsoft Entra ID - Multilocataire) et des comptes Microsoft personnels (par exemple, Skype, Xbox), entrez le mot commun au lieu d’un ID de locataire. Dans le cas contraire, l’application Microsoft Entra vérifie le client 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.
   i. Laissez les étendues vides. L’image suivante est un exemple.

   

6. Sélectionnez Enregistrer.

Microsoft Azure Active Directory (Azure AD) v2

1. Dans le Portail Azure, sélectionnez votre bot Azure dans le tableau de bord.

2. Dans la page de ressources, sélectionnez Configuration sous Paramètres.

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

   

4. Remplissez le formulaire comme suit :

   1. Nom. Entrez un nom descriptif pour la connexion. Utilisez 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 cette option sélectionnée, les champs spécifiques d’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 les critères suivants :

      • Si vous avez sélectionné Comptes dans ce répertoire organisationnel uniquement (Microsoft uniquement - Locataire unique) ou Comptes dans n’importe quel répertoire organisationnel (Tout locataire Microsoft Entra ID - 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 répertoire organisationnel (Tout locataire Microsoft Entra ID - Multilocataire) et des comptes Microsoft personnels (par exemple, Skype, Xbox), entrez le mot commun au lieu d’un ID de locataire. Dans le cas contraire, l’application Microsoft Entra vérifie le client dont l’ID a été sélectionné et exclut les comptes Microsoft personnels.

   7. Pour les étendues, entrez une liste délimitée par des espaces d’autorisations de graphique requises par cette application, telles que User.Read, User.ReadBasic.All ou Mail.Read.

5. Sélectionnez Enregistrer.

Tester la connexion

1. Sélectionnez l’entrée de connexion pour ouvrir la connexion que vous avez créée.

2. Sélectionnez Tester la connexion en haut du panneau Paramètres de connexion du fournisseur de services.

3. Pour la première fois, une nouvelle fenêtre de navigateur s’ouvre, vous demandant de sélectionner un compte. Sélectionnez le sous-réseau que vous souhaitez utiliser.

4. Ensuite, autorisez le fournisseur d’identité à utiliser vos données (informations d’identification). L’image suivante est un exemple.

   

5. Sélectionnez Accepter.

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

Déployer le bot sur Azure

Pour déployer le bot, suivez les étapes de la section Déployer votre bot sur Azure.

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

1. Dans l’Explorateur de solutions Visual Studio, sélectionnez et maintenez enfoncé (ou cliquez avec le bouton droit) le nom du projet.

2. Dans le menu déroulant, sélectionnez Publier.

3. Dans la fenêtre affichée, sélectionnez le nouveau lien.

4. Dans la fenêtre de boîte de dialogue, sélectionnez App Service et Créer.

5. Sélectionnez Publier.

6. Dans la fenêtre de dialogue suivante, entrez les informations requises.

   

7. Sélectionnez Créer.

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

9. Dans votre navigateur, accédez au Portail Azure.

10. Vérifiez votre groupe de ressources, le bot est répertorié avec les autres ressources. L’image suivante est un exemple.

    

11. Dans le groupe de ressources, sélectionnez le nom d’inscription du bot (lien).

12. Dans le panneau gauche, sélectionnez Paramètres

13. Dans la zone Point de terminaison de messagerie , saisissez 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.

14. Sélectionnez le bouton Enregistrer dans le coin supérieur gauche.

Tester localement à l’aide de Microsoft 365 Agents Playground

Pour tester votre bot localement, utilisez le Microsoft 365 Agents Playground, qui prend en charge à la fois les agents et les bots.
Pour obtenir des instructions d’installation et de test, consultez Tester votre agent localement avec Microsoft 365 Agents Playground.

Tester le bot de conversation

1. Dans votre navigateur, accédez au Portail Azure.

2. Recherchez votre groupe de ressources.

3. Sélectionnez le lien de ressource. La page de ressource s’affiche.

4. Dans la page de ressources, sélectionnez Tester dans Chat Web. Le bot démarre et affiche les salutations prédéfinies.

5. Tapez n’importe quoi dans la zone de conversation.

6. Sélectionnez la zone Connexion .

7. Une boîte de dialogue contextuelle s’affiche pour confirmer l’URL ouverte pour authentifier l’utilisateur du bot (vous).

8. Sélectionner Confirmer.

9. Si vous y êtes invité, sélectionnez le compte de l’utilisateur applicable. L’image suivante est un exemple d’interface utilisateur du bot après vous être connecté :

   

10. Sélectionnez le bouton Oui pour afficher votre jeton d’authentification. L’image suivante est un exemple.

    

11. Saisissez la déconnexion dans la zone de conversation de saisie pour vous déconnecter.

    

Installer et tester le bot dans Teams

1. Dans votre projet de bot, assurez-vous que le appPackage dossier contient les manifest.json fichiers et color.png les outline.png fichiers.

2. Dans l’Explorateur appPackage de solutions, accédez au 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" ].

3. Sélectionnez et compressez les fichiers, manifest.jsonet outline.png les color.pngfichiers.

4. Ouvrez Microsoft Teams.

5. Dans le volet gauche, en bas, sélectionnez l’icône Applications.

6. Dans le volet droit, en bas, sélectionnez Télécharger une application personnalisée.

7. Accédez au appPackage dossier et téléchargez le manifeste compressé.

8. Sélectionnez Ajouter pour installer l’application sur Teams.

   

9. Recherchez et sélectionnez l’étendue requise ou sélectionnez un canal ou une conversation dans la liste, puis parcourez la boîte de dialogue pour sélectionner Atteindre.

   

   Remarque

   OAuth n’est pas directement pris en charge dans les étendues de conversation de groupe ou de canal. Si vous activez l’authentification et que les utilisateurs installent votre bot dans des conversations de groupe ou des canaux, ils doivent s’authentifier dans leurs étendues personnelles avant de pouvoir utiliser le bot dans la conversation ou le canal de groupe.

10. Sélectionnez les trois points (●●●) dans le panneau de gauche. Sélectionnez ensuite l’icône du portail des développeurs .

11. Sélectionnez l’onglet Éditeur de manifeste . L’icône du bot que vous avez chargé doit s’afficher.

12. 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 exige que tous les services auxquels il accède soient disponibles à partir du cloud en utilisant des 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 machine. Pour configurer ngrok en vue de l’exécution locale de votre application Teams, procédez comme suit :

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

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

   

3. Copiez l’adresse HTTPS de transfert semblable à : https://dea822bf.ngrok.io/.

4. Ajouter /api/messages pour obtenir https://dea822bf.ngrok.io/api/messages, qui est le point de terminaison des messages pour le bot s’exécutant localement sur votre ordinateur et accessible sur le web dans une conversation dans Teams.

5. 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 au 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

6. Démarrez votre bot localement, par exemple en mode de débogage Visual Studio.

7. Testez le bot lors de l’exécution locale à l’aide de Test in Chat Web du portail Azure.

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

   

Informations supplémentaires

appPackage/manifest.json

Ce manifeste contient les informations nécessaires aux équipes pour se connecter avec le bot :

{ 

  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.22/MicrosoftTeams.schema.json", 

  "manifestVersion": "1.22", 

  "version": "1.0.0", 

  "id": "${{TEAMS_APP_ID}}", 

  "developer": { 

    "name": "Teams App, Inc.", 

    "websiteUrl": "https://example.azurewebsites.net", 

    "privacyUrl": "https://example.azurewebsites.net/privacy", 

    "termsOfUseUrl": "https://example.azurewebsites.net/termsofuse" 

  }, 

  "icons": { 

    "color": "color.png", 

    "outline": "outline.png" 

  }, 

  "name": { 

    "short": "Auth Bot", 

    "full": "Auth Bot" 

  }, 

  "description": { 

    "short": "Teams bot with SSO authentication and Graph API integration.", 

    "full": "This bot demonstrates SSO authentication in Microsoft Teams using Azure AD, and uses Microsoft Graph API to retrieve the user profile." 

  }, 

  "accentColor": "#FFFFFF", 

  "bots": [ 

    { 

      "botId": "${{BOT_ID}}", 

      "scopes": [ 

        "personal", 

        "groupChat", 

        "team" 

      ], 

      "supportsFiles": false, 

      "isNotificationOnly": false 

    } 

  ], 

  "permissions": [ 

    "identity", 

    "messageTeamMembers" 

  ], 

  "validDomains": [ 

    "token.botframework.com", 

    "${{BOT_DOMAIN}}" 

  ], 

  "webApplicationInfo": { 

    "id": "${{BOT_ID}}", 

    "resource": "api://botid-${{BOT_ID}}" 

  } 

} 

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

Exemple de code

Cet exemple montre comment implémenter l’authentification à Sign-On unique (SSO) pour les bots Microsoft Teams à l’aide de Azure Active Directory.

Voir aussi

• Obtenir l’accès au nom d’un utilisateur