Agregar un cuadro de diálogo a plantillas de tarjeta adaptativa (versión preliminar)

Puede mejorar las respuestas de tarjeta adaptable en agentes declarativos para Microsoft 365 Copilot agregando cuadros de diálogo modales. Estos cuadros de diálogo emergentes pueden hospedar HTML/JavaScript personalizado o mostrar widgets basados en iframe, como páginas web, vídeos de YouTube o contenido de Microsoft Stream, dentro de una experiencia interactiva y concentrada.

En este artículo se describe cómo usar Action.OpenUrlDialog (disponible en el esquema de tarjeta adaptable versión 1.5) para iniciar cuadros de diálogo modales desde plantillas de tarjeta adaptable y cómo configurar la autenticación de usuario.

Nota

La OpenUrlDialog acción está actualmente en versión preliminar.

Requisitos previos

Para usar Action.OpenUrlDialog, necesita los siguientes requisitos previos:

  • Esquema de tarjeta adaptable versión 1.5
  • Manifiesto del complemento de API versión 2.3
  • Biblioteca Microsoft TeamsJS (para escenarios de autenticación)

Definir la plantilla de tarjeta adaptativa

Para utilizar la acción del cuadro de diálogo modal:

En el ejemplo siguiente se muestra el esquema de Action.OpenUrlDialog.

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

Para obtener información de referencia de esquema, consulte Action.OpenUrlDialog.

Configurar tamaño de cuadro de diálogo

Use las propiedades dialogHeight y dialogWidth para establecer la altura y la anchura del cuadro de diálogo. Estos valores se ajustan dinámicamente en función de la resolución de pantalla del usuario y el tamaño de la ventana.

Puede especificar:

  • Tamaños predefinidos: , smallmedium, o large.
  • Valores de píxeles personalizados, por ejemplo, 400px, 600px.

Recomendación

Use valores en píxeles para un control preciso. Los tamaños predefinidos son relativos al espacio de pantalla disponible.

En la imagen siguiente se muestra un ejemplo de un cuadro de diálogo invocado desde un botón de tarjeta adaptable devuelto por un agente.

Imagen de un cuadro de diálogo para que los usuarios introduzcan información del cliente

Configurar autenticación

Para permitir el acceso seguro a las API desde el cuadro de diálogo, configure la autenticación mediante uno de los métodos siguientes:

  • Microsoft Entra ID
  • OAuth 2.0 (versión preliminar)

Configuración de Microsoft Entra ID

Para utilizar la autenticación de ID de Entra para la autenticación de API, utilice uno de los siguientes métodos:

  • Configure el id. de Entra, OAuth 2.0 o la autenticación basada en la clave de API con Microsoft como proveedor de identidades.
  • Utilice otro proveedor de identidad y registre la aplicación en Entra ID.

Configurar la autenticación basada en SSO

Configure el inicio de sesión único (SSO) para permitir que los usuarios accedan a las API sin tener que iniciar sesión varias veces.

Para habilitar SSO:

  1. Actualice la aplicación Microsoft Entra ID.
    • Configure el URI del identificador de la aplicación.
    • Configure los ámbitos y las opciones de consentimiento.
    • Autorice previamente aplicaciones cliente de confianza para evitar solicitudes de consentimiento repetidas.
  2. Implementar la recuperación de tokens y la lógica de validación.
    • Use el getAuthToken() método de la biblioteca TeamsJS para recuperar un token de acceso.
    • Envíe el token a su servidor en el encabezado de autorización.
    • Validar el token del lado servidor.
  3. Actualice el manifiesto de la aplicación.
    • Agrega la propiedad webApplicationInfo al manifiesto de la aplicación para habilitar el SSO.
    • Agregue el dominio del contenido del cuadro de diálogo a la propiedad "validDomains del manifiesto de la aplicación".

Actualizar la aplicación Microsoft Entra ID

Para configurar ámbitos y autorizar aplicaciones cliente de confianza, actualice la aplicación de Microsoft Entra ID de la siguiente manera:

  1. Agrega un URI de API a la propiedad identifierUris del manifiesto de la aplicación. Use el siguiente formato para el URI: 'api://fully-qualified-domain-name.com/{AppID}, como se muestra en el ejemplo siguiente.

    "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. Defina el ámbito de la API y quién puede dar su consentimiento para el ámbito. En la secciónÁmbitos definidos por esta API del Centro de administración de Microsoft Entra, seleccione + Agregar un ámbito.

    Captura de pantalla de los campos para agregar un ámbito

    1. Escriba el nombre del ámbito. Este campo es obligatorio.
    2. Seleccione el usuario que puede dar su consentimiento para este ámbito. La opción predeterminada es solo para administradores.
    3. Escriba el nombre para mostrar del consentimiento del Administrador. Este campo es obligatorio.
    4. Escriba la descripción para obtener el consentimiento del administrador. Este campo es obligatorio.
    5. Escriba el nombre para mostrar de consentimiento del usuario.
    6. Escriba la descripción de la descripción de consentimiento del usuario.
    7. En el campo Estado , selecciona la opción Habilitado para el estado.
    8. Seleccione Agregar ámbito.
  3. Cree identificadores de cliente autorizados para las aplicaciones que desee autorizar previamente. Esto permite al usuario de la aplicación acceder a los ámbitos de aplicación (permisos) que configuró sin necesidad de consentimiento adicional. Dado que los usuarios de la aplicación no tendrán la oportunidad de rechazar el consentimiento, autorice previamente solo las aplicaciones cliente en las que confíe.

    1. En la sección Aplicación cliente autorizada del Centro de administración de Microsoft Entra, seleccione + Agregar una aplicación cliente.

      Captura de pantalla con el botón Agregar una aplicación cliente resaltado

    2. Escriba el id. de cliente de Microsoft 365 para las aplicaciones que desea autorizar.

Implementar la recuperación de tokens y la lógica de validación

Agregue código para controlar el token de acceso, envíe el token al código del servidor de la aplicación en el encabezado de autorización y valide el token de acceso cuando se reciba.

Para obtener acceso a la aplicación para el usuario actual de la aplicación, el código del lado cliente debe realizar una llamada a Teams para obtener un token de acceso. Actualice el código del lado cliente para iniciar getAuthToken() el proceso de validación, como se muestra en el ejemplo siguiente.

// 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);
         });
     });
 }

Cuando Teams recibe el token de acceso, almacena en caché el token para reutilizarlo según sea necesario. El token se usa cuando getAuthToken() se le llama sin necesidad de realizar otra llamada a Microsoft Entra ID, hasta que expira el token.

Cuando llama getAuthToken() y se requiere el consentimiento del usuario para los permisos de nivel de usuario, el usuario que ha iniciado sesión ve un cuadro de diálogo de Microsoft Entra y el usuario debe dar su consentimiento inicial una vez.

Una vez que el usuario dé su consentimiento, podrá acceder a la página web del cuadro de diálogo. Los siguientes puntos se aplican al consentimiento del usuario:

  • Si el administrador ha concedido consentimiento en nombre del inquilino, no es necesario solicitar el consentimiento a los usuarios de la aplicación. Esto significa que los usuarios de la aplicación no verán el cuadro de diálogo de consentimiento y podrán acceder a la aplicación sin problemas.
  • Si la aplicación Microsoft Entra está registrada en el mismo inquilino desde el que solicita una autenticación en Teams, no se podrá pedir al usuario de la aplicación que dé su consentimiento y se le concederá un token de acceso inmediatamente. Los usuarios de la aplicación aceptan estos permisos solo si la aplicación Microsoft Entra está registrada en un inquilino diferente.
  • Dado que los usuarios deben dar su consentimiento para el acceso a la API y el consentimiento solo se requiere una vez por usuario, no se necesita ningún consentimiento adicional para los cuadros de diálogo.

Actualizar el manifiesto de la aplicación

Configure la propiedad webApplicationInfo en el archivo de manifiesto de la aplicación para habilitar el SSO. Esto ayuda a que los usuarios del agente accedan al agente sin problemas. En la tabla siguiente se enumeran las propiedades de la propiedad webApplicationInfo .

Propiedad Descripción
id Escriba el id. de aplicación (GUID) que creó en el id. de Microsoft Entra ID.
recurso Escriba el URI del subdominio de la aplicación y el URI del identificador de aplicación que creó en el identificador de Microsoft Entra ID al crear el ámbito.
"webApplicationInfo": {
  "id": "7c7c79df-bf9d-43b7-a464-1cb9995eb3b2",
  "resource": "api://67ec-4-213-76-42.ngrok-free.app/7c7c79df-bf9d-43b7-a464-1cb9995eb3b2"
 }

Especifique el dominio de la dirección URL que desea representar en el cuadro de diálogo de la propiedad validDomains del manifiesto de la aplicación, como se muestra en el ejemplo siguiente.

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

Configuración de OAuth 2.0 (versión preliminar)

Para los agentes que usan OAuth 2.0 con Microsoft Entra ID u otros proveedores de identidad, use la authentication.authenticate() función de la biblioteca TeamsJS para iniciar el flujo de autenticación.

Para habilitar la autorización de OAuth 2.0 para los cuadros de diálogo del complemento de API:

  • Configure la aplicación para usar Microsoft Entra ID como proveedor de identidades.
  • Realice cambios en el código para iniciar el flujo de autenticación y controlar el token.

Configure la aplicación para usar Microsoft Entra ID como proveedor de identidades

Para configurar la aplicación para que use Microsoft Entra ID:

  • En Azure Portal, vaya al registro de la aplicación.
  • En Autenticación, en la sección URI de redireccionamiento , agregue la dirección URL de redireccionamiento al punto de conexión de autenticación. Usa el siguiente formato para la URL de redireccionamiento: https://<hostname>/auth/simple-start.

Iniciar el flujo de autenticación y controlar el token

La mayoría de los proveedores de identidades no permiten que el contenido se coloque en un iframe. Esto significa que necesita una página para hospedar el proveedor de identidad que Copilot muestra dentro de una ventana emergente. Usa la authentication.authenticate() función de la biblioteca TeamsJS para iniciar esta página cuando se selecciona el botón Tarjeta adaptable.

Nota

La dirección URL a authenticate() la que pasa es la página de inicio del flujo de autenticación. Debe coincidir con lo que registró en el Azure Portal. El flujo de autenticación debe comenzar en una página de su dominio. Asegúrese de enumerar este dominio en la propiedad validDomains del manifiesto.

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 página emergente redirige al proveedor de identidad para que el usuario pueda iniciar sesión. El agente llama al servicio de autorización de Microsoft Entra y pasa la información del usuario y de la aplicación para que el usuario pueda autenticarse en el identificador de Entra. A continuación, Entra ID llama a la página de devolución de llamada que proporcionó.

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);
 });

Determine el éxito o el error de la solicitud de autenticación en función de la información devuelta por el ID de Entra y llame a cualquiera authentication.notifySuccess() o authentication.notifyFailure(). Si el inicio de sesión se realizó correctamente, el usuario tendrá acceso a los recursos de servicio.