Escopos e permissões na plataforma de identidade da Microsoft

  • Artigo

A plataforma de identidade da Microsoft implementa o protocolo de autorização OAuth 2.0 . OAuth 2.0 é um método através do qual um aplicativo de terceiros pode acessar recursos hospedados na Web em nome de um usuário. Qualquer recurso hospedado na Web que se integre à plataforma de identidade da Microsoft tem um identificador de recurso ou URI de ID de aplicativo.

Neste artigo, você aprenderá sobre escopos e permissões na plataforma de identidade.

A lista a seguir mostra alguns exemplos de recursos hospedados na Web da Microsoft:

  • Microsoft Graph: https://graph.microsoft.com
  • API de email do Microsoft 365: https://outlook.office.com
  • Azure Key Vault: https://vault.azure.net

O mesmo é válido para quaisquer recursos de terceiros que tenham sido integrados com a plataforma de identidade da Microsoft. Qualquer um desses recursos também pode definir um conjunto de permissões que podem ser usadas para dividir a funcionalidade desse recurso em partes menores. Como exemplo, o Microsoft Graph definiu permissões para executar as seguintes tarefas, entre outras:

  • Ler o calendário de um utilizador
  • Gravar no calendário de um usuário
  • Enviar e-mail como usuário

Devido a esses tipos de definições de permissão, o recurso tem controle refinado sobre seus dados e como a funcionalidade da API é exposta. Um aplicativo de terceiros pode solicitar essas permissões de usuários e administradores, que devem aprovar a solicitação antes que o aplicativo possa acessar dados ou agir em nome de um usuário.

Quando a funcionalidade de um recurso é dividida em pequenos conjuntos de permissões, os aplicativos de terceiros podem ser criados para solicitar apenas as permissões necessárias para executar sua função. Os usuários e administradores podem saber quais dados o aplicativo pode acessar. E eles podem estar mais confiantes de que o aplicativo não está se comportando com intenção maliciosa. Os desenvolvedores devem sempre respeitar o princípio do menor privilégio, pedindo apenas as permissões necessárias para que seus aplicativos funcionem.

No OAuth 2.0, esses tipos de conjuntos de permissões são chamados de escopos. Eles também são frequentemente chamados de permissões. Na plataforma de identidade da Microsoft, uma permissão é representada como um valor de cadeia de caracteres. Um aplicativo solicita as permissões necessárias especificando a permissão no scope parâmetro de consulta. A plataforma de identidade suporta vários escopos OpenID Connect bem definidos e permissões baseadas em recursos (cada permissão é indicada anexando o valor de permissão ao identificador do recurso ou ao URI da ID do aplicativo). Por exemplo, a cadeia de caracteres de permissão https://graph.microsoft.com/Calendars.Read é usada para solicitar permissão para ler calendários de usuários no Microsoft Graph.

Em solicitações ao servidor de autorização, para a plataforma de identidade da Microsoft, se o identificador de recurso for omitido no parâmetro scope, o recurso será considerado como Microsoft Graph. Por exemplo, scope=User.Read é equivalente a https://graph.microsoft.com/User.Read.

Permissões restritas pelo administrador

As permissões na plataforma de identidade da Microsoft podem ser definidas como restritas a administrador. Por exemplo, muitas permissões do Microsoft Graph com privilégios mais altos exigem aprovação do administrador. Se seu aplicativo exigir permissões restritas ao administrador, o administrador de uma organização deverá consentir com esses escopos em nome dos usuários da organização. A seção a seguir fornece exemplos desses tipos de permissões:

  • User.Read.All: Leia todos os perfis de usuários
  • Directory.ReadWrite.All: Gravar dados no diretório de uma organização
  • Groups.Read.All: Ler todos os grupos no diretório de uma organização

Nota

Em solicitações para os pontos de extremidade de autorização, token ou consentimento para a plataforma de identidade da Microsoft, se o identificador de recurso for omitido no parâmetro scope, o recurso será considerado como Microsoft Graph. Por exemplo, scope=User.Read é equivalente a https://graph.microsoft.com/User.Read.

Embora um usuário consumidor possa conceder a um aplicativo acesso a esse tipo de dados, os usuários organizacionais não podem conceder acesso ao mesmo conjunto de dados confidenciais da empresa. Se seu aplicativo solicitar acesso a uma dessas permissões de um usuário organizacional, o usuário receberá uma mensagem de erro informando que ele não está autorizado a consentir com as permissões do seu aplicativo.

Se o aplicativo solicitar permissões de aplicativo e um administrador conceder essas permissões, essa concessão não será feita em nome de nenhum usuário específico. Em vez disso, o aplicativo cliente recebe permissões diretamente. Esses tipos de permissões só devem ser usados por serviços de daemon e outros aplicativos não interativos executados em segundo plano. Para obter mais informações sobre o cenário de acesso direto, consulte Cenários de acesso na plataforma de identidade da Microsoft.

Para obter um guia passo a passo sobre como expor escopos em uma API da Web, consulte Configurar um aplicativo para expor uma API da Web.

Escopos do OpenID Connect

A implementação da plataforma de identidade Microsoft do OpenID Connect tem alguns escopos bem definidos que também são hospedados no Microsoft Graph: openid, email, profilee offline_access. Os address escopos e phone OpenID Connect não são suportados.

Se você solicitar os escopos do OpenID Connect e um token, receberá um token para chamar o ponto de extremidade UserInfo.

Âmbito openid de aplicação

Se um aplicativo entrar usando o OpenID Connect, ele deverá solicitar o openid escopo. O openid escopo aparece na página de consentimento da conta profissional como a permissão Entrar você .

Ao usar essa permissão, um aplicativo pode receber um identificador exclusivo para o usuário na forma da sub declaração. A permissão também dá ao aplicativo acesso ao ponto de extremidade UserInfo. O openid escopo pode ser usado no ponto de extremidade de token da plataforma de identidade da Microsoft para adquirir tokens de ID. O aplicativo pode usar esses tokens para autenticação.

Âmbito email de aplicação

O email escopo pode ser usado com o openid escopo e quaisquer outros escopos. Ele dá ao aplicativo acesso ao endereço de e-mail principal do usuário na forma da email reivindicação.

A email declaração é incluída em um token somente se um endereço de e-mail estiver associado à conta de usuário, o que nem sempre é o caso. Se seu aplicativo usa o email escopo, o aplicativo precisa ser capaz de lidar com um caso em que nenhuma email declaração existe no token.

Âmbito profile de aplicação

O profile escopo pode ser usado com o openid escopo e qualquer outro escopo. Ele dá ao aplicativo acesso a uma grande quantidade de informações sobre o usuário. As informações que ele pode acessar incluem, mas não se limitam a, nome próprio, sobrenome, nome de usuário preferencial e ID do objeto do usuário.

Para obter uma lista completa das profile declarações disponíveis no id_tokens parâmetro para um usuário específico, consulte a id_tokens referência.

Âmbito offline_access de aplicação

O offline_access escopo dá ao seu aplicativo acesso a recursos em nome do usuário por um longo período. Na página de consentimento, esse escopo aparece como a permissão Manter acesso aos dados que você lhe deu acesso .

Quando um usuário aprova o offline_access escopo, seu aplicativo pode receber tokens de atualização do ponto de extremidade de token da plataforma de identidade da Microsoft. Os tokens de atualização são de longa duração. Seu aplicativo pode obter novos tokens de acesso à medida que os mais antigos expiram.

Nota

Atualmente, essa permissão aparece em todas as páginas de consentimento, mesmo para fluxos que não fornecem um token de atualização (como o fluxo implícito). Essa configuração aborda cenários em que um cliente pode começar dentro do fluxo implícito e, em seguida, mover para o fluxo de código onde um token de atualização é esperado.

Na plataforma de identidade da Microsoft (solicitações feitas ao ponto de extremidade v2.0), seu aplicativo deve solicitar explicitamente o offline_access escopo para receber tokens de atualização. Portanto, ao resgatar um código de autorização no fluxo de código de autorização do OAuth 2.0, você receberá apenas um token de acesso do /token ponto de extremidade.

O token de acesso é geralmente válido por cerca de uma hora. Nesse ponto, seu aplicativo precisa redirecionar o usuário de volta ao /authorize ponto de extremidade para solicitar um novo código de autorização. Durante esse redirecionamento e dependendo do tipo de aplicativo, o usuário pode precisar inserir suas credenciais novamente ou consentir com as permissões novamente.

O token de atualização tem uma expiração mais longa do que o token de acesso e geralmente é válido por um dia. Para obter mais informações sobre como obter e usar tokens de atualização, consulte a referência de protocolo da plataforma de identidade da Microsoft.

Âmbito .default de aplicação

O .default escopo é usado para se referir genericamente a um serviço de recurso (API) em uma solicitação, sem identificar permissões específicas. Se o consentimento for necessário, usando .default sinais de que o consentimento deve ser solicitado para todas as permissões necessárias listadas no registro do aplicativo (para todas as APIs na lista).

O valor do parâmetro scope é construído usando o identificador URI para o recurso e .default, separados por uma barra (/). Por exemplo, se o URI do identificador do recurso for https://contoso.com, o escopo a ser solicitado será https://contoso.com/.default. Para casos em que você deve incluir uma segunda barra para solicitar corretamente o token, consulte a seção sobre barras à direita.

O uso scope={resource-identifier}/.default é funcionalmente o mesmo que resource={resource-identifier} no ponto de extremidade v1.0 (onde {resource-identifier} é o URI do identificador para a API, por exemplo https://graph.microsoft.com , para o Microsoft Graph).

O .default escopo pode ser usado em qualquer fluxo OAuth 2.0 e para iniciar o consentimento do administrador. Seu uso é necessário no fluxo On-Behalf-Of e no fluxo de credenciais do cliente.

Os clientes não podem combinar consentimento estático (.default) e consentimento dinâmico em uma única solicitação. Portanto, scope=https://graph.microsoft.com/.default Mail.Read resulta em um erro porque combina tipos de escopo.

O .default parâmetro scope só aciona um prompt de consentimento se o consentimento não tiver sido concedido para qualquer permissão delegada entre o cliente e o recurso, em nome do usuário conectado.

Se o consentimento existir, o token retornado conterá todos os escopos concedidos para esse recurso para o usuário conectado. No entanto, se nenhuma permissão tiver sido concedida para o recurso solicitado (ou se o prompt=consent parâmetro tiver sido fornecido), um prompt de consentimento será mostrado para todas as permissões necessárias configuradas no registro do aplicativo cliente, para todas as APIs na lista.

Por exemplo, se o escopo https://graph.microsoft.com/.default for solicitado, seu aplicativo está solicitando um token de acesso para a API do Microsoft Graph. Se pelo menos uma permissão delegada tiver sido concedida para o Microsoft Graph em nome do usuário conectado, a entrada continuará e todas as permissões delegadas do Microsoft Graph concedidas para esse usuário serão incluídas no token de acesso. Se nenhuma permissão tiver sido concedida para o recurso solicitado (Microsoft Graph, neste exemplo), um prompt de consentimento será apresentado para todas as permissões necessárias configuradas no aplicativo, para todas as APIs na lista.

Exemplo 1: O usuário, ou administrador do locatário, concedeu permissões

Neste exemplo, o usuário ou um administrador de locatário concedeu as Mail.Read permissões e User.Read Microsoft Graph ao cliente.

Se o cliente solicitar scope=https://graph.microsoft.com/.default, nenhum prompt de consentimento será exibido, independentemente do conteúdo das permissões registradas do aplicativo cliente para o Microsoft Graph. O token retornado contém os escopos Mail.Read e User.Read.

Exemplo 2: O usuário não concedeu permissões entre o cliente e o recurso

Neste exemplo, o usuário não concedeu consentimento entre o cliente e o Microsoft Graph, nem tem um administrador. O cliente se registrou para as permissões User.Read e Contacts.Read. Ele também se registrou para o escopo https://vault.azure.net/user_impersonationdo Azure Key Vault .

Quando o cliente solicita um token para scope=https://graph.microsoft.com/.defaulto , o usuário vê uma página de consentimento para o Microsoft Graph User.Read e Contacts.Read escopos e para o escopo do Cofre de Chaves user_impersonation do Azure. O token retornado contém apenas os escopos User.Read e Contacts.Read e pode ser usado somente no Microsoft Graph.

Exemplo 3: O usuário consentiu e o cliente solicita mais escopos

Neste exemplo, o usuário já consentiu para Mail.Read o cliente. O cliente se registrou para o Contacts.Read escopo.

O cliente primeiro executa um login com scope=https://graph.microsoft.com/.defaulto . Com base no scopes parâmetro da resposta, o código do aplicativo deteta que apenas Mail.Read foi concedido. Em seguida, o cliente inicia um segundo login usando scope=https://graph.microsoft.com/.defaulto , e desta vez força o consentimento usando prompt=consento . Se o usuário tiver permissão para consentir todas as permissões que o aplicativo registrou, será mostrado o prompt de consentimento. (Caso contrário, ser-lhes-á apresentada uma mensagem de erro ou o formulário de pedido de consentimento de administrador.) Ambos Contacts.Read e Mail.Read estarão no prompt de consentimento. Se o consentimento for concedido e a entrada continuar, o token retornado será para o Microsoft Graph e conterá Mail.Read e Contacts.Read.

Usando o .default escopo com o cliente

Em alguns casos, um cliente pode solicitar seu próprio .default escopo. O exemplo a seguir demonstra esse cenário.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
    ?response_type=token            //Code or a hybrid flow is also possible here
    &client_id=00001111-aaaa-2222-bbbb-3333cccc4444
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

Este exemplo de código produz uma página de consentimento para todas as permissões registradas se as descrições anteriores de consentimento se .default aplicarem ao cenário. Em seguida, o código retorna um id_token, em vez de um token de acesso.

Essa configuração não deve ser usada por novos clientes destinados à plataforma de identidade da Microsoft. Certifique-se de Migrar para a Biblioteca de Autenticação da Microsoft (MSAL) da Biblioteca de Autenticação do Azure AD (ADAL).

Fluxo de concessão de credenciais do cliente e .default

Outro uso é solicitar funções de aplicativo (também conhecidas como permissões de aplicativo) em um aplicativo não interativo, como um aplicativo daemon que usa o fluxo de concessão de credenciais do .default cliente para chamar uma API da Web.

Para definir funções de aplicativo (permissões de aplicativo) para uma API Web, consulte Adicionar funções de aplicativo em seu aplicativo.

As solicitações de credenciais do cliente em seu serviço de cliente devem incluir scope={resource}/.default. {resource} Aqui está a API da Web que seu aplicativo pretende chamar e deseja obter um token de acesso. Não há suporte para a emissão de uma solicitação de credenciais de cliente usando permissões (funções) de aplicativo individuais. Todas as funções do aplicativo (permissões de aplicativo) que foram concedidas para essa API da Web estão incluídas no token de acesso retornado.

Para conceder acesso às funções de aplicativo que você definir, incluindo a concessão de consentimento de administrador para o aplicativo, consulte Configurar um aplicativo cliente para acessar uma API da Web.

Barra à direita e .default

Alguns URIs de recursos têm uma barra à direita, por exemplo, https://contoso.com/ em oposição a https://contoso.com. A barra à direita pode causar problemas com a validação do token. Os problemas ocorrem principalmente quando um token é solicitado para o Azure Resource Manager (https://management.azure.com/).

Nesse caso, uma barra à direita no URI do recurso significa que a barra deve estar presente quando o token é solicitado. Então, quando você solicita um token para https://management.azure.com/ e usar .default, você deve solicitar https://management.azure.com//.default (observe a barra dupla!).

Em geral, se você verificar que o token está sendo emitido e se o token está sendo rejeitado pela API que deve aceitá-lo, considere adicionar uma segunda barra e tentar novamente.

Consulte também