Agregar un cuadro de diálogo a plantillas de tarjeta adaptable (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 Microsoft Stream) dentro de una experiencia interactiva centrada.

En este artículo se describe cómo usar Action.OpenUrlDialog (disponible en la versión 1.5 del esquema de tarjeta adaptable) 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:

• Versión 1.5 del esquema de tarjeta adaptable
• Versión 2.3 del manifiesto del complemento de API
• Biblioteca de Microsoft TeamsJS (para escenarios de autenticación)

Definición de la plantilla de tarjeta adaptable

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

• Agregue la plantilla tarjeta adaptable al manifiesto del complemento de API.
• Incluya el Action.OpenUrlDialog esquema en la definición de tarjeta adaptable.

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, vea Action.OpenUrlDialog.

Configurar el tamaño del cuadro de diálogo

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

Puede especificar lo siguiente:

• Tamaños predefinidos: small, mediumo large.
• Valores de píxel personalizados: por ejemplo, 400px, 600px.

Sugerencia

Use valores de píxel 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 tarjeta adaptable devuelto por un agente.

Configurar la autenticación

Para permitir el acceso seguro a las API desde dentro del 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 usar Entra ID autenticación para la autenticación de API, use uno de los enfoques siguientes:

• Configure la autenticación basada en claves de API, OAuth 2.0 o Entra ID mediante Microsoft como proveedor de identidades.
• Use otro proveedor de identidades y registre la aplicación en Entra ID.

Configuración de 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 el SSO:

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

Actualización de la aplicación Microsoft Entra ID

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

1. Agregue un URI de API a la propiedad identifierUris del manifiesto de 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 al ámbito. En la secciónÁmbitos definidos por esta API de la Centro de administración Microsoft Entra, seleccione + Agregar un ámbito.

   

   1. Introduzca el nombre del ámbito. Este campo es necesario.
   2. Seleccione el usuario que puede dar su consentimiento para este ámbito. La opción predeterminada es Solo administradores.
   3. Introduzca el nombre para mostrar del consentimiento del administrador. Este campo es necesario.
   4. Introduzca la descripción para el consentimiento del administrador. Este campo es necesario.
   5. Introduzca el nombre para mostrar del consentimiento del usuario.
   6. Introduzca la descripción del consentimiento del usuario.
   7. En el campo Estado , seleccione la opción Habilitado para estado.
   8. Seleccione Agregar ámbito.

3. Cree identificadores de cliente autorizados para las aplicaciones que desea autenticar 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 de la Centro de administración Microsoft Entra, seleccione + Agregar una aplicación cliente.

      

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

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

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

Para obtener acceso a la aplicación para el usuario de la aplicación actual, 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 usarlo getAuthToken() para iniciar 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 que se va a reutilizar según sea necesario. El token se usa cuando getAuthToken() se llama a sin necesidad de realizar otra llamada a Microsoft Entra ID, hasta que expire el token.

Consentimiento del usuario al cuadro de diálogo

Cuando se 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 Microsoft Entra y el usuario debe dar su consentimiento inicial una vez.

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

• Si el administrador concedió el consentimiento en nombre del inquilino, no es necesario pedir consentimiento a los usuarios de la aplicación. Esto significa que los usuarios de la aplicación no ven el cuadro de diálogo de consentimiento y pueden acceder a la aplicación sin problemas.
• Si la aplicación de Microsoft Entra está registrada en el mismo inquilino desde el que solicita una autenticación en Teams, no se puede pedir al usuario de la aplicación que dé su consentimiento y se le conceda un token de acceso de inmediato. Los usuarios de la aplicación dan su consentimiento a estos permisos solo si la aplicación de Microsoft Entra está registrada en un inquilino diferente.
• Dado que los usuarios deben proporcionar 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.

Actualización del manifiesto de la aplicación

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

Propiedad	Descripción
id	Escriba el identificador de aplicación (GUID) que creó en Microsoft Entra ID.
resource	Escriba el URI del subdominio de la aplicación y el URI del identificador de aplicación que creó en 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 identidades, use la authentication.authenticate() función en 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 que use Microsoft Entra ID como proveedor de identidades.
• Realice cambios en el código para iniciar el flujo de autenticación y controlar el token.

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

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

• En el Azure Portal, vaya al registro de la aplicación.
• En Autenticación, en la sección URI de redirección , agregue la dirección URL de redireccionamiento al punto de conexión de autenticación. Use el siguiente formato para la dirección 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 identidades que Copilot muestra dentro de una ventana emergente. Use la authentication.authenticate() función de la biblioteca TeamsJS para iniciar esta página cuando se seleccione el botón Tarjeta adaptable.

Nota:

La dirección URL a la que se pasa authenticate() 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 iniciarse en una página del 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 identidades para que el usuario pueda iniciar sesión. El agente llama al servicio de autorización de Microsoft Entra y pasa información de usuario y aplicación para que el usuario pueda autenticarse en Entra ID. Entra ID, a continuación, 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 Entra ID y llame a o authentication.notifySuccess()authentication.notifyFailure(). Si el inicio de sesión se realizó correctamente, el usuario tiene acceso a los recursos del servicio.

Contenido relacionado

• Esquema de manifiesto del complemento de API