Expandir a aplicação de separador com permissões e âmbitos do Microsoft Graph

Pode expandir a sua aplicação de separador através do Microsoft Graph para permitir permissões de utilizador adicionais, tais como ver o perfil de utilizador da aplicação, ler e-mails e muito mais. A sua aplicação tem de pedir âmbitos de permissão específicos para obter os tokens de acesso após o consentimento do utilizador da aplicação.

Os âmbitos de gráficos, como User.Read ou Mail.Read, indicam o que a sua aplicação pode aceder a partir de uma conta de utilizador do Teams. É preciso especificar seus escopos na solicitação da autorização. Este artigo explica-lhe os passos para configurar permissões e âmbitos do Microsoft Graph para a sua aplicação de separador Teams.

Configurar permissões de API no Microsoft Entra ID

Pode configurar âmbitos adicionais do Graph no ID do Microsoft Entra para a sua aplicação. Essas são permissões delegadas, usadas por aplicativos que exigem acesso conectado. Inicialmente, um utilizador ou administrador da aplicação com sessão iniciada tem de dar-lhes consentimento. A partir daí, a sua aplicação de separador pode consentir em nome do utilizador com sessão iniciada quando chama o Microsoft Graph.

Recomendamos a utilização de permissões delegadas para o utilizador com sessão iniciada. Se a sua aplicação não precisar de um utilizador com sessão iniciada, considere utilizar permissões de aplicação, também conhecidas como o cenário de acesso apenas à aplicação. Apenas os administradores podem conceder consentimento para permissões de aplicação. Para obter mais informações, veja permissões de aplicação.

Para configurar as permissões da API

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

2. Selecione Gerir>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 da Microsoft Graph API.

   

   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 aplicação para ver a lista de permissões delegadas ou de aplicação, respetivamente.

   

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.

   

   Configurou agora a sua aplicação com permissões do Microsoft Graph.

Configurar a autenticação para diferentes plataformas

Consoante a plataforma ou dispositivo onde pretende direcionar a sua aplicação, poderá ser necessária uma configuração adicional, como URIs de redirecionamento, definições de autenticação específicas ou detalhes específicos da plataforma.

Observação

• Se a sua aplicação de separador não tiver o consentimento do administrador de TI, os utilizadores da aplicação terão de dar consentimento na primeira vez que utilizarem a sua aplicação numa plataforma diferente.
• A concessão implícita não é necessária se o início de sessão único (SSO) estiver ativado numa aplicação de separador.

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. Pode escolher o tipo de plataforma a partir da aplicação 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 que selecionar.

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 pretende que o ID do Microsoft Entra envie para a sua aplicação.

6. Selecione Configurar.

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

Adquira o token de acesso para o MS Graph

Tem de adquirir um token de acesso para o Microsoft Graph. Pode fazê-lo através do fluxo microsoft Entra on-behalf-of (OBO).

A implementação atual do início de sessão único (SSO) está limitada a permissões ao nível do utilizador, que não são utilizáveis para fazer chamadas do Graph. Para obter as permissões e os âmbitos necessários para fazer uma chamada do Graph, as aplicações SSO têm de implementar um serviço Web personalizado para trocar o token recebido da biblioteca JavaScript do Teams por um token que inclua os âmbitos 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, terá de obter o ID do token do cliente do Teams e, em seguida, trocá-lo com o token do lado do servidor.

Obter o ID do token a partir do cliente do Teams

Segue-se um exemplo para obter o ID do token do cliente do Teams:

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

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

Segue-se um exemplo do fluxo OBO para obter o token de acesso do cliente do Teams com o 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

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:

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 identidades da Microsoft devolve um novo token de acesso que pode ser utilizado para aceder ao Microsoft Graph.
3. Obter os dados do Microsoft Graph usando o novo token.
4. Utilize a serialização da cache de tokens no MSAL.NET para colocar em cache o novo token de acesso para múltiplos, se necessário.

Importante

• Como melhor prática para a segurança, utilize sempre o código do lado do servidor para fazer chamadas do Microsoft Graph ou outras chamadas que exijam a transmissão de um token de acesso. Isso ajuda a proteger o token de ser interceptado ou vazado. DO NOT return the OBO token to the client because it would then enable the client to make direct calls to Microsoft Graph.
• Duas aplicações separadas registadas no Microsoft Entra ID requerem tokens individuais para cada aplicação. Utilize o fluxo OBO para ativar a comunicação entre as aplicações.
• Não utilize notifySuccess o resultado para devolver as informações do token à página principal. Utilize localStorage para guardar o token e transmitir a chave de item através de notifySuccess.

Obter consentimento

A sua aplicação pode obter consentimento para permissões do Graph globalmente junto do administrador inquilino ou individualmente por utilizador.

Do administrador inquilino

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

Do utilizador

Ao pedir consentimento adicional do utilizador através da capacidade de autenticação da biblioteca de cliente JavaScript (TeamsJS) do Microsoft Teams, tenha em atenção as seguintes considerações:

Para implementar a autenticação SSO num separador pessoal, siga estes passos:

1. O token obtido com getAuthToken() tem de ser trocado no lado do servidor através do fluxo OBO do Microsoft Entra para obter acesso às outras APIs do Graph. Certifique-se de que utiliza o ponto final do Microsoft Entra v2 para esta troca.

2. Quando tenta executar a troca de tokens para um utilizador pela primeira vez, se o Microsoft Entra se recusar a trocar tokens, poderá dever-se ao facto de o utilizador não ter consentido dar permissão à sua aplicação para os dados do utilizador. Nestes 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 expirado, revogado, mal formado ou ausente. Exemplos de interaction_required incluem quando é necessária a autenticação multifator ou a inscrição de dispositivos empresariais.

3. Se a troca falhar devido aos invalid_grant erros ou interaction_required , tem de pedir consentimento ao utilizador. Uma vez que a interação do utilizador só pode ocorrer a partir do cliente, o servidor tem de devolver uma indicação à aplicação cliente de que o consentimento é necessário. Em seguida, pode utilizar a interface de utilizador (IU) para pedir ao utilizador da aplicação que conceda outro consentimento. A IU tem de incluir um botão que aciona uma caixa de diálogo de consentimento do Microsoft Entra.

4. Para pedir consentimento ao utilizador para que a sua aplicação aceda aos respetivos dados, tem de incluir a prompt=consent propriedade no parâmetro query-string-parameter para o ID do Microsoft Entra.

   • Em vez de ?scope={scopes}, use ?prompt=consent&scope={scopes}
   • Certifique-se de que a {scopes} propriedade inclui todos os âmbitos que está a pedir ao utilizador. Por exemplo: Mail.Read ou User.Read.

   Para processar o consentimento incremental da aplicação de separador, veja Consentimento do utilizador incremental e dinâmico.

5. Depois de o utilizador da aplicação ter concedido mais permissões, repita o fluxo OBO para obter acesso a Graph APIs adicionais. Para obter mais informações, veja Código de exemplo de Autenticação SSO do Separador Pessoal do Teams .

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

Se um utilizador não tiver concedido o consentimento da aplicação Microsoft Entra para estes âmbitos, a chamada OBO falha com invalid_grant ou interaction_required erro. Este erro informa-o de que tem de pedir o consentimento do utilizador.

Quando o utilizador deu o seu consentimento e tenta fazer uma chamada OBO imediatamente, por vezes existe uma condição race entre o ID do Microsoft Entra propagar este consentimento e o pedido OBO a decorrer. Isto pode levar a que a chamada OBO falhe com os mesmos invalid_grant erros ou interaction_required erros.

Se a sua aplicação não tiver conhecimento deste comportamento, poderá pedir consentimento várias vezes ao utilizador. A melhor prática é criar um mecanismo de espera e repetição significativo para evitar esta experiência de utilizador inferior ao ideal.

O mecanismo de espera e repetição tem de ser registado se um utilizador tiver consentido os âmbitos necessários. Se uma chamada à API que inclui um pedido OBO falhar com os erros acima, mas o utilizador já tiver consentido, evite mostrar o pedido de consentimento ao utilizador. Em vez disso, aguarde algum tempo antes de repetir a chamada à API. Normalmente, o ID do Microsoft Entra envia o consentimento dentro de três a cinco segundos. Numa das nossas aplicações de exemplo, repetimos até três vezes com o dobro do tempo de espera entre cada repetição, começando numa espera de um segundo.

Se, após três a cinco tentativas, o fluxo OBO continuar a falhar, o utilizador poderá não ter consentido todos os âmbitos necessários e poderá ter de pedir-lhe que consintam novamente.

Esta abordagem ajuda a reduzir a possibilidade de ser pedido consentimento ao utilizador mais do que uma vez.

Exemplo de código

Nome de exemplo	Descrição	C#	Node.js
Separadores Microsoft Entra SSO	Aplicação de exemplo do Microsoft Teams para separadores Microsoft Entra SSO, que utiliza o fluxo OBO para chamar Graph APIs.	View	Exibir

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