Habilitar el inicio de sesión único (SSO) en un complemento de Office

  • Artículo

Los usuarios inician sesión en Office con su cuenta microsoft personal o su cuenta de trabajo o Microsoft 365 Educación. Aproveche esto y utilice el inicio de sesión único (SSO) para autenticar y autorizar al usuario para su complemento sin que tenga que iniciar sesión por segunda vez.

Una magen que muestra el proceso de inicio de sesión de un complemento

Cómo funciona el SSO en tiempo de ejecución

En el siguiente diagrama se muestra cómo funciona el proceso de SSO. Los elementos azules representan Office o la plataforma de identidad de Microsoft. Los elementos grises representan el código que escribe e incluyen el código del lado del cliente (panel de tareas) y el código del lado del servidor para su complemento.

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

  1. En el complemento, su código JavaScript llama a la API de Office.js getAccessToken. Si el usuario ya ha iniciado sesión en Office, el host de Office devolverá el token de acceso con las notificaciones del usuario que ha iniciado sesión.
  2. Si el usuario no ha iniciado sesión, la aplicación del host de Office abre un cuadro de diálogo para que el usuario inicie sesión. Office redirige a la plataforma de identidad de Microsoft para llevar a cabo el proceso de inicio de sesión.
  3. Si es la primera vez que el usuario actual ha usado su complemento, se le pide que dé su consentimiento.
  4. La Office host solicita el token de acceso de la plataforma de identidad de Microsoft para el usuario actual.
  5. La plataforma de identidad de Microsoft devuelve el token de acceso a Office. Office almacenará en caché el token en su nombre para que las llamadas futuras a getAccessToken simplemente devuelvan el token almacenado en caché.
  6. La aplicación host de Office devuelve el token de acceso al complemento como parte del objeto devuelto por lagetAccessToken llamada.
  7. El token es tanto un token de acceso como un token de identidad. Puede usarlo como un token de identidad para analizar y examinar notificaciones sobre el usuario, como el nombre del usuario y la dirección de correo electrónico.
  8. Opcionalmente, el complemento puede usar el token como un token de acceso para realizar solicitudes HTTPS autenticadas a las API en el lado del servidor. Dado que el token de acceso contiene notificaciones de identidad, el servidor puede almacenar información asociada con la identidad del usuario; por ejemplo, sus preferencias.

Procedimientos recomendados y requisitos

No almacenar en caché el token de acceso

Nunca almacene en caché el token de acceso en el código del lado del cliente. Llame siempre a getAccessToken cuando necesite un token de acceso. Office almacenará en caché el token de acceso (o solicitará uno nuevo si ha caducado). Esto ayudará a evitar que se filtre accidentalmente el token desde su complemento.

Habilitar la autenticación moderna para Outlook

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.

Implementar un sistema de autenticación de reserva

No debe depender del SSO como único método de autenticación del complemento. Implemente un sistema de autenticación diferente al que el complemento pueda recurrir en algunas situaciones de error. Por ejemplo, si el complemento se carga en una versión anterior de Office que no admite SSO,getAccessToken se producirá un error en la llamada.

Para los complementos de Excel, Word y PowerPoint, normalmente querrá recurrir a la plataforma de identidad de Microsoft. Para obtener más información, vea Autenticación con la plataforma de identidad de Microsoft.

En el caso de los complementos de Outlook, se recomienda un sistema de respaldo. Para obtener más información, vea Escenario: implementar el inicio de sesión único a un servicio en un complemento de Outlook.

También puede utilizar un sistema de tablas y autenticación de usuarios, o puede aprovechar uno de los proveedores de inicio de sesión social. Para obtener más información sobre cómo hacer esto con un complemento de Office, consulte Autorizar servicios externos en el complemento de Office.

Para ver ejemplos de código que utilizan la plataforma de identidad de Microsoft como sistema de reserva, vea Office Add-in NodeJS SSO y Office Add-in ASP.NET SSO.

Desarrollar un complemento de SSO

En esta sección se describe las tareas implicadas en la creación de un complemento de Office que usa SSO. Estas tareas se describen aquí independientemente del lenguaje o el marco. Para obtener instrucciones paso a paso, vea:

Registre su complemento con la plataforma de identidad de Microsoft

Para trabajar con SSO es necesario registrar el complemento en la plataforma de identidad de Microsoft. Esto permitirá que la plataforma de identidad de Microsoft proporcione servicios de autenticación y autorización para su complemento La creación del registro de la aplicación incluye las siguientes tareas.

  • Obtenga un identificador de aplicación (cliente) para identificar su complemento en la plataforma de identidad de Microsoft.
  • Genere un secreto de cliente que actúe como contraseña para su complemento cuando solicite un token.
  • Especifique los permisos que necesita el complemento. Siempre son necesarios los permisos "profile" y "openid" de Microsoft Graph Es posible que necesite permisos adicionales en función de lo que tenga que hacer el complemento.
  • Conceda la confianza de las aplicaciones de Office para el complemento.
  • Autorizar previamente las aplicaciones de Office para el complemento con el ámbito predeterminado access_as_user.

Para obtener más información acerca de este proceso, consulte Registrar un complemento de Office que usa SSO con la plataforma de identidad de Microsoft.

Configurar el complemento

Agregue un nuevo marcado al manifiesto del complemento.

  • <WebApplicationInfo> : elemento primario de los siguientes elementos.
  • <Id>. : el identificador de aplicación (cliente) que recibió al registrar el complemento con el Plataforma de identidad de Microsoft. Para obtener más información, consulte Registrar un complemento de Office que usa SSO con la plataforma de identidad de Microsoft.
  • <Recurso> : el URI del complemento. Este es el mismo URI (incluido elapi: protocolo) que usó al registrar el complemento con la plataforma de identidad de Microsoft. La parte del dominio de este URI debe coincidir con el dominio, incluidos los subdominios, que se usan en las direcciones URL de la <sección Recursos> del manifiesto del complemento y el URI debe terminar con el identificador de cliente especificado en el <elemento Id> .
  • <Ámbitos> : elemento primario de uno o varios <elementos Scope> .
  • <Ámbito> : especifica un permiso que necesita el complemento. Los permisos profile y openID siempre son necesarios y es posible que sean los únicos. Si el complemento necesita acceso a Microsoft Graph u otros recursos de Microsoft 365, necesitará elementos Scope> adicionales<. Por ejemplo, para los permisos de Microsoft Graph puede solicitar los ámbitos User.Read yMail.Read. Las bibliotecas que usa en su c?digo para acceder a Microsoft Graph pueden necesitar permisos adicionales. Para obtener más información, vea Autorizar a Microsoft Graph desde un complemento de Office.

Para complementos de Word, Excel y PowerPoint, agregue el marcado al final de la sección<VersionOverrides ... xsi:type="VersionOverridesV1_0">. Para complementos de Outlook, agregue el marcado al final de la sección <VersionOverrides ... xsi:type="VersionOverridesV1_1">.

A continuación verá un ejemplo de la revisión.

<WebApplicationInfo>
    <Id>5661fed9-f33d-4e95-b6cf-624a34a2f51d</Id>
    <Resource>api://addin.contoso.com/5661fed9-f33d-4e95-b6cf-624a34a2f51d</Resource>
    <Scopes>
        <Scope>openid</Scope>
        <Scope>user.read</Scope>
        <Scope>files.read</Scope>
        <Scope>profile</Scope>
    </Scopes>
</WebApplicationInfo>

Importante

Si uno o varios administradores implementan el complemento en sus organizaciones, la adición de nuevos ámbitos al manifiesto requerirá que el administrador dé su consentimiento a las actualizaciones. Los usuarios se bloquearán desde el complemento hasta que se conceda el consentimiento.

Nota:

Si no sigue los requisitos de formato del manifiesto para SSO, el complemento se rechazará desde AppSource hasta que cumpla con el formato requerido.

Incluir el conjunto de requisitos de la API de identidad

Para utilizar SSO, el complemento requiere el conjunto de requisitos de la API de identidad 1.3. Para obtener más información, consulte IdentityAPI.

Agregar código del lado cliente

Agregue JavaScript al complemento para:

  • Llame a getAccessToken.
  • Analice el token de acceso o páselo al código del lado del servidor del complemento.

El código siguiente muestra un ejemplo sencillo de getAccessToken llamar y analizar el token para el nombre de usuario y otras credenciales.

Nota:

Este ejemplo solamente maneja un tipo de error expl?citamente. Para ver ejemplos de manejo de errores más elaborados, consulte Complemento de Office SSO de NodeJS y Complemento de Office SSO de ASP.NET.

async function getUserData() {
    try {
        let userTokenEncoded = await OfficeRuntime.auth.getAccessToken();
        let userToken = jwt_decode(userTokenEncoded); // Using the https://www.npmjs.com/package/jwt-decode library.
        console.log(userToken.name); // user name
        console.log(userToken.preferred_username); // email
        console.log(userToken.oid); // user id     
    }
    catch (exception) {
        if (exception.code === 13003) {
            // SSO is not supported for domain user accounts, only
            // Microsoft 365 Education or work account, or a Microsoft account.
        } else {
            // Handle error
        }
    }
}

Cuándo llamar a getAccessToken

Si el complemento requiere un usuario que haya iniciado sesión, debe llamar desde getAccessToken dentro de Office.initialize. También debe pasar allowSignInPrompt: true el parámetro options de getAccessToken. Por ejemplo; OfficeRuntime.auth.getAccessToken( { allowSignInPrompt: true }); esto garantizará que, si el usuario aún no ha iniciado sesión, Office solicite al usuario a través de la interfaz de usuario que inicie sesión ahora.

Si el complemento tiene alguna funcionalidad que no requiere que un usuario haya iniciado sesión, puede llamar a cuando el usuario realice una acción que requiera que un usuario haya iniciado sesión.getAccessToken No hay una degradación significativa del rendimiento con llamadas redundantes de getAccessToken porque Office almacena en caché el token de acceso y lo reutilizará, hasta que expire, sin realizar otra llamada a la plataforma de identidad de MicrosoftgetAccessToken cuando se llame. Por lo que puede agregar llamadas de getAccessToken a todas las funciones y controladores que inician una acción en la que se requiere el token.

Importante

Como práctica de seguridad recomendada, llama siempre getAccessToken cuando necesite un token de acceso. Office almacenará en caché. No almacene ni guarde el token de acceso con su propio código.

Pasar el token de acceso al código del lado servidor

Si necesita tener acceso a Api web en el servidor o servicios adicionales como Microsoft Graph, deberá pasar el token de acceso al código del lado servidor. El token de acceso proporciona acceso (para el usuario autenticado) a las API web. También el código del lado servidor puede analizar el token para obtener información de identidad si lo necesita. (Consulte a continuación Usar el token de acceso como un token de identidad). Hay muchas bibliotecas disponibles para diferentes idiomas y plataformas que pueden ayudar a simplificar el código que escribe. Para obtener más información, consulte Overview of the Microsoft Authentication Library (MSAL).

Si necesita obtener acceso a Microsoft Graph, el código del lado servidor debe hacer lo siguiente:

  • Valide el token de acceso (vea validar el token de acceso a continuación).
  • Inicie el flujo en nombre de OAuth 2.0 con una llamada a la 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). La plataforma de identidad de Microsoft devolverá un nuevo token de acceso que se puede usar para obtener acceso a Microsoft Graph.
  • Obtener datos de Microsoft Graph mediante el nuevo token.
  • Si necesita almacenar en caché el nuevo token de acceso para varias llamadas, se recomienda usar la serialización de caché de tokens en MSAL.NET.

Importante

Como procedimiento recomendado de seguridad, use siempre el código del lado servidor para realizar llamadas de Microsoft Graph, u otras llamadas que requieran pasar un token de acceso. Nunca devuelva el token OBO al cliente para permitir que el cliente realice llamadas directas a Microsoft Graph. Esto ayuda a proteger el token de ser interceptado o filtrado. Para obtener más información sobre el flujo de protocolo adecuado, consulte el diagrama de protocolo de OAuth 2.0

El código siguiente muestra un ejemplo de pasar el token de acceso al lado del servidor. El token se pasa en un encabezado Authorization al enviar una solicitud a una API web del lado servidor. En este ejemplo se envían datos JSON, POST por lo que se usa el método, pero GET es suficiente para enviar el token de acceso cuando no se escribe en el servidor.

$.ajax({
    type: "POST",
    url: "/api/DoSomething",
    headers: {
        "Authorization": "Bearer " + accessToken
    },
    data: { /* some JSON payload */ },
    contentType: "application/json; charset=utf-8"
}).done(function (data) {
    // Handle success
}).fail(function (error) {
    // Handle error
}).always(function () {
    // Cleanup
});

Para obtener m?s informaci?n sobre c?mo obtener acceso autorizado a los datos de Microsoft Graph del usuario, consulte Autorizar a Microsoft Graph en su complemento de Office.

Validar el token de acceso

Las API web del servidor deben validar el token de acceso si se envía desde el cliente. El token es un JSON Web Token (JWT), lo que significa que la validación funciona igual que la validación des tokens en la mayoría de los flujos de OAuth normales. Hay muchas bibliotecas disponibles que pueden encargarse de la validación JWT, pero los conceptos básicos son:

  • Comprobar que el token es correcto
  • Comprobar que la autoridad prevista emitió el token
  • Comprobar que el token se destina a la API Web

Tenga en cuenta las siguientes instrucciones para validar el token.

  • Los tokens SSO válidos será emitidos por la autoridad de Azure, https://login.microsoftonline.com. La notificación iss en el token debería empezar por este valor.
  • El parámetro del token aud se establecerá en el identificador de aplicación del registro de la aplicación de Azure del complemento.
  • El parámetro scp del token se establece en access_as_user.

Para obtener más información sobre la validación de tokens, consulte la plataforma de identidad de Microsoft tokens de acceso.

Usar el token de acceso como token de identidad

Si el complemento necesita comprobar la identidad del usuario, el token de acceso devuelto de getAccessToken() contiene información que se puede usar para establecer la identidad. Las siguientes solicitudes del token se refieren a la identidad.

  • name: el nombre para mostrar del usuario
  • preferred_username: la dirección de correo del usuario.
  • oid - Un GUID que representa el identificador del usuario en el sistema de identidad de Microsoft.
  • tid - Un GUID que representa el inquilino en el que el usuario está iniciando sesión.

Para obtener más información sobre estas y otras notificaciones, consulte Tokens de identificador de la plataforma de identidad de Microsoft. Si necesita crear un identificador único para representar al usuario en el sistema, consulte Uso de notificaciones para identificar de forma fiable a un usuario para obtener más información.

Ejemplo de token de acceso

La siguiente es una carga ?til decodificada t?pica de un token de acceso. Para obtener información acerca de las propiedades, consulte tokens de acceso de la plataforma de identidad de Microsoft tokens de acceso.

{
    aud: "2c3caa80-93f9-425e-8b85-0745f50c0d24",
    iss: "https://login.microsoftonline.com/fec4f964-8bc9-4fac-b972-1c1da35adbcd/v2.0",
    iat: 1521143967,
    nbf: 1521143967,
    exp: 1521147867,
    aio: "ATQAy/8GAAAA0agfnU4DTJUlEqGLisMtBk5q6z+6DB+sgiRjB/Ni73q83y0B86yBHU/WFJnlMQJ8",
    azp: "e4590ed6-62b3-5102-beff-bad2292ab01c",
    azpacr: "0",
    e_exp: 262800,
    name: "Mila Nikolova",
    oid: "6467882c-fdfd-4354-a1ed-4e13f064be25",
    preferred_username: "milan@contoso.com",
    scp: "access_as_user",
    sub: "XkjgWjdmaZ-_xDmhgN1BMP2vL2YOfeVxfPT_o8GRWaw",
    tid: "fec4f964-8bc9-4fac-b972-1c1da35adbcd",
    uti: "MICAQyhrH02ov54bCtIDAA",
    ver: "2.0"
}

Uso de SSO con un complemento de Outlook

Existen algunas diferencias pequeñas pero importantes en cuanto al uso de SSO y el complemento de Outlook al usarlo en un complemento de Excel, PowerPoint o Word. Aseg?rese de leer Autenticar a un usuario con un token de inicio de sesi?n ?nico en un complemento de Outlook y Escenario: Implementar el inicio de sesi?n ?nico en su servicio en un complemento de Outlook.

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:

Recursos adicionales