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

Artigo
02/02/2024

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

Escopos de grafo, 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ê nas etapas para configurar permissões e escopos do Microsoft Graph para seu aplicativo de guias do Teams.

Configurar permissões de API no Microsoft Entra ID

Você pode configurar escopos adicionais do Graph em 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 ele chama o Microsoft Graph.

Recomendamos usar permissões delegadas para o usuário conectado. Se seu aplicativo não precisar de um usuário conectado, considere o uso de permissões de aplicativo, também conhecido como o 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

Abra o aplicativo que você registrou no portal do Azure.
Selecione Gerenciar>permissões de API no painel esquerdo.

A página Permissões da AP é exibida.
Selecione + Adicionar uma permissão para adicionar permissões do Microsoft API do Graph.

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

As opções de permissões de Graph são exibidas.
Selecione Permissões delegadas ou permissões de aplicativo para exibir a lista de permissões delegadas ou de aplicativo, respectivamente.
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 dispositivo em que você deseja direcionar seu aplicativo, a configuração adicional pode exigir, como URIs de redirecionamento, configurações de autenticação específicas ou detalhes específicos da plataforma.

Observação

Se o aplicativo de guia não tiver recebido o consentimento do administrador de TI, os usuários do aplicativo precisarão fornecer consentimento na primeira vez que usarem seu aplicativo em uma plataforma diferente.
A concessão implícita não será necessária se o SSO (logon único) estiver habilitado em um aplicativo de guia.

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

Para configurar a autenticação para uma plataforma

Abra o aplicativo que você registrou no portal do Azure.
Selecione Gerenciar>Autenticação no painel esquerdo.

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

A página Configurar plataformas é exibida.
Selecione a plataforma que você deseja configurar para seu aplicativo de guia. Você pode escolher o tipo de plataforma na Web ou aplicativo 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.
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 Microsoft Entra ID enviar para seu aplicativo.
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 Microsoft Entra fluxo OBO (em nome de).

A implementação atual do SSO (logon único) é limitada a permissões no nível do usuário, que não podem ser usadas para fazer chamadas do Graph. Para obter as permissões e 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, em seguida, trocá-la com o 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 com o token do lado do servidor

A seguir está um exemplo de fluxo OBO para buscar o token de acesso do cliente do Teams usando o MSAL:

C#
Node.js

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

Classe ConfidentiaClientApplication Referência do SDK | código de exemplo

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

Valide o token de acesso. Para saber mais, confira Validar o token de acesso.
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). O plataforma de identidade da Microsoft retorna um novo token de acesso que pode ser usado para acessar o Microsoft Graph.
Obter os dados do Microsoft Graph usando o novo token.
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.

Importante

Como uma prática recomendada para segurança, sempre use o código do lado do servidor para fazer chamadas do Microsoft Graph ou outras chamadas que exigem a passagem de um token de acesso. Isso ajuda a proteger o token de ser interceptado ou vazado. NÃO retorne o token OBO ao cliente porque ele habilitaria o cliente a fazer chamadas diretas para o Microsoft Graph.
Dois aplicativos separados registrados em Microsoft Entra ID exigirão tokens individuais para cada aplicativo. Use o fluxo OBO para habilitar a comunicação entre os aplicativos.
Não use notifySuccess o resultado para retornar as informações do token para a página pai. Use localStorage para salvar o token e passar a chave do item por meio de notifySuccess.

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

Do administrador do locatário

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

Do usuário

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

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

O token recuperado usando getAuthToken() deve ser trocado no lado do servidor usando Microsoft Entra fluxo OBO para obter acesso a essas outras APIs do Graph. Verifique se você usa o ponto de extremidade Microsoft Entra v2 para essa troca.
Quando você tenta executar a troca de tokens para um usuário pela primeira vez, se Microsoft Entra se recusar a trocar tokens, pode ser porque o usuário não consentiu em dar permissão ao 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, declaração ou o token de atualização está expirado, revogado, malformado ou ausente. Exemplos de interaction_required incluem quando a autenticação multifator ou o registro de dispositivo corporativo é necessário.
Se a troca falhar por causa dos invalid_grant erros ou interaction_required , você deverá solicitar o consentimento do usuário. Como a interação do usuário só pode acontecer do cliente, seu 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 (interface do usuário) para solicitar ao usuário do aplicativo que conceda outro consentimento. A interface do usuário deve incluir um botão que dispara uma caixa de diálogo de consentimento Microsoft Entra.
Para pedir consentimento ao usuário para que seu aplicativo acesse seus dados, você deve incluir a prompt=consent propriedade em seu parâmetro de cadeia de caracteres de consulta para 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 do aplicativo de guias, consulte consentimento incremental e dinâmico do usuário.
Depois que o usuário do aplicativo tiver concedido mais permissões, tente novamente o fluxo OBO para obter acesso a APIs adicionais do Graph. Para obter mais informações, consulte 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 Microsoft Entra consentimento do aplicativo para esses escopos, sua chamada OBO falhará com invalid_grant ou interaction_required erro. Esse 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 Microsoft Entra ID propagar esse consentimento e a solicitação OBO que está ocorrendo. Isso pode levar à falha na chamada OBO com os mesmos invalid_grant erros ou interaction_required .

Se seu aplicativo não tiver conhecimento desse comportamento, ele poderá pedir consentimento ao usuário várias vezes. A melhor prática é criar um mecanismo significativo de espera e repetição para evitar essa experiência de usuário suboptimal.

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 o prompt de consentimento para o usuário. Em vez disso, aguarde algum tempo antes de repetir a chamada de API. Normalmente, 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 repetição, começando em uma espera de um segundo.

Se depois de três a cinco tentativas o fluxo OBO ainda falhar, o usuário pode não ter consentido com todos os escopos necessários e talvez você precise solicitar que eles consentam novamente.

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

Exemplo de código

Nome de exemplo	Descrição	C#	Node.js
Tabs Microsoft Entra SSO	Aplicativo de exemplo do Microsoft Teams para guias Microsoft Entra SSO, que usa o fluxo OBO para chamar APIs do Graph.	View	Exibir

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

Configurar permissões de API no Microsoft Entra ID

Para configurar as permissões da API

Configurar a autenticação para diferentes plataformas

Para configurar a autenticação para uma plataforma

Adquira o token de acesso para o MS Graph

Obter a ID do token do cliente do Teams

Trocar a ID do token com o token do lado do servidor

Do administrador do locatário

Do usuário

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

Exemplo de código

Confira também

Comentários

Recursos adicionais

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

Configurar permissões de API no Microsoft Entra ID

Para configurar as permissões da API

Configurar a autenticação para diferentes plataformas

Para configurar a autenticação para uma plataforma

Adquira o token de acesso para o MS Graph

Obter a ID do token do cliente do Teams

Trocar a ID do token com o token do lado do servidor

Obter consentimento

Do administrador do locatário

Do usuário

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

Exemplo de código

Confira também

Comentários

Recursos adicionais