Ajouter une boîte de dialogue aux modèles de cartes adaptatives (préversion)

Vous pouvez améliorer les réponses de carte adaptative dans les agents déclaratifs pour Microsoft 365 Copilot en ajoutant des boîtes de dialogue modales. Ces boîtes de dialogue contextuelles peuvent héberger du code HTML/JavaScript personnalisé ou afficher des widgets iframe, tels que des pages web, des vidéos YouTube ou du contenu Microsoft Stream, dans une expérience interactive ciblée.

Cet article décrit comment lancer des boîtes de Action.OpenUrlDialog dialogue modales à partir de modèles de carte adaptative (disponible dans le schéma Adaptive Card version 1.5) et comment configurer l’authentification des utilisateurs.

Remarque

L’action OpenUrlDialog est actuellement en préversion.

Configuration requise

Pour utiliser Action.OpenUrlDialog, vous devez disposer des conditions préalables suivantes :

  • Schéma de la carte adaptative version 1.5
  • Manifeste du plug-in d’API version 2.3
  • Bibliothèque Microsoft TeamsJS (pour les scénarios d’authentification)

Définir le modèle de carte adaptative

Pour utiliser l’action de boîte de dialogue modale :

L’exemple suivant montre le schéma de Action.OpenUrlDialog.

"actions": [
     {
         "type": "Action.OpenUrlDialog",
         "title": "OpenDialogWithDimension",
         "url": "${url}",
         "dialogHeight": "large",
         "dialogWidth": "600px",
         "dialogTitle": "task module"
     }
    ]

Pour plus d’informations sur les informations de référence de schéma, consultez Action.OpenUrlDialog.

Configurer la taille de la boîte de dialogue

Utilisez les propriétés dialogHeight et dialogWidth pour définir la hauteur et la largeur de la boîte de dialogue. Ces valeurs s’ajustent dynamiquement en fonction de la résolution d’écran de l’utilisateur et de la taille de la fenêtre.

Vous pouvez spécifier :

  • Tailles prédéfinies - small, medium, ou large.
  • Valeurs de pixel personnalisées - par exemple, 400px. 600px

Conseil

Utilisez des valeurs de pixels pour un contrôle précis. Les tailles prédéfinies sont relatives à l’espace d’écran disponible.

L’image suivante montre un exemple de boîte de dialogue appelée à partir d’un bouton de carte adaptative retourné par un agent.

Image d’une boîte de dialogue permettant aux utilisateurs d’entrer des informations sur le client

Configurer l’authentification

Pour autoriser l’accès sécurisé aux API à partir de la boîte de dialogue, configurez l’authentification à l’aide de l’une des méthodes suivantes :

  • Microsoft Entra ID
  • OAuth 2.0 (préversion)

Configuration de Microsoft Entra ID

Pour utiliser l’authentification Entra ID pour l’authentification API, utilisez l’une des approches suivantes :

  • Configurez l’authentification basée sur l’ID Entra, OAuth 2.0 ou la clé API à l’aide de Microsoft comme fournisseur d’identité.
  • Utilisez un autre fournisseur d’identité et inscrivez votre application dans Entra ID.

Configurer l’authentification basée sur l’authentification unique

Configurez l’authentification unique (SSO) pour permettre aux utilisateurs d’accéder aux API sans avoir à se connecter plusieurs fois.

Pour activer l’authentification unique :

  1. Mettez à jour l’application Microsoft Entra ID.
    • Configurez l’URI d’ID de l’application.
    • Configurez les étendues et les paramètres de consentement.
    • Préautorisez les applications clientes approuvées pour éviter les invites de consentement répétées.
  2. Implémenter une logique de récupération et de validation des jetons.
    • Utilisez la getAuthToken() méthode de la bibliothèque TeamsJS pour récupérer un jeton d’accès.
    • Envoyez le jeton à votre serveur dans l’en-tête Authorization.
    • Validez le jeton côté serveur.
  3. Mettez à jour le manifeste de l’application.
    • Ajoutez la propriété webApplicationInfo au manifeste de l’application pour activer l’authentification unique.
    • Ajoutez le domaine du contenu de la boîte de dialogue à la propriété validDomains du manifeste de l’application.

Mettre à jour l’application Microsoft Entra ID

Pour configurer des étendues et autoriser des applications clientes approuvées, mettez à jour votre application Microsoft Entra ID comme suit :

  1. Ajoutez un URI d’API à la propriété identifierUris du manifeste de l’application. Utilisez le format suivant pour l’URI : « api://fully-qualified-domain-name.com/{AppID} », comme illustré dans l’exemple suivant.

    "identifierUris": [
    "api://b4ab3a28-16da-4a19-a07a-51ab0f3553db",
    "api://4-213-70-45.ngrok-free.app/b4ab3a28-16da-4a19-a07a-51ab0f3553db",
    "api://auth-58bfdecc-2870-4cda-99b4-1d30383b952b/b4ab3a28-16da-4a19-a07a-51ab0f3553db"
    ],
    
  2. Définissez l’étendue de l’API et les personnes autorisées à y consentir. Dans la sectionÉtendues définies par cette API du centre d’administration Microsoft Entra, sélectionnez + Ajouter une étendue.

    Capture d’écran des champs pour ajouter une étendue

    1. Entrez le nom de l’étendue. Ce champ est obligatoire.
    2. Sélectionnez l’utilisateur qui peut donner son consentement pour cette étendue. L’option par défaut est Administrateurs uniquement.
    3. Entrez le nom complet du consentement de l’Administration. Ce champ est obligatoire.
    4. Entrez la description du consentement de l’administrateur. Ce champ est obligatoire.
    5. Entrez le nom d’affichage du consentement de l’utilisateur.
    6. Entrez la description de la description de consentement utilisateur.
    7. Dans le champ État , sélectionnez l’option Activé pour l’état.
    8. Sélectionnez Ajouter une étendue.
  3. Créez des ID client autorisés pour les applications que vous souhaitez pré-autoriser. Cela permet à l’utilisateur de l’application d’accéder aux étendues d’application (autorisations) que vous avez configurées sans nécessiter de consentement supplémentaire. Étant donné que les utilisateurs de l’application n’auront pas la possibilité de refuser leur consentement, préautorisez uniquement les applications clientes auxquelles vous faites confiance.

    1. Dans la section Application cliente autorisée du Centre d’administration Microsoft Entra, sélectionnez + Ajouter une application cliente.

      Capture d’écran avec le bouton Ajouter une application cliente mis en surbrillance

    2. Entrez l’ID client Microsoft 365 pour les applications que vous souhaitez autoriser.

Implémenter une logique de récupération et de validation des jetons

Ajoutez du code pour gérer le jeton d’accès, envoyez le jeton au code du serveur de votre application dans l’en-tête Authorization et validez le jeton d’accès lorsqu’il est reçu.

Pour obtenir l’accès à l’application pour l’utilisateur actuel de l’application, votre code côté client doit effectuer un appel à Teams pour obtenir un jeton d’accès. Mettez à jour votre code côté client à utiliser getAuthToken() pour lancer le processus de validation, comme illustré dans l’exemple suivant.

// Get auth token
// Ask Teams to get us a token from AAD
function getClientSideToken() {
     return new Promise((resolve, reject) => {
         display("1. Get auth token from Microsoft Teams");

         microsoftTeams.authentication.getAuthToken().then((result) => {
             display(result);
             resolve(result);
         }).catch((error) => {
             reject("Error getting token: " + error);
         });
     });
 }

Lorsque Teams reçoit le jeton d’accès, il met en cache le jeton pour le réutiliser en fonction des besoins. Le jeton est utilisé lorsqu’il getAuthToken() est appelé sans qu’il soit nécessaire d’effectuer un autre appel à Microsoft Entra ID, jusqu’à l’expiration du jeton.

Lorsque vous appelez getAuthToken() et que le consentement de l’utilisateur est requis pour les autorisations de niveau utilisateur, l’utilisateur connecté voit s’afficher une boîte de dialogue Microsoft Entra et l’utilisateur doit donner son consentement initial une fois.

Une fois que l’utilisateur a donné, il peut accéder à la page web de la boîte de dialogue. Les points suivants s’appliquent au consentement de l’utilisateur :

  • Si l’administrateur a accordé son consentement au nom du client, les utilisateurs de l’application n’ont pas besoin d’être invités à donner leur consentement. Cela signifie que les utilisateurs de l’application ne voient pas la boîte de dialogue de consentement et peuvent accéder à l’application de manière transparente.
  • Si votre application Microsoft Entra est inscrite dans le même client que celui à partir duquel vous demandez une authentification dans Teams, l’utilisateur de l’application ne peut pas être invité à donner son consentement et un jeton d’accès lui est immédiatement accordé. Les utilisateurs de l’application consentent à ces autorisations uniquement si l’application Microsoft Entra est inscrite dans un autre client.
  • Étant donné que les utilisateurs doivent donner leur consentement pour accéder à l’API et que le consentement n’est requis qu’une seule fois par utilisateur, aucun consentement supplémentaire n’est nécessaire pour les boîtes de dialogue.

Mettre à jour le manifeste de l’application

Configurez la propriété webApplicationInfo dans le fichier manifeste de l’application pour activer l’authentification unique. Cela permet aux utilisateurs de l’agent d’accéder à votre agent en toute transparence. Le tableau suivant répertorie les propriétés de la propriété webApplicationInfo .

Propriété Description
id Entrez l’ID d’application (GUID) que vous avez créé dans Microsoft Entra ID.
ressource Entrez l’URI de sous-domaine de votre application et l’URI d’ID de l’application que vous avez créé dans Microsoft Entra ID lorsque vous avez créé l’étendue.
"webApplicationInfo": {
  "id": "7c7c79df-bf9d-43b7-a464-1cb9995eb3b2",
  "resource": "api://67ec-4-213-76-42.ngrok-free.app/7c7c79df-bf9d-43b7-a464-1cb9995eb3b2"
 }

Spécifiez le domaine de l’URL que vous souhaitez afficher dans la boîte de dialogue de la propriété validDomains du manifeste de l’application, comme illustré dans l’exemple suivant.

"validDomains": [
     "contoso.com",
     "mysite.someplace.com",
     "othersite.someplace.com"
 ]

Programme d’installation d’OAuth 2.0 (préversion)

Pour les agents qui utilisent OAuth 2.0 avec Microsoft Entra ID ou d’autres fournisseurs d’identité, utilisez la authentication.authenticate() fonction de la bibliothèque TeamsJS pour lancer le flux d’authentification.

Pour activer les boîtes de dialogue d’autorisation OAuth 2.0 pour le plug-in d’API :

  • Configurez votre application pour utiliser Microsoft Entra ID comme fournisseur d’identité.
  • Apportez des modifications au code pour démarrer le flux d’authentification et gérer le jeton.

Configurez votre application pour utiliser Microsoft Entra ID comme fournisseur d’identité

Pour configurer votre application afin qu’elle utilise Microsoft Entra ID :

  • Dans le portail Azure, accédez à Inscription de votre application.
  • Sous Authentification, dans la section URI de redirection , ajoutez l’URL de redirection à votre point de terminaison d’authentification. Utilisez le format suivant pour l’URL de redirection : https://<hostname>/auth/simple-start.

Lancer le flux d’authentification et gérer le jeton

La plupart des fournisseurs d’identité n’autorisent pas le placement de contenu dans un iFrame. Cela signifie que vous avez besoin d’une page pour héberger le fournisseur d’identité que Copilot affiche dans une fenêtre contextuelle. Utilisez la authentication.authenticate() fonction de la bibliothèque TeamsJS pour lancer cette page lorsque le bouton Carte adaptative est sélectionné.

Remarque

L’URL à laquelle vous transmettez est authenticate() la page de démarrage du flux d’authentification. Il doit correspondre à ce que vous avez inscrit dans le Portail Azure. Le flux d’authentification doit commencer sur une page de votre domaine. Veillez à répertorier ce domaine dans la propriété validDomains du manifeste.

import { authentication } from "@microsoft/teams-js";

authentication.authenticate({
     url: window.location.origin + "/auth/simple-start",
     width: 600,
     height: 535
 })
.then((result) => {
     console.log("Login succeeded: " + result);
     let data = localStorage.getItem(result);
     localStorage.removeItem(result);
     let tokenResult = JSON.parse(data);
     showIdTokenAndClaims(tokenResult.idToken);
     getUserProfile(tokenResult.accessToken);
 })
.catch((reason) => {
     console.log("Login failed: " + reason);
     handleAuthError(reason);
 });

La page contextuelle redirige vers le fournisseur d’identité afin que l’utilisateur puisse se connecter. L’agent appelle le service d’autorisation Microsoft Entra et transmet les informations sur l’utilisateur et l’application afin qu’il puisse s’authentifier auprès d’Entra ID. Entra ID appelle ensuite la page de rappel que vous avez fournie.

app.getContext().then((context) => {
// Generate random state string and store it, so we can verify it in the callback
     let state = _guid(); // _guid() is a helper function in the sample
     localStorage.setItem("simple.state", state);
     localStorage.removeItem("simple.error");

     // Go to the Azure AD authorization endpoint
     let queryParams = {
         client_id: "{{appId}}",
         response_type: "id_token token",
         response_mode: "fragment",
         scope: "https://graph.microsoft.com/User.Read openid",
         redirect_uri: window.location.origin + "/auth/simple-end",
         nonce: _guid(),
         state: state,
         // The context object is populated by Teams; the loginHint attribute
         // is used as hinting information
         login_hint: context.user.loginHint,
     };

     let authorizeEndpoint = `https://login.microsoftonline.com/${context.user.tenant.id}/oauth2/v2.0/authorize?${toQueryString(queryParams)}`;
     window.location.assign(authorizeEndpoint);
 });

Déterminez la réussite ou l’échec de la demande d’authentification en fonction des informations renvoyées par Entra ID et appelez soit authentication.notifySuccess() ou authentication.notifyFailure(). Si la connexion a réussi, l’utilisateur a accès aux ressources du service.