Ejercicio: Creación de un complemento de Office para Outlook que implemente el inicio de sesión único
En este ejercicio, creará un complemento de Outlook que agrega una lista de los próximos eventos del calendario al cuerpo de un correo por parte del usuario que inició sesión con Microsoft Graph. 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 Outlook 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 Outlook 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? MyOutlookSsoAddin
- ¿Qué aplicación cliente de Office quiere admitir? Outlook
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 web de Outlook
Abra un navegador y vaya a Outlook (https://outlook.office.com). Inicie sesión con una Cuenta profesional o educativa.
Para crear un mensaje nuevo, seleccione el botón Nuevo mensaje.
En la sección de mensaje nuevo, busque el botón ... en la parte inferior del nuevo mensaje en el mismo pie de página que los botones Enviar y Descartar.
Seleccione el elemento de menú Obtener complementos.
En el cuadro de diálogo Complementos para Outlook, seleccione Mis complementos en el menú de la izquierda.
En la pantalla Mis complementos, seleccione el botón Agregar un complemento personalizado>Agregar desde archivo....
Seleccione el archivo manifest.xml en la raíz de la carpeta del proyecto y seleccione Cargar.
Cuando se le solicite, seleccione el botón Instalar en el cuadro de diálogo Advertencia.
Cierre el cuadro de diálogo y seleccione el botón ... en la parte inferior del correo. Observe que ahora aparece el complemento personalizado:
Seleccione el complemento para abrir el panel de tareas. Cuando aparezca el panel de tareas, seleccione el botón Obtener la información de mi perfil de usuario.
Como ya inició sesión, después de un momento, verá que la información básica del perfil del usuario aparece en el correo sin tener que iniciar sesión.
Actualizar la aplicación para mostrar las próximas reuniones
Ahora, vamos a actualizar la aplicación del panel de tareas para mostrar una lista de próximas reuniones para el usuario que inició sesión actualmente. Esta información se recopilará con Microsoft Graph.
Actualizar el panel de tareas
Busque y abra ./src/taskpane/taskpane.html.
Reemplace el elemento <body> con el HTML siguiente. Esto actualizará la representación del panel de tareas:
<body class="ms-font-m ms-welcome ms-Fabric">
<header class="ms-welcome__header ms-bgColor-neutralLighter">
<img width="90" height="90" src="../../assets/logo-filled.png" alt="Contoso" title="Contoso" />
<h1 class="ms-font-su">My upcoming meetings... </h1>
</header>
<main class="ms-firstrun-instructionstep">
<ul class="ms-List ms-welcome__features">
<li class="ms-ListItem">
<i class="ms-Icon ms-Icon--Ribbon ms-font-xl"></i>
<span class="ms-font-m">Share your day with others...</span>
</li>
</ul>
<section class="ms-firstrun-instructionstep__header">
<h2 class="ms-font-m">This add-in adds a list of your upcoming meetings to the current email.</h2>
<div class="ms-firstrun-instructionstep__header--image"></div>
</section>
<p align="center">
<button id="getGraphDataButton" class="popupButton ms-Button ms-Button--primary"><span class="ms-Button-label">Add
upcoming schedule to email</span></button>
</p>
</div>
</main>
</body>
Actualizar el código del panel de tareas
Ahora, actualice el código que obtendrá los próximos eventos del calendario 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.
Esta consulta obtendrá todas las reuniones en el calendario del usuario actual a partir de la hora actual y para las próximas 24 horas:
const startDate = new Date();
let endDate = new Date(startDate);
endDate.setDate(startDate.getDate() + 1);
const endpoint = "/me/calendarview";
const urlParams = `?startdatetime=${ startDate.toISOString() }&enddatetime=${ endDate.toISOString() }&$select=subject,start,end`;
const response = await sso.getGraphData(exchangeResponse.access_token, endpoint, urlParams);
Después, busque y abra el archivo ./src/helpers/documentHelper.js.
Busque el método writeDataToOutlook(). Reemplazará el contenido de este método para crear una cadena HTML de las próximas reuniones devueltas desde la solicitud de Microsoft Graph y agregará la lista al correo actual.
Reemplace el contenido del método writeDataToOutlook() por el código siguiente:
let emailMessage = "";
result.value.forEach(function(meeting){
let startDateTime = new Date(meeting.start.dateTime + "Z");
let endDateTime = new Date(meeting.end.dateTime + "Z");
emailMessage += `<li><strong><em>${startDateTime.toLocaleTimeString()}-${endDateTime.toLocaleTimeString()}</em></strong><br />${meeting.subject}</li>`;
});
// wrap meeting
emailMessage = `Here's what my upcoming calendar looks like for the rest of the day: <ul>${emailMessage}</ul>`;
Office.context.mailbox.item.body.setSelectedDataAsync(emailMessage, { coercionType: Office.CoercionType.Html });
Creación de una nueva aplicación de Microsoft Entra para el complemento
En los ejercicios anteriores de este módulo se usó el script de utilidad configure-sso que se incluye con todos los proyectos creados con el generador de Yeoman para Microsoft Office. En este ejercicio, aprenderá a registrar manualmente una aplicación Microsoft Entra y a configurar el entorno de desarrollador para que use la aplicación creada manualmente.
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 en el espacio empresarial.
Seleccione Microsoft Entra id. en el panel de navegación situado más a la izquierda.
Registro de la aplicación
Seleccione Administrar>Registros de aplicaciones en el panel de navegación situado más a la izquierda.
En la página Registros de aplicaciones, seleccione Nuevo registro y establezca los siguientes valores en la pantalla Registrar una aplicación. Cuando termine, seleccione el botón Registrar.
- Nombre: MyOutlookSsoAddin2
- Tipos de cuenta admitidos: Cuentas en cualquier directorio organizativo (cualquier directorio Microsoft Entra multiinquilino)
- URI de redirección (opción): dejar el valor predeterminado en blanco
Autenticación de aplicaciones
El siguiente paso es configurar los detalles de registro de la aplicación.
Después, en el panel de navegación izquierdo, seleccione Administrar>Autenticación.
En la pantalla Autenticación, seleccione Agregar una plataforma. A continuación, seleccione la plataforma web en la lista de opciones:
En elURI de redirección, escriba https://localhost:3000/taskpane.html.
Para la concesión implícita y los flujos híbridos, seleccione las dos opciones siguientes y, después, seleccione Configurar:
- Tokens de acceso (usados para flujos implícitos)
- Tokens de identificador (usados para flujos implícitos e híbridos)
Después de que se vuelva a cargar la pantalla, seleccione Agregar URI en la plataforma web y escriba https://localhost:3000/fallbackauthdialog.html.
Seleccione Guardar en la parte superior de la pantalla para guardar los cambios.
Secretos y certificados de aplicación
Ahora debe crear un secreto de cliente para la aplicación
Seleccione Certificados & secretos en el panel de navegación situado más a la izquierda.
Seleccione el botón Nuevo secreto de cliente:
Cuando se le solicite, agregue una descripción al secreto y seleccione una de las opciones de duración de expiración que se proporcionan y, a continuación, Agregar. Lo que especifique y seleccione no importa para el ejercicio.
La página Certificados& y Secretos mostrará el nuevo secreto.
Importante
Es importante que copie este valor, ya que solo se muestra esta vez; si deja la página y vuelve, solo se mostrará como un valor enmascarado.
Después de copiar el secreto de cliente, vamos a copiar también el identificador de cliente. En el panel de navegación izquierdo, seleccione Administrar>Información general.
Permisos de API
Después, debe conceder a la aplicación permisos para Microsoft Graph.
En el panel de navegación izquierdo, seleccione Administrar>Permisos de API.
Se recomienda solicitar solo los permisos que necesita la aplicación. Por lo tanto, vamos a quitar el permiso User.Read inicial; para ello, selecciónelo y luego haga clic en Quitar permiso, seguido de Sí, quitar para confirmar.
Después, agregaremos los permisos mínimos necesarios para que los usuarios inicien sesión mediante SSO.
Para agregar un nuevo permiso, seleccione Agregar permiso.
En la pantalla Seleccionar una API, seleccione Microsoft Graph y, después, Permisos delegados. Seleccione los siguientes permisos en las secciones siguientes o use el cuadro de búsqueda para encontrarlos:
- Permisos de OpenID
- OpenID
- perfil
- Calendarios
- Calendars.Read
Una vez que haya seleccionado estos permisos, seleccione el botón Agregar permisos.
Después, seleccione Conceder consentimiento de administrador para Contoso y acepte el mensaje de confirmación seleccionando Sí.
Exponer una API: URI de identificador de aplicación
Por último, seleccione Administrar>Exponer una API en el panel de navegación del extremo izquierdo. Hay varias cosas que hacer en esta página:
En primer lugar, seleccione Establecer junto a laURI de id. de la aplicación. Este es el identificador único de nuestra aplicación. Agregue localhost:3000/ justo antes del protocolo y el identificador de la aplicación para que tenga un aspecto similar al siguiente y seleccione Guardar:
api://localhost:3000/f7b53c32-c205-40d8-84dc-0c15b662054c
Nota:
El GUID es el identificador único de cada aplicación. El identificador no coincidirá con el que se muestra en este ejercicio.
Exponer una API: ámbitos definidos por la API
En la sección a continuación se incluyen los ámbitos definidos por la API. Estos pueden ser ámbitos personalizados que permiten restringir el acceso a los datos y la funcionalidad protegidos por la API.
Seleccione Agregar un ámbito y use los siguientes valores para completar el formulario:
- Nombre del ámbito: access_as_user
- ¿Quién puede dar su consentimiento? Administradores y usuarios
- Nombre para mostrar del consentimiento del administrador: Office puede actuar como el usuario
- Descripción de consentimiento de administrador: permitir a Office llamar a las API de la web del complemento con los mismos derechos que el usuario actual.
- Nombre para mostrar del consentimiento del usuario: Office puede actuar como usted
- Descripción de consentimiento del usuario: permite a Office llamar a las API de la web del complemento con los mismos derechos que usted.
- Estado: Habilitado
Exponer una API: aplicaciones cliente autorizadas
La última sección indica que la API confiará automáticamente en aplicaciones específicas y no pedirá consentimiento al usuario cuando la aplicación llame a esta API.
Esto autoriza eficazmente a las aplicaciones web y de escritorio de Office a llamar a la API del complemento.
Seleccione Agregar una aplicación cliente para agregar las siguientes aplicaciones. Las aplicaciones se agregan como GUID. Para cada una de ellas, asegúrese de seleccionar los únicos Ámbitos autorizados enumerados para conceder a la aplicación acceso al ámbito definido anteriormente:
d3590ed6-52b3-4102-aeff-aad2292ab01c(Microsoft Office)ea5a67f6-b6f3-4338-b240-c655ddc3cc8e(Microsoft Office)57fb890c-0dab-4253-a5e0-7188c88b2bb4(Office en la Web)08e18876-6177-487e-b8b5-cf950c1e598c(Office en la Web)bc59ab01-8403-45c6-8796-ac3ef710b3e3(Outlook en la Web)93d53678-613d-4013-afc1-62e9e444a0a5(Office en la Web)
Si selecciona una de estas aplicaciones, cada una de ellas tiene el ámbito definido anteriormente como ámbito autorizado.
Actualización de la estación de trabajo del proyecto y del desarrollador
Con la aplicación Microsoft Entra creada, el último paso es actualizar el proyecto y la estación de trabajo para usar la nueva aplicación.
Dentro del proyecto, busque y abra el archivo .ENV.
Actualice el CLIENT_ID para usar el identificador de cliente que copió del proceso de registro de la aplicación.
Busque y abra el archivo ./manifest.xml. Al final del archivo, busque el elemento <WebApplicationInfo>. Dentro de este elemento, actualice los elementos <ID> y <Resource> para usar el nuevo identificador de cliente.
Busque y abra el archivo de /src/helpers/fallbackauthdialog.js. Busque la línea que empieza por const msalConfig. Este es el objeto de configuración de MSAL.js. Actualice la propiedad clientId del objeto para que sea el nuevo identificador de cliente.
Después, debe guardar el secreto de cliente de la aplicación en el almacén de credenciales de la estación de trabajo del desarrollador. La petición de ejecución depende de la plataforma.
Windows
Ejecute el siguiente PowerShell, después de actualizar los tres primeros valores:
$ssoAppName: el nombre del proyecto, como MyOutlookSsoAddin$user: el nombre de usuario de inicio de sesión de Windows, como MyDomain\MyUserName$secret: el secreto de cliente que copió al registrar la aplicación Microsoft Entra
$ssoAppName = "MyOutlookSsoAddin"
$user = "MyDomain\MyUserName"
$secret = "....."
[void][Windows.Security.Credentials.PasswordVault, Windows.Security.Credentials, ContentType = WindowsRuntime]
$creds = New-Object Windows.Security.Credentials.PasswordCredential
$creds.Resource = $ssoAppName
$creds.UserName = $user
$creds.Password = $secret
$vault = New-Object Windows.Security.Credentials.PasswordVault
$vault.Add($creds)
macOS
Ejecute lo siguiente en la consola, después de actualizar los tres primeros valores:
SSOAPPNAME: el nombre del proyecto, como MyOutlookSsoAddinUSER: el nombre de usuario de inicio de sesión de macOS, como myusernameSECRET: el secreto de cliente que copió al registrar la aplicación Microsoft Entra
SSOAPPNAME="MyOutlookSsoAddin"
USER="myusername"
SECRET="...."
sudo security add-generic-password -a $USER -s $SSOAPPNAME -w $SECRET -U
Compilar y volver a 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
Volver a probar el complemento en el cliente web de Outlook
Abra un navegador y vaya a Outlook (https://outlook.office.com). Inicie sesión con una Cuenta profesional o educativa.
Repita el proceso de prueba del complemento que hizo al principio de este ejercicio, Sin embargo, antes de activar el complemento, debe quitarlo porque el complemento instalado actualmente sigue usando el archivo manifest.xml antiguo con el registro de aplicación de Microsoft Entra anterior.
Para quitar el complemento, siga los mismos pasos para instalar un nuevo complemento, excepto antes de cargar el archivo manifest.xmlpersonalizado, quite el complemento instalado anteriormente:
Después de instalar el archivo manifest.xml del complemento actualizado, complete el proceso de prueba para probar la nueva lógica del complemento.
