Ejercicio: Creación de un complemento de Office para Word que implementa el inicio de sesión único
En este ejercicio, creará un complemento de Word que inserta detalles sobre el usuario que ha iniciado sesión actualmente 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 Word requiere el cliente web o los clientes de escritorio siguientes:
- Windows v16.0.12215.20006 (o superior)
- macOS v16.32.19102902 (o superior)
Usará Node.js para crear el complemento personalizado de Word en este módulo. En los ejercicios de este módulo se supone que tiene las herramientas siguientes 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 versión de LTS activa)
- NPM (instalado con Node.js)
- Yeoman : v4.x (o superior)
- Generador de Yeoman para Microsoft Office : v1.8.8
- Visual Studio Code
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.
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? MyWordSsoAddin
- ¿Qué aplicación cliente de Office quiere admitir? Word
Después de completar las solicitudes, el generador creará el proyecto e instalará componentes auxiliares de Node.
Explorar el proyecto inicial
Todos los proyectos de complementos de Word incluyen varias carpetas y archivos que implementan un complemento para Microsoft Word. El complemento se implementa principalmente en las carpetas ./src/commands y ./src/taskpane. Los archivos de estas dos carpetas implementan el complemento básico del panel de tareas y los comandos opcionales para desencadenar el complemento.
Echemos un vistazo a algunos de los otros archivos agregados al proyecto que admiten la implementación de una experiencia de SSO para los usuarios. Estos archivos se pueden encontrar en la carpeta ./src/helpers.
- documentHelper.js: este archivo usa la biblioteca de API de JavaScript de Office para recuperar los datos de Microsoft Graph y agregarlos al documento de Word.
- fallbackauthdialog.html: este archivo es la página sin la UI que carga la estrategia de autenticación de reserva de JavaScript.
- fallbackauthdialog.js: este archivo contiene JavaScript para la estrategia de autenticación que usa la Biblioteca de autenticación de Microsoft para JavaScript (MSAL.js) a fin de que el usuario inicie sesión.
- fallbackauthhelper.js: este archivo contiene JavaScript para el panel de tareas que invoca la estrategia de autenticación de reserva en escenarios en los que no se admite la autenticación SSO.
- ssoauthhelper.js: este archivo contiene JavaScript que llama a la API de SSO,
getAccessToken(), recibe el token de arranque e inicia el intercambio del token de arranque por un token de acceso que se puede usar para llamar a Microsoft Graph. Este archivo también incluye el código para llamar al punto de conexión de Microsoft Graph.
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.
Registro de la aplicación de Azure Active Directory (Azure AD)
En una unidad anterior, ha aprendido que un complemento de Office debe tener asociado un registro de aplicación de Azure AD para que el usuario inicie sesión y obtenga un token de acceso para llamar a Microsoft Graph.
Para poder probar el proyecto, deberá registrar la aplicación de Azure AD y, a continuación, actualizar el proyecto para que use la aplicación de Azure AD.
Sugerencia
Para más información sobre cómo registrar manualmente la aplicación de Azure AD, vea: Crear un complemento de Office de Node.js que use el inicio de sesión único: registrar el complemento con el punto de conexión v2.0 de Azure AD.
El proyecto de complemento de Office incluye una utilidad que puede crear el registro de la aplicación de Azure AD y actualizar el proyecto.
Desde el símbolo del sistema, asegúrese de que está actualmente en la carpeta raíz del proyecto. Ejecute el siguiente comando:
npm run configure-sso
El comando iniciará un navegador y le pedirá que inicie sesión en Azure AD. Asegúrese de iniciar sesión como un usuario que tenga permisos para registrar una aplicación de Azure AD, como un usuario asignado al rol de Administrador global.
Después de la autenticación, el script realizará las tareas siguientes:
- Registrar la aplicación Azure AD
- 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 Id. de cliente de la aplicación de Azure AD
Advertencia
El comando configure-sso producirá un error si el espacio empresarial de Azure AD 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 de Azure AD como se describe en el artículo Crear un complemento de Node.js Office que usa el inicio de sesión único: registrar el complemento con el punto de conexión de Azure AD v2.0.
Vamos a examinar el trabajo realizado por el script configure-sso.
Abra un explorador y navegue hasta el Centro de administración de Azure Active Directory (https://aad.portal.azure.com)). Inicie sesión con una Cuenta profesional o educativa que tenga derechos de administrador global de la tenencia.
Seleccione Azure Active Directory en el panel de navegación del extremo izquierdo.
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 la aplicación MyWordSsoAddin. Es el mismo nombre de la aplicación que creó anteriormente con el generador de Yeoman para Microsoft Office.
En la página MyWordSsoAddin, tome nota del Id. de aplicación. El script configure-sso que creó la aplicación de Azure AD establece este valor en el archivo .ENV del proyecto:
CLIENT_ID=056b1e8c-747d-4b45-94b1-f61ac2c19a5e
GRAPH_URL_SEGMENT=/me
NODE_ENV=development
PORT=3000
QUERY_PARAM_SEGMENT=
SCOPE=User.Read
Autenticación
A continuación, en el panel de navegación situado más a la izquierda, seleccione Administrar>Autenticación. Observe que los URI de redirección se establecen en las páginas taskpane.html y fallbackauthdialog.html de nuestra aplicación.
Tenga en cuenta también que la sección Concesión implícita y flujos híbridos se ha actualizado para garantizar que Azure AD devuelva tokens de acceso y tokens de identificador cuando un usuario se autentique en la aplicación:
Certificados y secretos
A continuación, en el panel de navegación situado más a la izquierda, seleccione Administrar>Autenticación. Observe que los URI de redireccionamiento están en el panel de navegación situado más a la izquierda y seleccione Administrar>secretos de certificados&.
El script configure-sso creó un secreto de cliente para la aplicación. Esto se mostró en el símbolo del sistema como vio anteriormente y agregó el almacén de secretos de la estación de trabajo del desarrollador.
Permisos de API
En el panel de navegación situado más a la izquierda, seleccione Administrar>Permisos de API. Observe cómo se han configurado varios permisos delegados para la aplicación. El script console-sso también concedió el consentimiento del administrador a todos los usuarios del espacio empresarial, por lo que no se les pedirá que den su consentimiento a la aplicación la primera vez que la usen.
Exponer una API: URI de identificador de aplicación
Por último, seleccione Administrar>Exponer una API en el panel de navegación situado más a la izquierda. Hay varios aspectos que se deben tener en cuenta en esta página:
En primer lugar, observe el URI del identificador de la aplicación. Este es el identificador único de nuestra aplicación. Observe que tiene el identificador de la aplicación en la cadena completa.
Exponer una API: ámbitos definidos por la API
En la sección a continuación se incluyen los ámbitos definidos por la API. Pueden ser ámbitos personalizados que permiten restringir el acceso a los datos y la funcionalidad protegidos por la API. En nuestro caso, la aplicación configure-sso, agregó el ámbito siguiente:
api://localhost:3000/056b1e8c-747d-4b45-94b1-f61ac2c19a5e/access_as_user
El identificador del ámbito coincidirá con el identificador de la aplicación. Observe el final del ámbito. Este ámbito, access_as_user, permite que las aplicaciones cliente de Office usen las API web del complemento con los mismos derechos que el usuario que ha iniciado sesión.
Exponer una API: aplicaciones cliente autorizadas
En la última sección se indica que la API confiará automáticamente en estas aplicaciones específicas y no solicitará el consentimiento del usuario cuando la aplicación llame a esta API.
Esto autoriza a las aplicaciones web y de escritorio de Office a llamar a la API del complemento.
Las aplicaciones enumeradas son las siguientes:
- Microsoft Office:
d3590ed6-52b3-4102-aeff-aad2292ab01c - Microsoft Office:
ea5a67f6-b6f3-4338-b240-c655ddc3cc8e - Office en la Web:
57fb890c-0dab-4253-a5e0-7188c88b2bb4 - Office en la Web:
08e18876-6177-487e-b8b5-cf950c1e598c - Outlook en la Web:
bc59ab01-8403-45c6-8796-ac3ef710b3e3
Si selecciona una de estas aplicaciones, cada una de ellas tiene el ámbito definido anteriormente como ámbito autorizado.
Compilar y probar la aplicación
Ejecute el comando siguiente en un símbolo del sistema para transpilar e iniciar el proceso de depuración:
npm start
El script start hará tres cosas:
- crear el proyecto de complemento
- iniciar un servidor web local para hospedar el complemento en la estación de trabajo local
- iniciar el cliente de Office y transferir localmente el complemento de Office en él
Sugerencia
Asegúrese de supervisar el símbolo del sistema. Es posible que se le pida que escriba la contraseña para completar el proceso de inicio, instalación de prueba y depuración.
Probar el complemento en el cliente de escritorio de Word
Después de un momento, Word 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.
Una vez que el usuario inicia sesión, el complemento recuperará la información básica del perfil de Microsoft Graph y la agregará al documento.
Probar el complemento en el cliente web de Word
Para ver el inicio de sesión único en acción, pruebe el complemento en el cliente web de Office desde OneDrive.
Abra un explorador y vaya a OneDrive (https://onedrive.com). Inicie sesión con una cuenta profesional o educativa.
Seleccione el botón Nuevo y, a continuación, Documento de Wordpara agregar un nuevo documento de Word.
Instale el complemento de Word mediante la instalación de prueba. 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, a continuación, el botón Obtener mi información de perfil de usuario.
Dado que ya ha iniciado sesión, después de un momento, verá que aparece la misma información de perfil en el documento sin tener que iniciar sesión.
Explorar el proyecto
Ahora vamos a explorar cómo el complemento de Word usa SSO para conectarse a Microsoft Graph y mostrar la información de perfil del usuario que ha iniciado sesión en el documento.
Abra el proyecto que creó al principio de este ejercicio en Visual Studio Code.
Busque y abra el archivo ./manifest.xml. En el manifiesto del complemento, busque el elemento SourceLocation:
<OfficeApp>
<DefaultSettings>
<SourceLocation DefaultValue="https://localhost:{PORT}/taskpane.html"/>
</DefaultSettings>
</OfficeApp>
El valor de este elemento indica al cliente de Office de hospedaje la dirección URL que se va a cargar en el IFRAME del panel de tareas.
Busque y abra el archivo ./src/taskpane/taskpane.html. Se pueden observar dos cosas en este archivo:
- En la sección
<head>de la página, observe la referencia<script>al archivo office.js. Este es el SDK de JavaScript de Office que el complemento puede usar para comunicarse con el cliente host de Office. - Desplácese a la parte inferior del archivo hasta el botón
<button id="getGraphDataButton">. Este es el botón que inicia el proceso de obtención de un token de acceso para que el usuario solicite a Microsoft Graph la información de perfil del usuario que ha iniciado sesión.
Busque y abra el archivo ./src/taskpane/taskpane.js. Una vez que el cliente de Office de hospedaje ha cargado el complemento, adjunta el método ssoAuthHelper.getGraphData() al evento de clic del botón del panel de tareas.
Busque y abra el archivo ./src/helpers/ssoauthhelper.js. Este archivo contiene el código que realiza la mayor parte del trabajo de autenticación del usuario mediante SSO y obtención de los datos de perfil del usuario de Microsoft Graph. Todo esto se implementa en el método getGraphData(). Este método realiza las acciones siguientes:
Obtiene un token de acceso de Azure AD para iniciar la sesión del usuario. Este token de acceso, denominado
bootstrapToken, contiene un token de identificador y un token de acceso.Intercambie el token de acceso con Azure AD por uno que se pueda usar para llamar a Microsoft Graph.
El
bootstrapTokenobtenido en el primer paso no contiene los ámbitos necesarios para llamar a Microsoft Graph, ya que se usa para autenticar al usuario y obtener un token de identificador.Nota:
El método
sso.getGraphToken()llamado en este paso llama al punto de conexiónhttps://graph.microsoft.com/v1.0/autha fin de obtener un token de acceso que se pueda usar para Microsoft Graph.Envíe una solicitud a la API de REST de Microsoft Graph para obtener los datos de perfil del usuario. Esto se hace llamando al método
sso.makeGraphApiCall().Nota:
El método
sso.makeGraphApiCall()llama al punto de conexión dehttps://graph.microsoft.com/v1.0/getuserdatapara recuperar la información de perfil del usuario.
Si se produce un error en cualquier punto del proceso de autenticación, el código usa un proceso de autenticación de reserva mediante los archivos ./src/helpers/fallbackauth*.* .
El código agregado por el generador de Yeoman para Microsoft Office al proyecto de complemento inicial recupera la información de perfil del usuario de Microsoft Graph. En los demás ejercicios de este módulo se mostrará cómo solicitar información adicional a Microsoft Graph.