Agregar código para habilitar el inicio de sesión único

  • Artículo

Antes de agregar código para habilitar el inicio de sesión único, asegúrese de que ha registrado la aplicación con Microsoft Entra ID.

Registrarse con Microsoft Entra ID

Debe configurar el código del lado cliente de la aplicación de pestaña para obtener un token de acceso de Microsoft Entra ID. El token de acceso se emite en nombre de la aplicación de pestaña. Si la aplicación de pestaña requiere permisos adicionales de Microsoft Graph, deberá pasar el token de acceso al lado servidor e intercambiarlo por el token de Microsoft Graph.

configurar código para controlar el token de acceso

En esta sección se describen estos temas:

Agregar código del lado cliente

Para obtener acceso a la aplicación para el usuario de la aplicación actual, el código del lado cliente debe realizar una llamada a Teams para obtener un token de acceso. Debe actualizar el código del lado cliente para usar getAuthToken() para iniciar el proceso de validación.


Más información sobre getAuthToken()

getAuthToken() es un método de la biblioteca JavaScript de Microsoft Teams. Solicita que se emita un token de acceso de Microsoft Entra en nombre de la aplicación. El token se puede adquirir de la memoria caché, si no ha expirado. Si ha expirado, se envía una solicitud a Microsoft Entra ID para obtener un nuevo token de acceso.

Para más información, vea getAuthToken.

Cuándo llamar a getAuthToken

Use getAuthToken() en el momento en que necesite un token de acceso para el usuario de la aplicación actual:

Si se necesita un token de acceso... Llame a getAuthToken()...
Cuando el usuario de la aplicación accede a la aplicación Después de microsoftTeams.app.initialize().
Para usar una funcionalidad determinada de la aplicación Cuando el usuario de la aplicación realiza una acción que requiere el inicio de sesión.

Agregar código para getAuthToken

Agregue un fragmento de código JavaScript a la aplicación de pestaña a:

  • Llamar a getAuthToken().
  • Analice el token de acceso o páselo al código del lado del servidor.

El fragmento de código siguiente muestra un ejemplo de llamada getAuthToken().

microsoftTeams.app.initialize().then(() => {
    getClientSideToken()
        .then((clientSideToken) => {
            return getServerSideToken(clientSideToken);
        })
        .then((profile) => {
            return useServerSideToken(profile);
        })
        .catch((error) => {
            ...
        })
}

    function getClientSideToken() {

        return new Promise((resolve, reject) => {
            display("1. Get auth token from Microsoft Teams");
            
            microsoftTeams.authentication.getAuthToken().then((result) => {
                display(result);

                resolve(result);
            }).catch((error) => {
                reject("Error getting token: " + error);
            });
        });
    }

Por lo que puede agregar llamadas de getAuthToken() a todas las funciones y controladores que inician una acción en la que se requiere el token.


Este es un ejemplo del código del lado cliente:

Configuración del código de cliente

Cuando Teams recibe el token de acceso, se almacena en caché y se reutiliza según sea necesario. Este token se puede usar siempre que getAuthToken() se llame a , hasta que expire, sin realizar otra llamada a Microsoft Entra ID.

Importante

Como procedimiento recomendado para la seguridad del token de acceso:

  • Llame siempre a getAuthToken() cuando necesite un token de acceso.
  • Teams almacenará en caché el token de acceso. No almacene en caché ni la almacene en el código de la aplicación.

Cuando se llama getAuthToken() y se requiere el consentimiento del usuario de la aplicación para los permisos de nivel de usuario, se muestra un cuadro de diálogo de Microsoft Entra al usuario de la aplicación que ha iniciado sesión actualmente.

Símbolo del cuadro de diálogo de inicio de sesión único de pestaña

El cuadro de diálogo de consentimiento que aparece es para los ámbitos de id. abierto definidos en Microsoft Entra ID. El usuario de la aplicación solo debe dar su consentimiento una vez. Después de dar su consentimiento, el usuario de la aplicación puede acceder y usar la aplicación de pestaña para los permisos y ámbitos concedidos.

Importante

Escenarios en los que no se necesitan cuadros de diálogo de consentimiento:

  • Si el administrador de inquilinos ha concedido el consentimiento en nombre del inquilino, no es necesario solicitar consentimiento a los usuarios de la aplicación. Esto significa que los usuarios de la aplicación no ven los cuadros de diálogo de consentimiento y pueden acceder a la aplicación sin problemas.
  • Si la aplicación de Microsoft Entra está registrada en el mismo inquilino desde el que solicita una autenticación en Teams, no se puede pedir al usuario de la aplicación que dé su consentimiento y se le conceda un token de acceso de inmediato. Los usuarios de la aplicación dan su consentimiento a estos permisos solo si la aplicación de Microsoft Entra está registrada en un inquilino diferente.

Si encuentra algún error, consulte Solución de problemas de autenticación de SSO en Teams.

Usar el token de acceso como token de identidad

El token devuelto a la aplicación de pestaña es un token de acceso y un token de identificador. La aplicación de pestaña puede usar el token como un token de acceso para realizar solicitudes HTTPS autenticadas a las API en el lado del servidor.

El token de acceso devuelto desde getAuthToken() se puede usar para establecer la identidad del usuario de la aplicación mediante las siguientes notificaciones en el token:

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

Teams puede almacenar en caché esta información asociada a la identidad del usuario de la aplicación, como las preferencias del usuario.

Nota:

Si necesita crear un identificador único para representar al usuario de la aplicación en el sistema, consulte Uso de notificaciones para identificar de forma fiable a un usuario.

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

Si necesita tener acceso a las API web en el servidor, deberá pasar el token de acceso al código del lado servidor. Las API web deben descodificar el token de acceso para ver las notificaciones de ese token.

Nota:

Si no recibe el nombre principal de usuario (UPN) en el token de acceso devuelto, agréguelo como una notificación opcional en Microsoft Entra ID. Para obtener más información, consulte tokens de acceso.

El token de acceso recibido en la devolución de llamada correcta de getAuthToken() proporciona acceso (para el usuario de aplicación 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.

Si necesita pasar el token de acceso para obtener datos de Microsoft Graph, consulte Extensión de la aplicación de pestaña con permisos de Microsoft Graph.

Código para pasar el token de acceso al lado servidor

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, por lo que se usa el método POST. GET es suficiente para enviar el token de acceso cuando no escribe en el servidor.

function getServerSideToken(clientSideToken) {
        return new Promise((resolve, reject) => {
            microsoftTeams.app.getContext().then((context) => {
                fetch('/getProfileOnBehalfOf', {
                    method: 'post',
                    headers: {
                        'Content-Type': 'application/json'
                    },
                    body: JSON.stringify({
                        'tid': context.user.tenant.id,
                        'token': clientSideToken
                    }),
                    mode: 'cors',
                    cache: 'default'
                })
                .then((response) => {
                    if (response.ok) {
                        return response.json();
                    } else {
                        reject(response.error);
                    }
                })
                .then((responseJson) => {
                    if (responseJson.error) {
                        reject(responseJson.error);
                    } else {
                        const profile = responseJson;

                        resolve(profile);
                    }
                });
            });
        });
    }

Validar el token de acceso

Para obtener más información sobre cómo validar el token de acceso, consulte Validación de tokens.

Ejemplo de token de acceso

La siguiente es una carga ?til decodificada t?pica de un token 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"
}

Ejemplos de código

Ejemplo de nombre Descripción .NET Node.js Manifiesto
Inicio de sesión único de pestaña Aplicación de ejemplo de Microsoft Teams para pestañas Microsoft Entra sso View Ver,
Kit de herramientas de Teams		 ND
Inicio de sesión único (SSO) de pestaña, bot y extensión de mensajes (ME) En este ejemplo se muestra SSO para pestaña, Bot y ME: búsqueda, acción, linkunfurl. View View View

Paso siguiente

Actualización del manifiesto de aplicación de Teams y vista previa de aplicación

Recursos adicionales