Escenario: Implementar el inicio de sesión único a su servicio en un complemento de Outlook

  • Artículo

En este artículo veremos un método recomendado del uso conjunto del token de acceso de inicio de sesión único y el token de identidad de Exchange para proporcionar la implementación de un inicio de sesión único en a su propio servicio back-end. Al usar ambos tokens juntos, puede aprovechar las ventajas del token de acceso SSO cuando está disponible, a la vez que se asegura de que el complemento de funcionarán cuando no es así, como cuando el usuario cambia a un cliente que no sea compatible o si el buzón del usuario se encuentra en un servidor de Exchange local.

Nota:

La API de inicio de sesión único es actualmente compatible con Word, Excel, PowerPoint y Outlook. Para más información sobre dónde se admite en este momento la API de inicio de sesión único, vea Conjuntos de requisitos de la API de identidad. Si está trabajando con un complemento 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.

¿Por qué usar el token de acceso SSO?

El token de identidad de Exchange está disponible en todos los conjuntos de requisitos de los complementos API, por lo que puede resultar tentador dependen de este token e ignorar el token SSO por completo. Sin embargo, el token SSO ofrece algunas ventajas sobre el token de identidad de Exchange lo hace que sea el método recomendado cuando está disponible.

  • El token SSO utiliza un formato OpenID estándar y es emitido por Azure. Esto simplifica en gran medida el proceso de validación de estos tokens. En comparación, los tokens de identidad de Exchange utilizan un formato personalizado basado en el estándar JSON Web Token, lo que requiere una tarea personalizada para validar el token.
  • El back-end puede usar el token SSO para recuperar un token de acceso de Microsoft Graph sin que el usuario tenga que realizar ninguna acción de inicio de sesión adicional.
  • El token SSO proporciona información de identidad más avanzada, como el nombre para mostrar del usuario.

Escenario del complemento

Para este ejemplo, considere que el complemento se compone de la interfaz de usuario, de scripts (HTML + JavaScript) y de una API web de back-end a la cual el complemento realiza la llamada. La API web de back-end realiza llamadas a la API de Microsoft Graph y a la API de datos de Contoso, una API ficticia creada por terceros. Al igual que la API de Microsoft Graph, la API de datos de Contoso requiere autenticación de OAuth. El requisito es que la API web de back-end debería poder realizar llamadas a las API sin tener que solicitar al usuario sus credenciales cada vez que un token de acceso expire.

Para hacer esto, la API de back-end crea una base de datos segura de los usuarios. Cada usuario cuenta con una entrada en la base de datos donde el back-end puede almacenar tokens de actualización de larga duración para la API de datos de Contoso y la API de Microsoft Graph. La siguiente marca JSON representa una entrada del usuario en la base de datos.

{
  "userDisplayName": "...",
  "ssoId": "...",
  "exchangeId": "...",
  "graphRefreshToken": "...",
  "contosoRefreshToken": "..."
}

El complemento incluye el token de acceso SSO (si está disponible) o el token de identidad de Exchange (si no está disponible el token SSO) con cada llamada que realiza a la API web de back-end.

Inicio del complemento

  1. Cuando se inicia el complemento, envía una solicitud a la API web del back-end para determinar si el usuario está registrado (es decir, si tiene un registro asociado en la base de datos de usuarios) y que la API tiene tokens actualizados para Graph y Contoso. En esta llamada, el complemento incluye tanto el token SSO (si está disponible) y el token de identidad.

  2. La API Web utiliza los métodos de Autenticar a un usuario con un token de inicio de sesión único en un complemento de Outlook y Autenticar a un usuario con un token de identidad para Exchange para validar y generar un único identificador de ambos tokens.

  3. Si se proporciona un token SSO, la API Web consulta la base de datos de usuarios para encontrar una entrada que tenga un valor ssoId que coincida con el identificador único generado a partir del token de SSO.

    • Si no existe una entrada, continúe con el paso siguiente.
    • Si existe una entrada, vaya al paso 5.

  4. La API Web consulta la base de datos para encontrar una entrada que tenga un valor exchangeId que coincida con el identificador único generado a partir del token de identidad de Exchange.

    • Si existe una entrada y se proporciona un token de SSO, actualice el registro del usuario en la base de datos para establecer el valor ssoId para el identificador único generado a partir del token de SSO y vaya al paso 5.
    • Si existe una entrada y no se proporcionó ningún token SSO, vaya al paso 5.
    • Si no existe, cree una nueva entrada. Establezca ssoId para el identificador único generado a partir del token SSO (si está disponible) y exchangeId para el identificador único generado a partir del token de identidad de Exchange.

  5. Busque un token de actualización válido en el valor graphRefreshToken del usuario.

    • Si el valor falta o no es válido, y se proporciona un token de SSO, use OAuth2 en nombre de flujo para obtener un token de acceso y actualizar el token de Graph. Guarde el token de actualización en el valor graphRefreshToken para el usuario.

  6. Busque los tokens de actualización válidos tanto en graphRefreshToken como en contosoRefreshToken.

    • Si los dos valores son válidos, responda al complemento para indicar que el usuario ya está registrado y configurado.
    • Si algún válido no es válido, responda al complemento para indicar que la configuración de ese usuario es necesaria, además de los servicios (Graph o Contoso) que deben configurarse.

  7. El complemento comprueba la respuesta.

    • Si el usuario ya está registrado y configurado, el complemento continúa un funcionamiento normal.
    • Si se requiere la configuración de usuario, el complemento entra en modo de "configuración" y se le pedirá autorización para el complemento.

Autorizar la API web de back-end

Lo ideal es que el procedimiento para autorizar la API web de back-end para que llame a la API de Microsoft Graph y la API de datos de Contoso solo debería tener que pasar una vez, para minimizar tener que preguntar al usuario que inicie sesión.

Según la respuesta de la API web del back-end, el complemento podría necesitar autorizar al usuario para la API de Microsoft Graph, la API de datos de Contoso o ambas. Como las API usa autenticación OAuth2, el método es similar para ambas.

  1. El complemento notifica al usuario que necesita autorizar el uso de la API y le pide que haga clic en un vínculo o un botón para iniciar el proceso.

  2. Cuando se complete el flujo, el complemento envía el token de actualización a la API web del back-end e incluye el token SSO (si está disponible) o el token de identidad de Exchange.

  3. La API web del back-end encuentra al usuario en la base de datos y actualiza el token de actualización correspondiente.

  4. El complemento continúa con un funcionamiento normal.

Funcionamiento normal

Cuando el complemento realiza una llamada a la API web del back-end, incluye el token SSO o el token de identidad de Exchange. la API web del back-end localiza al usuario con este token y, después, usa los tokens de actualización almacenados para obtener los tokens de acceso para la API Graph de Microsoft y la API de datos de Contoso. Siempre y cuando los tokens de actualización sean válidos, el usuario no tendrá que iniciar sesión de nuevo.