Ejercicio: Creación de un complemento de Office para Excel que implemente el inicio de sesión único
En este ejercicio, creará un complemento de Excel que agrega una lista de los correos electrónicos recientes recibidos por el usuario que ha iniciado sesión con Microsoft Graph en una hoja de cálculo. Este proceso usa el esquema de autenticación de inicio de sesión único (SSO).
Requisitos previos
El desarrollo de complementos de Office para Microsoft Excel requiere el cliente web o los siguientes clientes de escritorio:
- Windows v16.0.12215.20006 (o superior)
- macOS v16.32.19102902 (o superior)
Usará Node.js para crear el complemento personalizado de Excel en este módulo. En los ejercicios de este módulo se supone que tiene las siguientes herramientas instaladas en su estación de trabajo de desarrollador:
Importante
En la mayoría de los casos, instalar la última versión de las siguientes herramientas es la mejor opción. Las versiones enumeradas aquí fueron usadas la última vez que se publicó y se probó este módulo.
- Node.js (la última versión de LTS)
- NPM (instalado con Node.js): versión 6.x (o posterior)
- Yeoman: versión v3.x (o posterior)
- Generador de Yeoman para Microsoft Office : v1.8.8
- Visual Studio Code
Debe tener las versiones mínimas de estos requisitos previos instaladas en su estación de trabajo.
Importante
Este ejercicio se escribe para trabajar con el generador de Yeoman para Microsoft Office v1.8.8. Asegúrese de usar esta versión mediante la instalación de una versión específica mediante el comando npm install generator-office@1.8.8 --global. Las versiones posteriores del generador se quitaron y, a continuación, cambiaron el scaffolding del proyecto de SSO que no coincide con los pasos de este laboratorio.
Importante
El ejemplo de este ejercicio está pensado para usarse solo como un recurso de aprendizaje y no está pensado para usarse en un escenario de producción porque pasa el token de OAuth que se usa para enviar solicitudes a Microsoft Graph al cliente para realizar la llamada directamente.
Como procedimiento recomendado de seguridad, use siempre el código del lado servidor para realizar llamadas de Microsoft Graph, u otras llamadas que requieran pasar un token de acceso. Nunca devuelva el token OBO al cliente para permitir que el cliente realice llamadas directas a Microsoft Graph. Esto ayuda a proteger el token de ser interceptado o filtrado. Para obtener más información sobre el flujo de protocolo adecuado, consulte el diagrama de protocolos de OAuth 2.0.
Crear el proyecto de complemento
Ejecute el siguiente comando para crear un proyecto de complemento con el generador de Yeoman:
yo office
Nota:
Cuando ejecute el comando yo office, es posible que reciba mensajes sobre las directivas de recopilación de datos de Yeoman y las herramientas de la CLI de complementos de Office. Use la información adecuada que se proporciona para responder a los mensajes.
Cuando se le pida, proporcione la siguiente información para crear el proyecto de complemento:
- Seleccione un tipo de proyecto: proyecto del panel de tareas del complemento de Office que admita el inicio de sesión único
- Seleccione un tipo de script: JavaScript
- ¿Qué nombre quiere asignar al complemento? MyExcelSsoAddin
- ¿Qué aplicación cliente de Office quiere admitir? Excel
Después de completar las solicitudes, el generador creará el proyecto e instalará componentes auxiliares de Node.
Registro de la aplicación Microsoft Entra
A continuación, registre la aplicación Microsoft Entra y actualice el proyecto para que use la aplicación Microsoft Entra.
Sugerencia
Para obtener más información sobre cómo registrar manualmente la aplicación Microsoft Entra, consulte Creación de un complemento de Office Node.js que usa el inicio de sesión único: Registro del complemento con el punto de conexión de Azure AD v2.0.
Desde el símbolo del sistema, asegúrese de que está actualmente en la carpeta raíz del proyecto. Ejecute el comando siguiente:
npm run configure-sso
El comando iniciará un explorador y le pedirá que inicie sesión en Microsoft Entra identificador. Asegúrese de iniciar sesión como un usuario que tenga permisos para registrar una aplicación Microsoft Entra, como un usuario asignado al rol administrador global.
Después de la autenticación, el script realizará las siguientes tareas:
- Registro de la aplicación Microsoft Entra
- Configurar la audiencia y los permisos de la aplicación
- Crear un secreto de cliente y guardarlo en el almacén de secretos de las estaciones de trabajo de desarrollador
- Actualizar el proyecto con el identificador de cliente de la aplicación Microsoft Entra
Advertencia
Se producirá un error en el comando configure-sso si el inquilino de Microsoft Entra está configurado para la autenticación multifactor (MFA)/autenticación en dos fases. En este caso, deberá crear manualmente el registro de la aplicación Microsoft Entra tal como se describe en el artículo Creación de un complemento de Office de Node.js que usa el inicio de sesión único: Registrar el complemento con el punto de conexión de Azure AD v2.0.
Compilar y probar la aplicación
Ejecute el siguiente comando en un símbolo del sistema para transpilar e iniciar el proceso de depuración:
npm start
Probar el complemento en el cliente de escritorio de Excel
Después de un momento, Excel se cargará con el botón del complemento en la cinta de opciones y se cargará en el panel de tareas.
Para probar el complemento, seleccione el botón Obtener mi información de perfil de usuario.
Si aún no ha iniciado sesión con su cliente de Office, se le pedirá que inicie sesión.
Después de iniciar sesión, el complemento recuperará la información de perfil básica de Microsoft Graph y la agregará al documento.
Actualizar la aplicación para mostrar correos electrónicos recientes
Ahora, vamos a actualizar la aplicación del panel de tareas para agregar una lista de los correos electrónicos recientes recibidos por el usuario que ha iniciado sesión con Microsoft Graph.
Actualización de los permisos de la aplicación de Microsoft Entra
Primero se deben conceder permisos a la aplicación Microsoft Entra registrada.
Abra un explorador y vaya al centro de administración de Microsoft Entra (https://aad.portal.azure.com). Inicie sesión con una Cuenta profesional o educativa que tenga derechos de administrador global de la tenencia.
En el panel de navegación situado más a la izquierda, seleccione Administrar>Permisos de API.
Agregue un nuevo permiso seleccionando Agregar un permiso.
En la pantalla Seleccionar una API, seleccione Microsoft Graph y, después, Permisos delegados. Busque y seleccione el permiso Mail.Read y seleccione Agregar permisos.
Después, seleccione Conceder consentimiento de administrador para Contoso y acepte el mensaje de confirmación seleccionando Sí.
Actualizar el complemento de panel de tareas de Excel
El siguiente paso consiste en actualizar el código del complemento.
Actualizar el panel de tareas
Busque y abra ./src/taskpane/taskpane.html.
Busque el siguiente elemento HTML en el panel de tareas:
<div class="ms-firstrun-instructionstep__welcome-body">
Busque la primera viñeta en el HTML y cambie el contenido del elemento span a:
<span class="ms-ListItem-primaryText">Click the <b>Get my last 10 emails</b> button.</span>
Busque la última viñeta en el HTML y cambie el contenido del elemento span a:
<span class="ms-ListItem-primaryText">Your last 10 emails will be displayed in the document.</span>
Busque el botón y cambie el texto a: Get last 10 emails.
Actualizar el código del panel de tareas
Ahora, actualice el código que obtendrá los últimos 10 correos electrónicos del usuario.
Busque y abra el archivo ./src/helpers/ssoauthhelper.js.
Busque el siguiente código en el método getGraphData():
const response = await sso.makeGraphApiCall(exchangeResponse.access_token);
Elimine esta línea y reemplácela por el código siguiente. Este código usa un método diferente en el asistente de SSO para enviar una solicitud específica a Microsoft Graph:
const endpoint = "/me/messages";
const urlParams = "?$select=receivedDateTime,subject,isRead&$orderby=receivedDateTime&$top=10";
const response = await sso.getGraphData(exchangeResponse.access_token, endpoint, urlParams);
A continuación, busque y abra el archivo ./src/helpers/documentHelper.js.
Busque el método writeDataToExcel(). Reemplazará la mayor parte del código de este método, pero debería mantener la estructura básica. Elimine el contenido del método y reemplácelo por el código siguiente:
return Excel.run(function(context) {
const sheet = context.workbook.worksheets.getActiveWorksheet();
// TODO
return context.sync();
});
En primer lugar, reemplace // TODO por el código siguiente para crear algunos encabezados de columna en la hoja:
const rangeHeading = sheet.getRange("A1:D1");
rangeHeading.values = [["Received Date/Time", "Subject", "Read?", "ID"]];
Después, agregue el código siguiente después del código anterior que acaba de agregar. Esto tomará los resultados de la solicitud de Microsoft Graph y los convertirá en una matriz multidimensional para escribirlos en la hoja de cálculo.
A continuación, escriba los resultados en la hoja de cálculo y dé formato a las columnas para que todos los datos sean visibles:
// convert data to a list
const mailResults = result.value;
for (let i = 0; i < mailResults.length; i++) {
if (mailResults[i] !== null) {
let innerArray = [];
innerArray.push(mailResults[i].receivedDateTime);
innerArray.push(mailResults[i].subject);
innerArray.push(mailResults[i].isRead);
innerArray.push(mailResults[i].id);
let data = [];
data.push(innerArray);
let rangeData = sheet.getRange(`A${i+2}:D${i+2}`);
rangeData.values = data;
}
}
rangeHeading.format.autofitColumns();
Compilar y probar la aplicación
Ejecute el siguiente comando en un símbolo del sistema para transpilar e iniciar el proceso de depuración:
npm start
Probar el complemento en Excel
Después de un momento, Excel se cargará con el botón del complemento en la cinta de opciones y se cargará en el panel de tareas. Vamos a probar esto en el cliente web de Excel.
Abra un explorador y vaya a OneDrive (https://onedrive.com). Inicie sesión con una Cuenta profesional o educativa.
Agregue un nuevo libro de Excel seleccionando el botón Nuevo y seleccione Libro de Excel.
Instale el complemento de Excel mediante transferencia local. En la cinta de opciones, seleccione Insertar>Complementos.
El cuadro de diálogo Complementos de Office, seleccione Cargar mi complemento.
Seleccione el archivo manifest.xml en la raíz del proyecto y seleccione Cargar.
Microsoft Word transferirá localmente el complemento y mostrará el botón Mostrar panel de tareas en la cinta de opciones, al igual que el cliente de escritorio.
Seleccione el botón Mostrar panel de tareas y seleccione el botón Obtener los últimos 10 correos electrónicos.
Como ya ha iniciado sesión, después de un momento, verá que los correos electrónicos recientes aparecen en la hoja de cálculo sin tener que iniciar sesión.
