Autorizar a Microsoft Graph con SSO

  • Artículo

Los usuarios inician sesión en Office con su cuenta microsoft personal o su cuenta de trabajo o Microsoft 365 Educación. La mejor manera de que un complemento de Office obtenga acceso autorizado a Microsoft Graph es usar las credenciales del inicio de sesión de Office del usuario. Esto les permite acceder a sus datos de Microsoft Graph sin necesidad de iniciar sesión una segunda vez.

Arquitectura de complementos para SSO y Microsoft Graph

Además de hospedar las páginas y JavaScript de la aplicación web, el complemento también debe hospedar, en el mismo nombre de dominio completo, una o más API web que obtendrán un token de acceso a Microsoft Graph y le realizan solicitudes.

El manifiesto del complemento contiene un <elemento WebApplicationInfo> que proporciona información importante de registro de aplicaciones de Azure a Office, incluidos los permisos para Microsoft Graph que requiere el complemento.

Cómo funciona en tiempo de ejecución

En el diagrama siguiente se muestran los pasos necesarios para iniciar sesión y acceder a Microsoft Graph. Todo el proceso usa tokens de acceso de OAuth 2.0 y JWT.

Diagrama que muestra el proceso de inicio de sesión único.

  1. El código del lado cliente del complemento llama a la API de Office.js getAccessToken. Esto indica al host de Office que obtenga un token de acceso para el complemento.

    Si el usuario no ha iniciado sesión, el host de Office junto con el Plataforma de identidad de Microsoft proporciona la interfaz de usuario para que el usuario inicie sesión y dé su consentimiento.

  2. El host de Office solicita un token de acceso del Plataforma de identidad de Microsoft.

  3. El Plataforma de identidad de Microsoft devuelve el token de acceso A al host de Office. El token de acceso A solo proporciona acceso a las propias API del lado servidor del complemento. No proporciona acceso a Microsoft Graph.

  4. El host de Office devuelve el token de acceso A al código del lado cliente del complemento. Ahora el código del lado cliente puede realizar llamadas autenticadas a las API del lado servidor.

  5. El código del lado cliente realiza una solicitud HTTP a una API web en el lado servidor que requiere autenticación. Incluye el token de acceso A como prueba de autorización. El código del lado servidor valida el token de acceso A.

  6. El código del lado servidor usa el flujo en nombre de OAuth 2.0 (OBO) para solicitar un nuevo token de acceso con permisos a Microsoft Graph.

  7. El Plataforma de identidad de Microsoft devuelve el nuevo token de acceso B con permisos para Microsoft Graph (y un token de actualización, si el complemento solicita offline_access permiso). Opcionalmente, el servidor puede almacenar en caché el token de acceso B.

  8. El código del lado servidor realiza una solicitud a una Graph API de Microsoft e incluye el token de acceso B con permisos para Microsoft Graph.

  9. Microsoft Graph devuelve los datos al código del lado servidor.

  10. El código del lado servidor devuelve los datos al código del lado cliente.

En las solicitudes posteriores, el código de cliente siempre pasará el token de acceso A al realizar llamadas autenticadas al código del lado servidor. El código del lado servidor puede almacenar en caché el token B para que no sea necesario volver a solicitarlo en futuras llamadas API.

Desarrollar un complemento de inicio de sesi?n ?nico (SSO) que tenga acceso a Microsoft Graph

Desarrolla un complemento que accede a Microsoft Graph igual que cualquier otra aplicación que use sso. Para obtener una descripción detallada, vea Habilitar el inicio de sesión único para complementos de Office. La diferencia es que es obligatorio que el complemento tenga una API web del lado servidor.

En función del lenguaje y el marco, es posible que haya bibliotecas disponibles que simplifiquen el código del lado servidor que tiene que escribir. El código debe hacer lo siguiente:

  • Valide el token de acceso A cada vez que se pasa desde el código del lado cliente. Para obtener más información, consulte Validar el token de acceso.
  • Inicie el flujo en nombre de OAuth 2.0 (OBO) con una llamada al Plataforma de identidad de Microsoft que incluya el token de acceso, algunos metadatos sobre el usuario y las credenciales del complemento (su identificador y secreto). Para obtener más información sobre el flujo de OBO, vea Plataforma de identidad de Microsoft y flujo en nombre de OAuth 2.0.
  • Opcionalmente, una vez completado el flujo, almacene en caché el token de acceso devuelto B con permisos para Microsoft Graph. Es probable que desee hacer esto si el complemento realiza más de una llamada a Microsoft Graph. Para obtener más información, consulte Adquisición y almacenamiento en caché de tokens mediante la Biblioteca de autenticación de Microsoft (MSAL)
  • Cree uno o varios métodos de API web que obtengan datos de Microsoft Graph pasando el token de acceso B (posiblemente almacenado en caché) a Microsoft Graph.

Para obtener ejemplos de tutoriales y escenarios detallados, vea:

Distribución de complementos habilitados para SSO en Microsoft AppSource

Cuando un administrador de Microsoft 365 adquiere un complemento de AppSource, el administrador puede redistribuirlo a través de Aplicaciones integradas y conceder el consentimiento del administrador al complemento para acceder a los ámbitos de Microsoft Graph. Sin embargo, también es posible que el usuario final adquiera el complemento directamente desde AppSource, en cuyo caso el usuario debe conceder su consentimiento al complemento. Esto puede crear un posible problema de rendimiento para el que hemos proporcionado una solución.

Si el código pasa la allowConsentPrompt opción en la llamada de getAccessToken, como OfficeRuntime.auth.getAccessToken( { allowConsentPrompt: true } );, Office puede solicitar al usuario su consentimiento si el Plataforma de identidad de Microsoft informa a Office de que el consentimiento aún no se ha concedido al complemento. Sin embargo, por motivos de seguridad, Office solo puede pedir al usuario que dé su consentimiento al ámbito de Microsoft Graph profile . Office no puede solicitar el consentimiento a otros ámbitos de Microsoft Graph, ni siquiera User.Read. Esto significa que si el usuario concede el consentimiento en el símbolo del sistema, Office devuelve un token de acceso. Pero el intento de intercambiar el token de acceso por un nuevo token de acceso con ámbitos adicionales de Microsoft Graph produce un error AADSTS65001, lo que significa que no se ha concedido el consentimiento (a los ámbitos de Microsoft Graph).

Nota:

La solicitud de consentimiento con { allowConsentPrompt: true } todavía podría producir un error incluso para el profile ámbito si el administrador ha desactivado el consentimiento del usuario final. Para más información, consulte Configuración del consentimiento de los usuarios finales a las aplicaciones mediante Azure Active Directory.

El código puede y debe controlar este error volviendo a un sistema alternativo de autenticación, que solicita al usuario su consentimiento a los ámbitos de Microsoft Graph. Para ver ejemplos de código, vea Crear un complemento de Office de Node.js que usa el inicio de sesión único y Crear un complemento de Office ASP.NET que use el inicio de sesión único y los ejemplos a los que vinculan. Todo el proceso requiere varios recorridos de ida y vuelta al Plataforma de identidad de Microsoft. Para evitar esta penalización de rendimiento, incluya la forMSGraphAccess opción en la llamada de getAccessToken; por ejemplo, OfficeRuntime.auth.getAccessToken( { forMSGraphAccess: true } ). Esto indica a Office que el complemento necesita ámbitos de Microsoft Graph. Office pedirá al Plataforma de identidad de Microsoft que compruebe que ya se ha concedido el consentimiento a los ámbitos de Microsoft Graph al complemento. Si es así, se devuelve el token de acceso. Si no lo ha hecho, la llamada de getAccessToken devuelve el error 13012. El código puede controlar este error si vuelve a un sistema alternativo de autenticación inmediatamente, sin realizar un intento irrecuperable de intercambiar tokens con el Plataforma de identidad de Microsoft.

Como procedimiento recomendado, pase forMSGraphAccess siempre a getAccessToken cuando el complemento se distribuya en AppSource y necesite ámbitos de Microsoft Graph.

Detalles sobre el inicio de sesión único con un complemento de Outlook

Si desarrolla un complemento de Outlook que usa el inicio de sesión único y lo transfiere de forma local para las pruebas, Office siempre devolverá el error 13012 cuando forMSGraphAccess se pase a getAccessToken incluso si se ha concedido el consentimiento del administrador. Por este motivo, debe comentar la forMSGraphAccess opción al desarrollar un complemento de Outlook. Asegúrese de quitar la marca de comentario de la opción al implementar para producción. El falso 13012 solo se produce cuando se realiza la transferencia local en Outlook.

En el caso de los complementos de Outlook, asegúrese de habilitar la autenticación moderna para el inquilino de Microsoft 365. Para obtener información sobre cómo hacerlo, vea Habilitar o deshabilitar la autenticación moderna para Outlook en Exchange Online.

Google Chrome está eliminando las cookies de terceros en 2024 e introduciendo una característica denominada Prevención de seguimiento. Si la prevención de seguimiento está habilitada en el explorador Chrome, el complemento no podrá usar cookies de terceros. El complemento puede encontrar problemas al autenticar al usuario, como varias solicitudes de inicio de sesión o errores.

Para obtener experiencias de autenticación mejoradas, consulte Uso del estado del dispositivo para obtener una experiencia de INICIO de sesión único mejorada en exploradores con cookies de terceros bloqueadas.

Para obtener más información sobre el lanzamiento de Google Chrome, consulte los siguientes recursos:

Consulte también