Autenticar y autorizar con la API de cuadros de diálogo de Office

  • Artículo

Use siempre la API del cuadro de diálogo de Office para autenticar y autorizar a los usuarios con el complemento de Office. También debe usar la API de cuadro de diálogo de Office si va a implementar la autenticación de reserva cuando no se puede usar el inicio de sesión único (SSO).

Los complementos de Office se ejecutan en un iframe cuando se abren en Office en la Web. Muchas entidades de identidad, también denominadas Servicios de token seguro (STS), impiden que su página de inicio de sesión se abra en un iframe. Estos incluyen Google, Facebook y servicios protegidos por el Plataforma de identidad de Microsoft (anteriormente Azure AD V 2.0), como una cuenta de Microsoft, una cuenta Microsoft 365 Educación o profesional u otra cuenta común. También las características de seguridad implementadas en la vista web cuando los complementos de Office se ejecutan en Office en Windows o Office en Mac pueden impedir que las páginas de inicio de sesión funcionen correctamente.

Para que la autorización funcione correctamente, la página de inicio de sesión debe abrirse en una instancia de control de vista web o explorador independiente. Por este motivo, Office proporciona la API de diálogo de Office, específicamente el método displayDialogAsync .

Nota:

El cuadro de diálogo abierto con esta API tiene las siguientes características.

  • Es nonmodal.
  • Se trata de una instancia de explorador totalmente independiente del panel de tareas, lo que quiere decir que:
    • Tiene su propio entorno en tiempo de ejecución y objeto de ventana y variables globales.
    • No hay ningún entorno de ejecución compartido en el panel de tareas.
    • No comparte el mismo almacenamiento de sesión (la propiedad Window.sessionStorage ) que el panel de tareas.
  • La primera página abierta en el cuadro de diálogo debe hospedarse en el mismo dominio que el panel de tareas, incluidos el protocolo, los subdominios y el puerto, si existe.
  • El cuadro de diálogo puede devolver información al panel de tareas mediante el método messageParent . Se recomienda llamar a este método solo desde una página hospedada en el mismo dominio que el panel de tareas, incluidos el protocolo, los subdominios y el puerto. De lo contrario, hay complicaciones en la forma de llamar al método y procesar el mensaje. Para obtener más información, consulte Mensajería entre dominios al tiempo de ejecución del host.

De forma predeterminada, el cuadro de diálogo se abre en un nuevo control de vista web, no en un iframe. Esto garantiza que se pueda abrir la página de inicio de sesión de un proveedor de identidades. Como verá más adelante en este artículo, las características del cuadro de diálogo de Office tienen implicaciones en el uso de bibliotecas de autenticación o autorización, como Microsoft Authentication Library (MSAL) y Passport.

Nota:

Para configurar el cuadro de diálogo para que se abra en un iframe flotante, pase la displayInIframe: true opción en la llamada a displayDialogAsync. No haga esto al usar la API de cuadros de diálogo de Office para iniciar sesión.

Flujo de autenticación con el cuadro de diálogo de Office

A continuación se muestra un flujo de autenticación típico.

Diagrama que muestra la relación entre el panel de tareas y los procesos del explorador de diálogos.

  1. La primera página que se abre en el cuadro de diálogo es una página (u otro recurso) que se hospeda en el dominio del complemento; es decir, el mismo dominio que la ventana del panel de tareas. Esta página puede tener una interfaz de usuario que solo diga "Espere, le redirigiremos a la página donde puede iniciar sesión en NAME-OF-PROVIDER". El código de esta página construye la dirección URL de la página de inicio de sesión del proveedor de identidades con información que se pasa al cuadro de diálogo como se describe en Pasar información al cuadro de diálogo o se codifica de forma rígida en un archivo de configuración del complemento, como un archivo de web.config.
  2. Luego, la ventana de diálogo redirige a la página de inicio de sesión. La URL incluye un parámetro de consulta que indica al proveedor de identidades que debe redirigir la ventana de diálogo a una página específica después de que el usuario haya iniciado sesión. En este artículo llamaremos a esta página redirectPage.html. Los resultados del intento de inicio de sesión se pueden pasar al panel de tareas con una llamada de messageParent en esta página. Se recomienda que la página esté en el mismo dominio que la ventana del host.
  3. El servicio del proveedor de identidad procesa la solicitud GET entrante desde la ventana de diálogo. Si el usuario ya ha iniciado sesión, inmediatamente redirige la ventana a redirectPage.html e incluye los datos del usuario como un parámetro de consulta. Si el usuario aún no ha iniciado sesión, la página de inicio de sesión del proveedor aparece en la ventana y el usuario puede iniciar sesión. Para la mayoría de los proveedores, si el usuario no puede iniciar sesión correctamente, el proveedor muestra una página de error en la ventana de diálogo y no redirige a redirectPage.html. El usuario debe cerrar la ventana seleccionando X en la esquina. Si el usuario inicia sesión correctamente, la ventana de diálogo se redirige a redirectPage.html y los datos de usuario se incluyen como un parámetro de consulta.
  4. Cuando se abre la página redirectPage.html, llama a messageParent para informar del acceso correcto o incorrecto a la página del panel de tareas y, de forma opcional, también informa de los datos del usuario o de error. Otros mensajes posibles incluyen pasar un token de acceso o indicar al panel de tareas que el token está en almacenamiento.
  5. El evento DialogMessageReceived se inicia en la página del panel de tareas y su controlador cierra la ventana de diálogo y puede continuar el proceso del mensaje.

Compatibilidad con múltiples proveedores de identidades

Si el complemento proporciona al usuario una selección de proveedores, como una cuenta de Microsoft, Google o Facebook, necesita una primera página local (consulte la sección anterior) que proporcione una interfaz de usuario para que el usuario seleccione un proveedor. La selección activa la construcción de la URL de inicio de sesión y la redirige.

Autorización del complemento a un recurso externo

En la web moderna, los usuarios y las aplicaciones web son entidades de seguridad. La aplicación dispone de su propia identidad y permisos para un recurso en línea como Microsoft 365, Google Plus, Facebook o LinkedIn. La aplicación se registra con el proveedor de recursos antes de implementarla. El registro incluye:

  • Una lista de los permisos que necesita la aplicación.
  • Una dirección URL a la que el servicio de recursos debe devolver un token de acceso cuando la aplicación accede al servicio.

Cuando un usuario invoca una función en la aplicación que accede a los datos del usuario en el servicio de recursos, se le pide que inicie sesión en el servicio y que conceda a la aplicación los permisos necesarios para los recursos del usuario. El servicio entonces redirige la ventana de inicio de sesión a la URL previamente registrada y pasa el token de acceso. La aplicación utiliza el token de acceso para acceder a los recursos del usuario.

Puede usar la API de cuadros de diálogo de Office para gestionar este proceso utilizando un flujo similar al descrito para que los usuarios inicien sesión. Las únicas diferencias son:

  • Si el usuario no ha concedido previamente a la aplicación los permisos que necesita, se le pedirá que lo haga en el cuadro de diálogo después de iniciar sesión.
  • El código de la ventana de diálogo envía el token de acceso a la ventana host mediante messageParent para enviar el token de acceso stringified o almacenando el token de acceso donde la ventana host puede recuperarlo (y usando messageParent para indicar a la ventana host que el token está disponible). El token tiene un límite de tiempo, pero mientras dure, la ventana host puede usarlo para acceder directamente a los recursos del usuario sin necesidad de ninguna otra confirmación.

Algunos complementos de ejemplo de autenticación que usan la API de cuadros de diálogo de Office para este propósito se muestran en Ejemplos.

Uso de bibliotecas de autenticación con el cuadro de diálogo

Dado que el cuadro de diálogo de Office y el panel de tareas se ejecutan en diferentes instancias en tiempo de ejecución del explorador, debe usar bibliotecas de autenticación o autorización de forma diferente de cómo se usan cuando la autenticación y autorización tienen lugar en la misma ventana. En las secciones siguientes se describen las formas en que puede y no puede usar estas bibliotecas.

Normalmente no se puede usar la memoria caché interna de la biblioteca para almacenar tokens

Normalmente, las bibliotecas relacionadas con la autenticación ofrecen una caché en memoria para almacenar el token de acceso. Si se llevan a cabo llamadas sucesivas al proveedor de recursos (como Google, Microsoft Graph, Facebook, etc.), la biblioteca comprobará en primer lugar si el token en su caché ha caducado. Si no ha caducado, la biblioteca devolverá el token en caché, en lugar de realizar otro recorrido de ida y vuelta al STS para obtener un nuevo token. Pero este patrón no se puede usar en complementos de Office. Dado que el proceso de inicio de sesión se produce en la instancia del explorador del cuadro de diálogo de Office, la caché de tokens está en esa instancia.

Estrechamente vinculado a esto es el hecho de que una biblioteca, por lo general, proporciona métodos interactivos y "silenciosos" para obtener un token. Cuando se pueden realizar tanto la autenticación como las llamadas de datos al recurso en la misma instancia del explorador, el código llama al método silencioso para obtener un token justo antes de que el código agregue el token a la llamada de datos. El método silencioso comprueba si hay un token sin expirar en la memoria caché y, si lo hay, lo devuelve. De lo contrario, el método silencioso llama al método interactivo que redirige al inicio de sesión del STS. Una vez completado el inicio de sesión, el método interactivo devuelve el token, pero también lo almacena en caché en memoria caché. Pero cuando se usa la API de cuadros de diálogo de Office, las llamadas de datos al recurso, que llaman al método silencioso, están en la instancia del explorador del panel de tareas. La caché de tokens de la biblioteca no existe en esa instancia.

Como alternativa, la instancia del explorador de diálogos del complemento puede llamar directamente al método interactivo de la biblioteca. Cuando ese método devuelve un token, el código debe almacenar explícitamente el token en algún lugar donde la instancia del explorador del panel de tareas pueda recuperarlo, como el almacenamiento local o una base de datos del lado servidor.

Nota:

Los cambios en la seguridad del explorador afectarán a la estrategia de control de tokens.

  • Si el complemento se ejecuta en Office en la Web en el Microsoft Edge (versión anterior) (no Chromium) o en el explorador Safari, el cuadro de diálogo y el panel de tareas no comparten el mismo almacenamiento local, por lo que no se puede usar para comunicarse entre ellos.
  • A partir de la versión 115 de los exploradores basados en Chromium, como Chrome y Edge, se está probando la creación de particiones de almacenamiento para evitar el seguimiento entre sitios de canal lateral específico (consulte también las directivas del explorador Microsoft Edge). Esto significa que los datos almacenados por las API de almacenamiento, como el almacenamiento local, solo están disponibles para contextos con el mismo origen y el mismo sitio de nivel superior. Para solucionar este problema, en el explorador, vaya a chrome://flags o edge://flags y, a continuación, establezca la marca Creación de particiones de almacenamiento experimental de terceros (#third-entidad-almacenamiento-partición) en Deshabilitado. Siempre que sea posible, se recomienda pasar datos entre el cuadro de diálogo y el panel de tareas mediante los métodos messageParent y messageChild , como se describe en Uso de la API de diálogo de Office en los complementos de Office.

Otra opción es pasar el token al panel de tareas con el método messageParent. Esta alternativa solo es posible si el método interactivo almacena el token de acceso en un lugar en el que el código pueda leerlo. A veces, un método interactivo de la biblioteca está diseñado para almacenar el token en una propiedad privada de un objeto al que no se puede obtener acceso desde el código.

Normalmente no se puede usar el objeto "contexto de autenticación" de la biblioteca.

A menudo, una biblioteca relacionada con la autenticación tiene un método que obtiene un token de forma interactiva y también crea un objeto de "contexto de autenticación" que devuelve el método. El token es una propiedad del objeto (lo que es posible que sea privado y que no pueda obtener acceso directamente desde el código). Ese objeto tiene los métodos que obtienen los datos del recurso. Estos métodos incluyen el token en las solicitudes HTTP que realizan al proveedor de recursos (como Google, Microsoft Graph, Facebook, etc.).

Estos objetos de contexto de autenticación y los métodos que los crean no se pueden usar en complementos de Office. Dado que el inicio de sesión se produce en la instancia del explorador del cuadro de diálogo de Office, el objeto tendría que crearse allí. Pero las llamadas de datos al recurso están en la instancia del explorador del panel de tareas y no hay ninguna forma de recuperar el objeto de una instancia a otra. Por ejemplo, no se puede pasar el objeto con messageParent porque messageParent solo puede pasar valores de cadena. Un objeto de JavaScript con métodos no se puede convertir en cadena de forma segura.

Cómo puede usar las bibliotecas con la API de cuadros de diálogo de Office

Además de los objetos de "contexto de autenticación" monolíticos, o en lugar de ellos, la mayoría de las bibliotecas ofrece las API en un nivel de abstracción inferior que permite al código crear objetos de aplicación auxiliar menos monolíticos. Por ejemplo, MSAL.NET v. 3.x.x tiene una API para construir una dirección URL de inicio de sesión y otra API que construye un objeto AuthResult que contiene un token de acceso en una propiedad accesible para el código. Para ver ejemplos de MSAL.NET en un complemento de Office, vea: Complemento de Office de Microsoft Graph ASP.NET y Complemento de Outlook de Microsoft Graph ASP.NET. Para ver un ejemplo de cómo usar msal.js en un complemento, vea Complemento de Office de Microsoft Graph React.

Para obtener más información sobre las bibliotecas de autenticación y autorización, vea Microsoft Graph: bibliotecas recomendadas y Otros servicios externos: bibliotecas.

Ejemplos

Vea también