Estender aplicativo de guia com permissões e escopos do Microsoft Graph

Você pode estender seu aplicativo de guia usando o Microsoft Graph para permitir permissões de usuário adicionais, como exibir o perfil de usuário do aplicativo, ler emails e muito mais. Seu aplicativo deve solicitar escopos de permissão específicos para obter os tokens de acesso mediante o consentimento do usuário do aplicativo.

Escopos de gráfico, como User.Read ou Mail.Read, indicam o que seu aplicativo pode acessar de uma conta de usuário do Teams. É preciso especificar seus escopos na solicitação da autorização. Este artigo orienta você pelas etapas para configurar as permissões e os escopos do Microsoft Graph para seu aplicativo da guia Teams.

Configurar permissões de API no Microsoft Entra ID

Você pode configurar escopos do Graph adicionais no Microsoft Entra ID para seu aplicativo. Essas são permissões delegadas, usadas por aplicativos que exigem acesso conectado. Um usuário ou administrador de aplicativo conectado deve inicialmente consentir com eles. Depois disso, seu aplicativo de guia pode consentir em nome do usuário conectado quando chamar o Microsoft Graph.

Recomendamos o uso de permissões delegadas para o usuário conectado. Se o aplicativo não precisar de um usuário conectado, considere o uso de permissões de aplicativo, também conhecidas como cenário de acesso somente aplicativo. Somente os administradores podem conceder consentimento para permissões de aplicativo. Para obter mais informações, consulte permissões de aplicativo.

Para configurar as permissões da API

1. Abra o aplicativo que você registrou no portal do Azure.

2. Selecione Gerenciar>permissões de API no painel esquerdo.

   

   A página Permissões da AP é exibida.

3. Selecione + Adicionar uma permissão para adicionar permissões de API do Graph Microsoft.

   

   A página Solicitar permissões da API é exibida.

4. Selecione Microsoft Graph.

   

   As opções de permissões de Graph são exibidas.

5. Selecione Permissões delegadas ou Permissões de aplicativo para exibir a lista de permissões delegadas ou de aplicativo, respectivamente.

   

6. Selecione as permissões relevantes para seu aplicativo e, em seguida, selecione Adicionar permissões.

   

   Você também pode inserir o nome da permissão na caixa de pesquisa para encontrá-lo.

   Uma mensagem aparece no navegador informando que as permissões foram atualizadas.

   

   As permissões adicionadas são exibidas na página Permissões da API.

   

   Agora você configurou seu aplicativo com permissões do Microsoft Graph.

Configurar a autenticação para diferentes plataformas

Dependendo da plataforma ou do dispositivo para o qual você deseja direcionar seu aplicativo, configurações adicionais podem ser necessárias, como URIs de redirecionamento, configurações de autenticação específicas ou detalhes específicos da plataforma.

Você pode configurar a autenticação para várias plataformas, desde que o URL seja exclusivo.

Para configurar a autenticação para uma plataforma

1. Abra o aplicativo que você registrou no portal do Azure.

2. Selecione Gerenciar>Autenticação no painel esquerdo.

   

   A página Configurações da plataforma é exibida.

3. Selecione Adicionar uma plataforma.

   

   A página Configurar plataformas é exibida.

4. Selecione a plataforma que você deseja configurar para seu aplicativo de guia. Você pode escolher o tipo de plataforma entre aplicativo web ou de página única.

   

   Você pode configurar várias plataformas para um tipo específico de plataforma. Verifique se o URI de redirecionamento é exclusivo para cada plataforma configurada.

   A página Configurar Web é exibida.

   Observação

   As configurações são diferentes com base na plataforma selecionada.

5. Insira os detalhes da configuração para a plataforma.

   

   1. Insira o URI de redirecionamento. A URI deve ser exclusiva.
   2. Insira a URL de logoff do canal frontal.
   3. Selecione os tokens que você deseja que o Microsoft Entra ID envie para seu aplicativo.

6. Selecione Configurar.

   A plataforma é configurada e exibida na página Configurações da plataforma.

Adquira o token de acesso para o MS Graph

Você precisa adquirir um token de acesso para o Microsoft Graph. Você pode fazer isso usando o fluxo OBO (em nome de) do Microsoft Entra.

A implementação atual para logon único (SSO) é limitada a permissões no nível do usuário, que não são utilizáveis para fazer chamadas do Graph. Para obter as permissões e os escopos necessários para fazer uma chamada do Graph, os aplicativos SSO devem implementar um serviço Web personalizado para trocar o token recebido da biblioteca JavaScript do Teams por um token que inclua os escopos necessários. Você pode usar a Biblioteca de Autenticação da Microsoft (MSAL) para buscar o token do lado do cliente.

Depois de configurar as permissões do Graph no Microsoft Entra ID, você precisará obter a ID do token do cliente do Teams e trocá-la pelo token do lado do servidor.

Obter a ID do token do cliente do Teams

Veja a seguir um exemplo para obter a ID do token do cliente do Teams:

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

Trocar a ID do token pelo token do lado do servidor

Veja a seguir um exemplo de fluxo OBO para buscar o token de acesso do cliente do Teams usando MSAL:

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

// 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 });
            });
        });

Se você precisar acessar dados do Microsoft Graph, configure o código do lado do servidor para:

1. Valide o token de acesso. Para saber mais, confira Validar o token de acesso.
2. Inicie o fluxo de OBO do OAuth 2.0 com uma chamada para a plataforma de identidade da Microsoft que inclui o token de acesso, alguns metadados sobre o usuário e as credenciais do aplicativo de guia (sua ID de aplicativo e segredo do cliente). A plataforma de identidade da Microsoft retorna um novo token de acesso que pode ser usado para acessar o Microsoft Graph.
3. Obter os dados do Microsoft Graph usando o novo token.
4. Use a serialização de cache de token no MSAL.NET para armazenar em cache o novo token de acesso para vários, se necessário.

Obter consentimento

Você pode obter consentimento do aplicativo para permissões do Graph globalmente do administrador ou individualmente por usuário.

Do administrador

Uma maneira simples de consentir em nome de uma organização é obter o consentimento do administrador.

Do usuário

Ao solicitar consentimento adicional do usuário usando o recurso de autenticação TeamsJS (biblioteca de cliente JavaScript do Microsoft Teams), tenha em mente as seguintes considerações:

Para implementar a autenticação SSO em uma guia pessoal, siga estas etapas:

1. O token recuperado usando getAuthToken() deve ser trocado no lado do servidor usando o fluxo OBO do Microsoft Entra para obter acesso a essas outras APIs do Graph. Certifique-se de usar o ponto de extremidade do Microsoft Entra v2 para essa troca.

2. Quando você tenta executar a troca de token para um usuário pela primeira vez, se o Microsoft Entra se recusar a trocar tokens, pode ser porque o usuário não consentiu em dar permissão ao seu aplicativo para os dados do usuário. Nesses casos, a troca falha com o invalid_grant erro ou interaction_required . Exemplos de erros de invalid_grant incluem quando o consentimento é necessário ou auth_code, asserção ou o token de atualização expirou, foi revogado, malformado ou está ausente. Exemplos de interaction_required incluem quando a autenticação multifator ou o registro de dispositivo corporativo é necessário.

3. Se a troca falhar devido a invalid_grant erros ou interaction_required , você deverá solicitar o consentimento do usuário. Como a interação do usuário só pode acontecer a partir do cliente, o servidor precisa retornar uma indicação ao aplicativo cliente de que o consentimento é necessário. Em seguida, você pode usar a interface do usuário (UI) para solicitar que o usuário do aplicativo conceda outro consentimento. A interface do usuário deve incluir um botão que acione uma caixa de diálogo de consentimento do Microsoft Entra.

4. Para pedir consentimento ao usuário para que seu aplicativo acesse os dados, você deve incluir a propriedade em seu query-string-parameter para o prompt=consent Microsoft Entra ID.

   • Em vez de ?scope={scopes}, use ?prompt=consent&scope={scopes}
   • Verifique se a {scopes} propriedade inclui todos os escopos que você está solicitando ao usuário. Por exemplo: Mail.Read ou User.Read.

   Para lidar com o consentimento incremental para o aplicativo de guia, consulte consentimento incremental e dinâmico do usuário.

5. Depois que o usuário do aplicativo tiver concedido mais permissões, repita o fluxo OBO para obter acesso a APIs do Graph adicionais. Para obter mais informações, consulte o código de exemplo de autenticação SSO da guia pessoal do Teams .

Condição de corrida ao fazer uma chamada OBO após exceção de concessão inválida

Se um usuário não tiver concedido consentimento ao aplicativo Microsoft Entra para esses escopos, sua chamada OBO falhará com invalid_grant ou interaction_required erro. Este erro informa que você precisa solicitar o consentimento do usuário.

Quando o usuário forneceu seu consentimento e você tenta fazer uma chamada OBO imediatamente, às vezes há uma condição de corrida entre o Microsoft Entra ID propagando esse consentimento e a solicitação OBO ocorrendo. Isso pode levar a uma falha de chamada OBO com o mesmo invalid_grant ou interaction_required erros.

Se o aplicativo não estiver ciente desse comportamento, ele poderá solicitar o consentimento do usuário várias vezes. A prática recomendada é criar um mecanismo significativo de espera e repetição para evitar essa experiência de usuário abaixo do ideal.

O mecanismo de espera e repetição deve acompanhar se um usuário consentiu com os escopos necessários. Se uma chamada de API que inclui uma solicitação OBO falhar com os erros acima, mas o usuário já tiver consentido, evite mostrar a solicitação de consentimento ao usuário. Em vez disso, aguarde algum tempo antes de repetir a chamada à API. Normalmente, o Microsoft Entra ID envia o consentimento dentro de três a cinco segundos. Em um de nossos aplicativos de exemplo, tentamos novamente até três vezes com o dobro do tempo de espera entre cada tentativa, começando com uma espera de um segundo.

Se, após três a cinco tentativas, o fluxo OBO ainda falhar, talvez o usuário não tenha consentido com todos os escopos necessários e talvez seja necessário solicitar que ele dê consentimento novamente.

Essa abordagem ajuda a reduzir a possibilidade de o usuário ser solicitado a dar consentimento mais de uma vez.

Exemplo de código

Confira também

• Fluxo em Nome do OAuth 2.0
• Obter acesso para o MS Graph
• Serialização de cache de token no MSAL.NET
• Provedor MSAL2 do Microsoft Teams