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

Los usuarios inician sesión en Office con su cuenta microsoft personal o su cuenta profesional o de Microsoft 365 Education. 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.

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.

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:

• Crear un complemento de Node.js Office que usa el inicio de sesión único
• Crear un complemento de ASP.NET Office que usa el inicio de sesión único

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

El manifiesto debe proporcionar a Office cierta información sobre cómo se registra el complemento en el identificador de Microsoft Entra. La configuración depende del tipo de manifiesto que use el complemento.

"webApplicationInfo": {
	"id": "a661fed9-f33d-4e95-b6cf-624a34a2f51d",
	"resource": "api://addin.contoso.com/a661fed9-f33d-4e95-b6cf-624a34a2f51d"
},

<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>

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.

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.

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.

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.

Compatibilidad con cookies de terceros de Google Chrome

Google Chrome está trabajando para dar a los usuarios un mayor control de su experiencia de navegación. Los usuarios podrán bloquear cookies de terceros en su navegador Chrome. Esto impedirá que su complemento use dichas cookies. Esto puede provocar problemas cuando el complemento autentica al usuario, como varias solicitudes o errores de inicio de sesión.

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 Una nueva ruta de acceso para el espacio aislado de privacidad en la web.

Recursos adicionales

• Documentación de la Plataforma de identidad de Microsoft
• Conjuntos de requisitos
• IdentityAPI