Implementación del inicio de sesión único (SSO) para complementos de Office

  • 11 minutos

El inicio de sesión único (SSO) ofrece una forma sencilla para que el complemento autentique a los usuarios. Con este método, el complemento puede autenticar al usuario para recuperar información de identidad o para obtenerla de otro punto de conexión protegido como Microsoft Graph. Para ello, el complemento debe llamar a una API web del lado del servidor registrada con Azure AD.

En esta unidad, aprenderá cómo funciona la autenticación con complementos de Office y cómo usar el inicio de sesión único para los complementos de Office.

Información general sobre autenticación y autorización en los complementos de Office

Las aplicaciones web y, por ende, los complementos de Office permiten de forma predeterminada el acceso anónimo. Pero, si quiere, puede exigir que los usuarios se autentiquen con un inicio de sesión. Por ejemplo, puede requerir que los usuarios inicien sesión con una cuenta de Microsoft, una cuenta de Microsoft 365 Education, una cuenta de trabajo u otra cuenta común. Esta tarea se denomina autenticación de usuario porque indica al complemento quién es el usuario.

El complemento también puede obtener el consentimiento del usuario para acceder a los datos de Microsoft Graph (como el perfil de Microsoft 365, los archivos de OneDrive y los datos de SharePoint) o a otros datos de orígenes externos como Google, Facebook, LinkedIn, SalesForce y GitHub. Esta tarea se denomina autorización de complemento (o de aplicación), porque se autoriza al complemento, no al usuario.

Puede elegir entre dos maneras para lograr la autenticación y la autorización.

  • Inicio de sesión único (SSO) de Office: sistema que permite que el inicio de sesión del usuario en Office también funcione como inicio de sesión en el complemento. De forma opcional, el complemento también puede usar las credenciales de Office del usuario para autorizar el complemento a Microsoft Graph.
  • Autenticación y autorización de aplicaciones web con Azure Active Directory (Azure AD): esta es la forma en que los complementos de Office (y otras aplicaciones web) autenticaban a los usuarios y las aplicaciones autorizadas antes de que hubiera un sistema de SSO de Office y se siguen usando en escenarios en los que el inicio de sesión único de Office no puede ser. Además, hay escenarios en los que desea que los usuarios inicien sesión en su complemento por separado, incluso cuando el inicio de sesión único está disponible; por ejemplo, si quiere que tengan la opción de iniciar sesión en el complemento con un identificador diferente del que utiliza en una sesión iniciada actualmente en Office.

Inicio de sesión único (SSO) en Complementos de Office

Microsoft agregó compatibilidad con el inicio de sesión único a Office en 2020. Esta funcionalidad reduce la frecuencia con la que se solicita a un usuario que inicie sesión en servicios de terceros.

La compatibilidad con el inicio de sesión único de Office se implementa en combinación con código en los complementos personalizados, compatibilidad con el inicio de sesión único en el SDK de JavaScript en tiempo de ejecución de Office y Azure AD. Para admitir el inicio de sesión único, un complemento de Office debe tener el correspondiente registro de aplicación de Azure AD. Este registro de aplicación define qué permisos el complemento admite y usa con las aplicaciones cliente de Office para que actúen en nombre del usuario.

Con esta compatibilidad con el inicio de sesión único, las aplicaciones pueden solicitar información de perfil del usuario o información de Microsoft Graph.

Los usuarios pueden otorgar su consentimiento a los complementos de Office para permitir que la aplicación obtenga su información de perfil. Después, la aplicación puede usar esta información de perfil proporcionada por Azure AD y Office como id. del usuario que ha iniciado sesión actualmente.

Los administradores pueden otorgar su consentimiento para toda una organización a través de un proceso de implementación centralizado, por lo que cada usuario no tiene que pasar individualmente por el proceso de consentimiento.

El inicio de sesión único de Office admite los dos tipos de cuentas compatibles con Microsoft: cuentas profesionales y educativas (cuentas de Azure AD) y cuentas de Microsoft (MSA).

El inicio de sesión único de los complementos de Office es compatible con los clientes web de Office y los siguientes clientes de escritorio:

  • Windows v16.0.12215.20006 (o posterior)
  • macOS v16.32.19102902 (o posterior)

Descripción del flujo de autenticación del inicio de sesión único

Echemos un vistazo a cómo funciona el proceso de inicio de sesión único en tiempo de ejecución.

Diagrama de información general del flujo de proceso en tiempo de ejecución de SSO.

  1. En el complemento, JavaScript llama a la nueva API de Office.js getAccessToken(). Esto indica a la aplicación cliente de Office que obtenga un token de acceso al complemento.
  2. Si el usuario no ha iniciado sesión, la aplicación cliente de Office abre una ventana emergente para que el usuario inicie sesión.
  3. Se pide al usuario que dé su consentimiento si es la primera vez que el usuario actual usa el complemento.
  4. La aplicación cliente de Office solicita el token de complemento del punto de conexión de Azure AD v2.0 para el usuario actual.
  5. Azure AD envía el token de complemento a la aplicación cliente de Office.
  6. La aplicación cliente de Office envía el token de complemento al complemento como parte del objeto de resultado que devuelve la llamada a getAccessToken().
  7. JavaScript en el complemento puede analizar el token y extraer la información que necesita.
  8. Opcionalmente, el complemento puede enviar solicitudes HTTP a su servidor para obtener más información sobre el usuario; como las preferencias del usuario. Alternativamente, el propio token de acceso podría enviarse al lado del servidor para su análisis y validación allí.

Implementación del inicio de sesión único en complementos de Office

Para que una aplicación de Microsoft Teams admita el inicio de sesión único, debe hacer lo siguiente:

  1. Registrar una aplicación de Azure AD
  2. Asociar un complemento de Office a la aplicación de Azure AD
  3. Implementar un código del lado cliente para obtener un token de acceso del cliente de Office de hospedaje

Echemos un vistazo a cada uno de estos valores:

Registrar una aplicación de Azure AD

El primer paso es registrar una aplicación de Azure AD para el complemento.

Las aplicaciones de Azure AD usadas para admitir el inicio de sesión único en los complementos de Office tienen muchos requisitos. Por ejemplo, deben ser aplicaciones multiinquilino, exponer el permiso access_as_user y también confiar en todas las aplicaciones cliente de Office que llaman a la aplicación.

Las herramientas de desarrollo proporcionadas por Microsoft incluyen la utilidad configure-sso que registrará la aplicación de Azure AD con todas las opciones necesarias durante el proceso de desarrollo.

Otra unidad de este módulo profundizará en cómo crear una nueva aplicación de Azure AD para que la use un complemento de Office que implemente el inicio de sesión único.

Asociar el complemento de Office a la aplicación de Azure AD

Una vez creada la aplicación de Azure AD, debe asociarse al complemento de Office. Esto se hace en el archivo de manifest.xml del complemento en la sección <WebApplicationInfo>:

<WebApplicationInfo>
  <Id>056b1e8c-747d-4b45-94b1-f61ac2c19a5e</Id>
  <Resource>api://localhost:3000/056b1e8c-747d-4b45-94b1-f61ac2c19a5e</Resource>
  <Scopes>
    <Scope>User.Read</Scope>
    <Scope>profile</Scope>
    <Scope>openid</Scope>
  </Scopes>
</WebApplicationInfo>

Hay dos partes de esta sección que deben actualizarse para la aplicación:

  • Identificador: este es el identificador de cliente de la aplicación de Azure AD registrada
  • Recurso: esta es la dirección URL del complemento, que es lo mismo que el URI que se usó al registrar el complemento en Azure AD. La parte del dominio del URI debe coincidir con el dominio donde se usa en cualquiera de las direcciones URL de la sección <Resources> del archivo manifest.xml del complemento.
  • Ámbitos: estos son los permisos o ámbitos que el complemento necesita de Azure AD.

Importante

El complemento siempre necesita los permisos de OpenID profile y openid. Estos pueden ser los únicos permisos necesarios, a menos que el complemento necesite llamar a otro servicio, como Microsoft Graph.

Además, algunas bibliotecas que usa el complemento pueden requerir permisos adicionales. Por ejemplo, MSAL.NET requiere el permiso offline_access.

Agregar código del lado cliente

Por último, un complemento debe implementar código del lado cliente para implementar y admitir el inicio de sesión único. Si usa las herramientas proporcionadas por Microsoft, el proyecto de complemento incluirá la mayor parte del código reutilizable para admitir el inicio de sesión único. Esto es así si usa el Office Developer Tools de Visual Studio 2019 para un complemento de ASP.NET o el generador de Yeoman de para Microsoft Office para VS Code de un complemento basado en Node.js.

El complemento usa el método de API [OfficeRuntime.Auth.getAccessToken()](/javascript/api/office-runtime/officeruntime.auth) para solicitar un token de acceso al cliente de Office de hospedaje.

El cliente de Office solicitará un token de acceso de Azure AD mediante la aplicación previamente registrada con Azure AD.

El token devuelto por Azure AD se puede usar para identificar al usuario, pero también se puede usar como token de arranque para obtener un token de acceso que se puede usar para enviar solicitudes a Microsoft Graph (suponiendo que el complemento y el usuario tengan permisos de Microsoft Graph específicos).

Usar el token de acceso para identificar al usuario

Es posible que el complemento necesite identificar al usuario. En este caso, el complemento normalmente proporciona este token a su propio sistema back-end que usa el token para almacenar las preferencias del usuario u otra información específica del usuario que ha iniciado sesión actualmente.

En este escenario, el token devuelto incluye algunas propiedades que pueden ser útiles para la aplicación:

  • name: este es el nombre para mostrar del usuario
  • preferred_username: este es el UPN del usuario o la dirección de correo electrónico
  • oid: este es el identificador de objeto único del usuario. Debe usarse para identificar al usuario en el sistema back-end como el nombre de y el usuario o un administrador pueden cambiar las propiedades de preferred_username.
  • tid: este es el identificador único del espacio empresarial al que pertenece el usuario

Uso del token de acceso en su propia API

Si usa el token de acceso en su propia API, debe implementar los procedimientos recomendados aceptados al reenviar el token recibido de Office. Esto incluye validar el token para asegurarse de que lo creó Azure AD, es de la autoridad esperada, el complemento es la audiencia prevista del token, el token no ha expirado y el ámbito se establece en access_as_user.

Usar el token de acceso para acceder a Microsoft Graph.

En el escenario en el que el complemento necesita acceder a Microsoft Graph, el código puede usar este token proporcionado por Office a la aplicación para iniciar el flujo de OAuth2 On-Behalf-Of (OBO). Cuando el token se usa de esta manera, se conoce como "token de arranque" porque solo se utiliza para obtener un token de acceso que se puede usar para llamar a Microsoft Graph.