Inicio de sesión único (SSO)

  • Artículo

En este artículo, usará el generador de Yeoman para complementos de Office para crear un complemento de Office para Excel, Outlook, Word o PowerPoint que use el inicio de sesión único (SSO).

Nota:

La plantilla de SSO proporcionada por el generador de Yeoman para complementos de Office solo se ejecuta en localhost y no se puede implementar. Si va a crear un nuevo complemento de Office con SSO para fines de producción, siga las instrucciones de Creación de un complemento de Office Node.js que usa el inicio de sesión único.

Requisitos previos

  • Node.js (la última versión de LTS).

  • La versión más reciente de Yeoman y Generador de Yeoman para complementos de Office. Para instalar estas herramientas globalmente, ejecute el siguiente comando desde el símbolo del sistema.

    npm install -g yo generator-office

    Nota:

    Incluso si ya ha instalado el generador Yeoman, recomendamos que actualice el paquete de la versión más reciente desde npm.

  • Si esta usando un equipo Mac y no tiene Azure CLI instalado en el equipo, tiene que instalar Homebrew. El script de configuración de SSO que ejecutará durante este inicio rápido usará Homebrew para instalar Azure CLI y, a continuación, deberá usar Azure CLI para configurar el SSO en Azure.

Creación del proyecto de complemento

Sugerencia

El generador de Yeoman puede crear un complemento de Office habilitado para SSO para Excel, Outlook, Word o PowerPoint con el tipo de script JavaScript o TypeScript. Las siguientes instrucciones especifican JavaScript y Excel, pero debería elegir el tipo de script y la aplicación cliente de Office que mejor se adapten a su escenario.

Ejecute el siguiente comando para crear un proyecto de complemento con el generador Yeoman. Se agregará una carpeta que contiene el proyecto al directorio actual.

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.

  • Elija un tipo de proyecto:Office Add-in Task Pane project supporting single sign-on (localhost)
  • Elija un tipo de script:JavaScript
  • ¿Cómo desea asignarle el nombre al complemento?My Office Add-in
  • ¿Qué aplicación cliente de Office desea admitir? Elija Excel, Outlook, Wordo Powerpoint.

Mensajes y respuestas para el generador de Yeoman en una interfaz de línea de comandos.

Después de completar el asistente, el generador creará el proyecto e instalará componentes auxiliares de Node.

Nota:

Si usa Node.js versión 20.0.0 o posterior, es posible que vea una advertencia cuando el generador ejecute la instalación de que tiene un motor no admitido. Estamos trabajando en una solución para esto. Mientras tanto, la advertencia no afecta al generador ni al proyecto que se genera, por lo que se puede omitir.

Sugerencia

Se pueden pasar por alto las instrucciones de los pasos siguientes que el generador de Yeoman ofrece después de que se haya creado el proyecto de complemento. Las instrucciones paso a paso de este artículo le dan toda la información que necesitará para completar este tutorial.

Explorar el proyecto

El proyecto de complemento que ha creado con el generador Yeoman contiene código para un complemento de panel de tareas compatible con SSO.

Configuración

Los siguientes archivos especifican los valores de configuración del complemento.

  • El archivo ./manifest.xml en el directorio raíz del proyecto define la configuración y las funciones del complemento.

  • El archivo ./.ENV del directorio raíz del proyecto define las constantes que usa el proyecto del complemento.

Panel de tareas

Los siguientes archivos definen la interfaz de usuario y la funcionalidad del panel de tareas del complemento.

  • El archivo ./src/taskpane/taskpane.html contiene el marcado HTML para el panel de tareas.

  • El archivo ./src/taskpane/taskpane.css contiene la CSS que se aplica al contenido en el panel de tareas.

  • El archivo ./src/taskpane/taskpane.js contiene código para inicializar el complemento y también código que usa la biblioteca de API de JavaScript de Office para agregar los datos de Microsoft Graph al documento de Office.

Autenticación

Los siguientes archivos facilitan el proceso de SSO y escriben datos en el documento de Office.

  • En un proyecto de JavaScript, el archivo ./src/helpers/documentHelper.js contiene código que encapsula la información de perfil del usuario para su inserción en el documento de Office actual. No hay ningún archivo de este tipo en un proyecto de TypeScript. En su lugar, el código que recopila la información del perfil está insertado en el archivo ./src/taskpane/taskpane.ts .

  • El archivo ./src/helpers/fallbackauthdialog.html es la página sin interfaz de usuario que carga JavaScript para la estrategia de autenticación de reserva. La <script> etiqueta para cargar JavaScript se inserta en el archivo cuando se ejecuta Webpack.config.js.

  • El archivo ./src/helpers/fallbackauthdialog.js contiene JavaScript para la estrategia de autenticación de reserva que inicia la sesión del usuario con msal.js.

  • El archivo ./src/helpers/message-helper.js contiene JavaScript que muestra u oculta los mensajes de error al usuario.

  • El archivo ./src/helpers/middle-tier-calls.js contiene el JavaScript que llama a la API web para capturar datos.

  • El archivo ./src/helpers/sso-helper.js contiene la llamada de JavaScript a la API de SSO, getAccessToken, recibe el token de acceso e lo incluye en una llamada a Microsoft Graph para los datos. En caso de error o en escenarios en los que no se admite la autenticación de SSO, invoca la estrategia de reserva.

Configuración de SSO

Ahora que el proyecto de complemento se crea y contiene el código necesario para facilitar el proceso de SSO, complete los pasos siguientes para configurar el inicio de sesión único para el complemento.

  1. Vaya a la carpeta raíz del proyecto.

    cd "My Office Add-in"

  2. Ejecute el comando siguiente para configurar el SSO para el complemento.

    npm run configure-sso

    Advertencia

    Si el espacio empresarial está configurado para requerir autenticación de dos factores, este comando producirá un error. En este escenario, tendrá que completar manualmente los pasos de configuración de inicio de sesión único y registro de aplicaciones de Azure siguiendo todos los pasos del tutorial Creación de un complemento de Node.js Office que usa el inicio de sesión único .

  3. Se abrirá una ventana del explorador web y se le pedirá que inicie sesión en Azure. Inicie sesión en Azure con sus credenciales de administrador de Microsoft 365. Estas credenciales se usarán para registrar una nueva aplicación en Azure y configurar las opciones que necesita el SSO.

    Nota:

    Si inicia sesión en Azure durante este paso con credenciales que no son de administrador, el script configure-sso no podrá dar el consentimiento de administrador para el complemento a los usuarios de su organización. Por lo tanto, los usuarios del complemento no tendrán SSO disponible y se les pedirá que inicien sesión.

  4. Una vez que escriba las credenciales, cierre la ventana del explorador y vuelva a la línea de comandos. Durante el proceso de configuración de SSO, verá cómo aparecen en la consola mensajes de estado. Estos mensajes indican que los archivos del proyecto de complemento que el generador de Yeoman creó, se actualizan automáticamente con los datos necesarios para el proceso de SSO.

Prueba del complemento

Si ha creado un complemento de Excel, Word o PowerPoint, complete los pasos de la sección siguiente para probarlo. Si ha creado un complemento de Outlook, complete los pasos de la sección Outlook en su lugar.

Excel, Word y PowerPoint

Complete los pasos siguientes para probar un complemento de Excel, Word o PowerPoint.

  1. Cuando termine el proceso de configuración de SSO, ejecute el comando siguiente para compilar el proyecto, inicie el servidor web local y transfiera localmente el complemento en la aplicación cliente de Office anteriormente seleccionada.

    Nota:

    Los complementos de Office deben usar HTTPS, no HTTP, aunque esté desarrollando. Si se le pide que instale un certificado después de ejecutar uno de los siguientes comandos, acepte el mensaje para instalar el certificado que proporciona el generador de Yeoman. Es posible que también deba ejecutar el símbolo del sistema o el terminal como administrador para que se realicen los cambios.

    npm start

  2. Cuando Excel, Word o PowerPoint se abra al ejecutar el comando anterior, asegúrese de que ha iniciado sesión con una cuenta de usuario que sea miembro de la misma organización de Microsoft 365 que la cuenta de administrador de Microsoft 365 que usó para conectarse a Azure al configurar el inicio de sesión único en el paso 3 de la sección anterior. Esto garantiza las condiciones adecuadas para que el SSO funcione correctamente.

  3. En la aplicación cliente de Office, elija la pestaña Inicio y, a continuación, elija Mostrar panel de tareas para abrir el panel de tareas del complemento.

    Botón de complemento de Excel.

  4. En la parte inferior del panel de tareas, seleccione el botón Obtener la información de mi perfil de usuario para iniciar el proceso de SSO.

  5. Si se muestra una ventana de cuadro de diálogo para solicitar permisos en nombre del complemento, esto significa que el SSO no es compatible con su escenario y el complemento ha recurrido a un método de autenticación de usuario alternativo. Esto puede ocurrir cuando el administrador de inquilinos no ha concedido el consentimiento para que el complemento acceda a Microsoft Graph, o cuando el usuario no haya iniciado sesión en Office con una cuenta de Microsoft o Microsoft 365 Educación o una cuenta profesional válidas. Elija Aceptar para continuar.

    Cuadro de diálogo permisos solicitados con el botón Aceptar resaltado.

    Nota:

    Una vez que el usuario acepte esta solicitud de permisos, ya no se le pedirá nuevamente en el futuro.

  6. El complemento recupera información de perfil del usuario que ha iniciado sesión y la escribe en el documento. En la imagen siguiente se muestra un ejemplo de la información de perfil escrita en una hoja de cálculo de Excel.

    Información del perfil de usuario en la hoja de cálculo de Excel.

Outlook

Complete los pasos siguientes para probar un complemento de Outlook.

  1. Cuando termine el proceso de configuración de SSO, ejecute el comando siguiente para compilar el proyecto e iniciar el servidor web local.

    Nota:

    Los complementos de Office deben usar HTTPS, no HTTP, aunque esté desarrollando. Si se le pide que instale un certificado después de ejecutar uno de los siguientes comandos, acepte el mensaje para instalar el certificado que proporciona el generador de Yeoman. Es posible que también deba ejecutar el símbolo del sistema o el terminal como administrador para que se realicen los cambios.

    npm start

  2. Siga las instrucciones en Transferir localmente complementos de Outlook para realizar pruebas para transferir localmente el complemento en Outlook. Asegúrese de que ha iniciado sesión en Outlook con un usuario que sea miembro de la misma organización de Microsoft 365 que la cuenta de administrador de Microsoft 365 que usó para conectarse a Azure cuando configuró el SSO en el paso 3 de la sección anterior. Esto garantiza las condiciones adecuadas para que el SSO funcione correctamente.

  3. En Outlook, redacte un mensaje nuevo.

  4. En la ventana de redacción de mensajes, elija el botón Mostrar panel de tareas para abrir el panel de tareas del complemento.

    Botón de la cinta de opciones del complemento resaltado en la ventana de mensajes de redacción de Outlook.

  5. En la parte inferior del panel de tareas, seleccione el botón Obtener la información de mi perfil de usuario para iniciar el proceso de SSO.

  6. Si se muestra una ventana de cuadro de diálogo para solicitar permisos en nombre del complemento, esto significa que el SSO no es compatible con su escenario y el complemento ha recurrido a un método de autenticación de usuario alternativo. Esto puede ocurrir cuando el administrador de inquilinos no ha concedido el consentimiento para que el complemento acceda a Microsoft Graph, o cuando el usuario no haya iniciado sesión en Office con una cuenta de Microsoft o Microsoft 365 Educación o una cuenta profesional válidas. Elija Aceptar para continuar.

    Cuadro de diálogo permisos solicitados con el botón Aceptar resaltado.

    Nota:

    Una vez que el usuario acepte esta solicitud de permisos, ya no se le pedirá nuevamente en el futuro.

  7. El complemento recupera información de perfil del usuario que ha iniciado sesión y la escribe en el cuerpo del mensaje de correo.

    La información del perfil de usuario en la ventana de mensajes de redacción de Outlook.

Pasos siguientes

Enhorabuena, ha creado correctamente un complemento de panel de tareas que usa SSO siempre que sea posible y recurre a otro método de autenticación de usuario cuando no lo sea. Para más información sobre cómo personalizar el complemento para agregar una nueva funcionalidad que requiera permisos diferentes, vea Personalizar el complemento Node.js habilitado para SSO.

Solución de problemas

Vea también