Extensión de la aplicación de pestaña con permisos y ámbitos de Microsoft Graph

Puede ampliar la aplicación de pestaña mediante Microsoft Graph para permitir permisos de usuario adicionales, como ver el perfil de usuario de la aplicación, leer correo y mucho más. La aplicación debe solicitar ámbitos de permiso específicos para obtener los tokens de acceso tras el consentimiento del usuario de la aplicación.

Los ámbitos de grafo, como User.Read o Mail.Read, indican a qué puede acceder la aplicación desde una cuenta de usuario de Teams. Debe especificar sus ámbitos en la solicitud de autorización. En este artículo se le guiará por los pasos para configurar los permisos y ámbitos de Microsoft Graph para la aplicación de pestaña de Teams.

Configuración de permisos de API en Microsoft Entra ID

Puede configurar ámbitos de Graph adicionales en Microsoft Entra ID para la aplicación. Estos son permisos delegados, que usan las aplicaciones que requieren acceso de inicio de sesión. Un usuario o administrador de la aplicación que ha iniciado sesión debe dar su consentimiento inicialmente. A partir de entonces, la aplicación de pestaña puede dar su consentimiento en nombre del usuario que ha iniciado sesión cuando llama a Microsoft Graph.

Se recomienda usar permisos delegados para el usuario que ha iniciado sesión. Si la aplicación no necesita un usuario que haya iniciado sesión, considere la posibilidad de usar permisos de aplicación, también conocidos como escenario de acceso de solo aplicación. Solo los administradores pueden conceder el consentimiento para los permisos de aplicación. Para obtener más información, consulte permisos de aplicación.

Para configurar los permisos de API

1. Abra la aplicación que registró en el Azure Portal.

2. Seleccione Administrar>permisos de API en el panel izquierdo.

   

   Aparece la página de permisos de API

3. Seleccione + Agregar un permiso para agregar permisos de Microsoft Graph API.

   

   Aparece la página Solicitar permisos de API.

4. Seleccione Microsoft Graph.

   

   Se muestran las opciones de permisos de gráfico.

5. Seleccione Permisos delegados o Permisos de aplicación para ver la lista de permisos delegados o de aplicación respectivamente.

   

6. Seleccione los permisos relevantes para la aplicación y, a continuación, seleccione Agregar permisos.

   

   También puede introducir el nombre del permiso en el cuadro de búsqueda para encontrarlo.

   Aparece un mensaje en el navegador que indica que los permisos se actualizaron.

   

   Los permisos agregados se muestran en la página depermisos de API.

   

   Ahora ha configurado la aplicación con permisos de Microsoft Graph.

Configurar la autenticación para distintas plataformas

En función de la plataforma o dispositivo en el que quiera dirigirse a la aplicación, es posible que se requiera una configuración adicional, como uri de redireccionamiento, configuración de autenticación específica o detalles específicos de la plataforma.

Nota:

• Si a la aplicación de pestaña no se le ha concedido el consentimiento del administrador de TI, los usuarios de la aplicación deben proporcionar su consentimiento la primera vez que usen la aplicación en otra plataforma.
• La concesión implícita no es necesaria si el inicio de sesión único (SSO) está habilitado en una aplicación de pestaña.

Puede configurar la autenticación para varias plataformas siempre que la dirección URL sea única.

Para configurar la autenticación para una plataforma

1. Abra la aplicación que registró en el Azure Portal.

2. Seleccione Administrarautenticación>en el panel izquierdo.

   

   Aparece la página Configuraciones de la plataforma.

3. Seleccione + Agregar una plataforma.

   

   Aparece la página Configurar plataformas.

4. Seleccione la plataforma que desea configurar para la aplicación de pestañas. Puede elegir el tipo de plataforma de la aplicación web o de página única.

   

   Puede configurar varias plataformas para un tipo de plataforma en particular. Asegúrese de que el URI de redireccionamiento es único para cada plataforma que configure.

   Aparece la página de Configuración de la web.

   Nota:

   Las configuraciones son diferentes en función de la plataforma que seleccione.

5. Introduzca los detalles de configuración de la plataforma.

   

   1. Introduzca el URI de redireccionamiento. El URI debe ser único.
   2. Introduzca la URL de cierre de sesión del canal frontal.
   3. Seleccione los tokens que desea que Microsoft Entra ID envíe para la aplicación.

6. Seleccione Configurar.

   La plataforma se configura y se muestra en la página Configuraciones de la plataforma.

Adquirir token de acceso para MS Graph

Debe adquirir un token de acceso para Microsoft Graph. Para ello, use Microsoft Entra flujo en nombre de (OBO).

La implementación actual del inicio de sesión único (SSO) se limita a los permisos de nivel de usuario, que no se pueden usar para realizar llamadas a Graph. Para obtener los permisos y ámbitos necesarios para realizar una llamada a Graph, las aplicaciones de SSO deben implementar un servicio web personalizado para intercambiar el token recibido de la biblioteca de JavaScript de Teams por un token que incluya los ámbitos necesarios. Puede usar la biblioteca de autenticación de Microsoft (MSAL) para obtener el token desde el lado del cliente.

Después de configurar los permisos de Graph en Microsoft Entra ID, tendrá que obtener el identificador de token del cliente de Teams y, a continuación, intercambiarlo con el token del lado servidor.

Obtención del identificador de token del cliente de Teams

A continuación se muestra un ejemplo para obtener el identificador de token del cliente de Teams:

microsoftTeams.authentication.getAuthToken().then((result) => {
    //result contains the id token
            console.log(result);
        })

Intercambio del identificador de token con el token del lado servidor

A continuación se muestra un ejemplo de flujo de OBO para capturar el token de acceso del cliente de Teams mediante MSAL:

C#

IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(<"Client id">)
                                                .WithClientSecret(<"Client secret">)
                                                .WithAuthority($"https://login.microsoftonline.com/<"Tenant id">")
                                                .Build();
            try
            {
                var idToken = <"Client side token">;
                UserAssertion assert = new UserAssertion(idToken);
                List<string> scopes = new List<string>();
                scopes.Add("https://graph.microsoft.com/User.Read");
                // Acquires an access token for this application (usually a Web API) from the authority configured in the application.
                var responseToken = await app.AcquireTokenOnBehalfOf(scopes, assert).ExecuteAsync();
                return responseToken.AccessToken.ToString();
            }
            catch (Exception ex)
            {
                return ex.Message;
            }
        }

Node.js

Clase ConfidentiaClientApplication Referencia del SDK | código de ejemplo

// Exchange client Id side token with server token
  app.post('/getProfileOnBehalfOf', function(req, res) {
        var tid = < "Tenant id" >
    var token = < "Client side token" >
    var scopes = ["https://graph.microsoft.com/User.Read"];

        // Creating MSAL client
        const msalClient = new msal.ConfidentialClientApplication({
            auth: {
                clientId: < "Client ID" >,
                clientSecret: < "Client Secret" >
      }
        });

        var oboPromise = new Promise((resolve, reject) => {
            msalClient.acquireTokenOnBehalfOf({
                authority: `https://login.microsoftonline.com/${tid}`,
                oboAssertion: token,
                scopes: scopes,
                skipCache: true
            }).then(result => {
                console.log("Token is: " + result.accessToken);
            }).catch(error => {
                reject({ "error": error.errorCode });
            });
        });

Si necesita acceder a los datos de Microsoft Graph, configure el código del lado del servidor para:

1. Validar el token de acceso. Para obtener más información, consulte Validar el token de acceso.
2. Inicie el flujo de OBO de OAuth 2.0 con una llamada a la plataforma de identidad de Microsoft que incluye el token de acceso, algunos metadatos sobre el usuario y las credenciales de la aplicación de pestaña (su identificador de aplicación y secreto de cliente). El Plataforma de identidad de Microsoft devuelve un nuevo token de acceso que se puede usar para acceder a Microsoft Graph.
3. Obtener datos de Microsoft Graph mediante el nuevo token.
4. Use la serialización de caché de tokens en MSAL.NET para almacenar en caché el nuevo token de acceso para varios, si es necesario.

Importante

• Como procedimiento recomendado para la seguridad, use siempre código del lado servidor para realizar llamadas de Microsoft Graph u otras llamadas que requieran pasar un token de acceso. Esto ayuda a proteger el token de ser interceptado o filtrado. NO devuelva el token de OBO al cliente porque, a continuación, permitiría al cliente realizar llamadas directas a Microsoft Graph.
• Dos aplicaciones independientes registradas en Microsoft Entra ID requerirán tokens individuales para cada aplicación. Use el flujo de OBO para habilitar la comunicación entre las aplicaciones.
• No use notifySuccess result para devolver la información del token a la página primaria. Use localStorage para guardar el token y pasar la clave de elemento a través de notifySuccess.

Obtener consentimiento

La aplicación puede obtener el consentimiento para los permisos de Graph globalmente del administrador de inquilinos, o individualmente por usuario.

Desde el administrador de inquilinos

Una forma sencilla de dar su consentimiento en nombre de una organización es obtener el consentimiento del administrador.

Del usuario

Al solicitar consentimiento adicional del usuario mediante la funcionalidad de autenticación de la biblioteca cliente JavaScript (TeamsJS) de Microsoft Teams, tenga en cuenta las siguientes consideraciones:

Para implementar la autenticación sso en una pestaña personal, siga estos pasos:

1. El token recuperado mediante getAuthToken() debe intercambiarse en el lado servidor mediante Microsoft Entra flujo de OBO para obtener acceso a esas otras API de Graph. Asegúrese de usar el punto de conexión Microsoft Entra v2 para este intercambio.

2. Al intentar ejecutar el intercambio de tokens para un usuario por primera vez, si Microsoft Entra se niega a intercambiar tokens, podría deberse a que el usuario no ha dado su consentimiento para conceder permiso de aplicación a los datos del usuario. En estos casos, el intercambio produce un invalid_grant error o interaction_required . Algunos ejemplos de errores de invalid_grant son cuando se requiere el consentimiento o se auth_code, aserción o que el token de actualización ha expirado, revocado, incorrecto o ausente. Algunos ejemplos de interaction_required incluyen cuándo se requiere la autenticación multifactor o la inscripción de dispositivos corporativos.

3. Si se produce un error en el intercambio debido a los invalid_grant errores o interaction_required , debe pedir consentimiento al usuario. Dado que la interacción del usuario solo puede producirse desde el cliente, el servidor debe devolver una indicación a la aplicación cliente de que se requiere consentimiento. A continuación, puede usar la interfaz de usuario (UI) para pedir al usuario de la aplicación que conceda otro consentimiento. La interfaz de usuario debe incluir un botón que desencadene un cuadro de diálogo de consentimiento de Microsoft Entra.

4. Para pedir al usuario su consentimiento para que la aplicación acceda a sus datos, debe incluir la propiedad en el prompt=consentparámetro query-string para Microsoft Entra ID.

   • En lugar de ?scope={scopes}, use ?prompt=consent&scope={scopes}
   • Asegúrese de que la {scopes} propiedad incluye todos los ámbitos que solicita al usuario. Por ejemplo, Mail.Read o User.Read.

   Para controlar el consentimiento incremental para la aplicación de pestaña, consulte consentimiento de usuario incremental y dinámico.

5. Una vez que el usuario de la aplicación haya concedido más permisos, vuelva a intentar el flujo de OBO para obtener acceso a las API de Graph adicionales. Para obtener más información, vea Código de ejemplo de autenticación de INICIO de sesión único de Teams Personal Tab .

Condición de carrera al realizar una llamada OBO después de una excepción de concesión no válida

Si un usuario no ha concedido Microsoft Entra consentimiento de la aplicación para estos ámbitos, se produce un error o interaction_required se produce un error en invalid_grant la llamada de OBO. Este error le informa de que debe solicitar al usuario su consentimiento.

Cuando el usuario ha proporcionado su consentimiento e intenta realizar una llamada OBO inmediatamente, a veces hay una condición de carrera entre Microsoft Entra ID propagar este consentimiento y la solicitud de OBO que tiene lugar. Esto puede provocar un error en la llamada de OBO con el mismo invalid_grant error o interaction_required .

Si la aplicación no es consciente de este comportamiento, es posible que pida al usuario su consentimiento varias veces. El procedimiento recomendado consiste en crear un mecanismo de espera y reintento significativo para evitar esta experiencia de usuario poco óptima.

El mecanismo de espera y reintento debe realizar un seguimiento si un usuario ha dado su consentimiento a los ámbitos necesarios. Si se produce un error en una llamada API que incluye una solicitud OBO con los errores anteriores, pero el usuario ya ha dado su consentimiento, evite mostrar la solicitud de consentimiento al usuario. En su lugar, espere algún tiempo antes de volver a intentar la llamada API. Normalmente, Microsoft Entra ID envía el consentimiento en un plazo de entre tres y cinco segundos. En una de nuestras aplicaciones de ejemplo, reintentamos hasta tres veces con el doble del tiempo de espera entre cada reintento, empezando por una espera de un segundo.

Si después de tres o cinco intentos el flujo de OBO sigue generando un error, es posible que el usuario no haya dado su consentimiento a todos los ámbitos necesarios y que tenga que pedirle que dé su consentimiento de nuevo.

Este enfoque ayuda a reducir la posibilidad de que se pida al usuario el consentimiento más de una vez.

Ejemplo de código

Ejemplo de nombre	Descripción	C#	Node.js
Pestañas Microsoft Entra inicio de sesión único	Aplicación de ejemplo de Microsoft Teams para pestañas Microsoft Entra sso, que usa el flujo de OBO para llamar a las API de Graph.	View	Ver

Consulte también

• Flujo OAuth 2.0 On-Behalf-Of
• Obtener acceso para MS Graph
• Serialización de caché de tokens en MSAL.NET
• Proveedor MSAL2 de Microsoft Teams