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. O OAuth 2.0 é um método pelo qual um aplicativo de terceiros pode acessar recursos hospedados na Web em nome do 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 seguinte lista mostra alguns exemplos de recursos da Microsoft hospedados na Web:

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

Isso se aplica a todos os recursos de terceiros que se integraram à plataforma de identidade da Microsoft. Qualquer um desses recursos também pode definir um conjunto de permissões que pode ser usado para dividir a funcionalidade desse recurso em partes menores. Por exemplo, o Microsoft Graph definiu permissões para realizar as seguintes tarefas, entre outras:

  • Ler o calendário de um usuário
  • Escrever no calendário de um usuário
  • Enviar email como um usuário

Por causa desses tipos de definições de permissões, o recurso tem controle refinado sobre seus dados e como a funcionalidade de 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 do usuário.

Quando a funcionalidade do recurso é dividida em conjuntos menores de permissão, os aplicativos de terceiros podem ser criados para solicitar apenas as permissões que eles precisam para realizar suas funções. Os usuários e administradores podem saber quais dados o aplicativo pode acessar. E podem ter mais confiança de que o aplicativo não está se comportando com más intenções. Os desenvolvedores devem sempre obedecer o princípio de privilégios mínimos, solicitando apenas as permissões necessárias para que seus aplicativos funcionem.

No OAuth 2.0, esses tipos de conjuntos de permissão são chamados de escopos. Eles também são 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 parâmetro de consulta scope. A plataforma de identidade dá suporte a vários escopos do OpenID Connect bem definidos e permissões baseadas em recursos (cada permissão é indicada acrescentando 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.

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

Permissões restringidas pelo administrador

As permissões na plataforma de identidade da Microsoft podem ser definidas como restritas pelo administrador. Por exemplo, muitas permissões de privilégios mais altos do Microsoft Graph exigem aprovação de administrador. Se o aplicativo exigir escopos para 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: ler os perfis completos de todos os usuários
  • Directory.ReadWrite.All: gravar dados em um diretório da organização
  • Groups.Read.All: ler todos os grupos em um diretório da organização

Observação

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

Embora um usuário consumidor possa conceder acesso de aplicativo para 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 que informa que não está autorizado a consentir com as permissões de seu aplicativo.

Se o aplicativo solicita permissões de aplicativo e um administrador concede essas permissões, essa concessão não é feita em nome de um usuário específico. Na verdade, o aplicativo cliente recebe as permissões diretamente. Esses tipos de permissões são usadas apenas por serviços daemon e outros aplicativos não interativos executados em segundo plano. Para saber mais sobre o cenário de acesso direto, confira Cenários de acesso na plataforma de identidade da Microsoft.

Para ver um guia passo a passo sobre como expor escopos em uma API Web, confira Configurar um aplicativo para expor uma API Web.

Escopos do OpenID Connect

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

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

O escopo openid

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

Usando essa permissão, um aplicativo pode receber um identificador exclusivo para o usuário na forma da declaração sub. A permissão também fornece ao aplicativo acesso ao ponto de extremidade UserInfo. O escopo openid 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.

O escopo email

O escopo do email pode ser usado com o escopo do openid e com muitos outros escopos. Ele concede ao aplicativo acesso ao endereço de email principal do usuário na forma da declaração email .

A declaração email só será incluída nos tokens se um endereço de e-mail estiver associado à conta de usuário, o que nem sempre é o caso. Se seu aplicativo usar o escopo do email, o aplicativo precisará ser capaz de lidar com um caso no qual não há nenhuma declaração emailno token.

O escopo profile

O escopo do profile pode ser usado com o escopo do openid e com qualquer outro escopo. Ele fornece o acesso de aplicativo a uma grande quantidade de informações sobre o usuário. As informações que ele pode acessar incluem, entre outros, nome, sobrenome, nome de usuário preferencial e ID de objeto do usuário.

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

O escopo offline_access

O escopo do offline_access concede 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 o acesso aos dados para os quais recebeu acesso.

Quando um usuário aprova o escopo do offline_access, o aplicativo pode receber tokens de atualização do ponto de extremidade de token da plataforma de identidade da Microsoft. Os tokens de atualização têm uma vida longa. Seu aplicativo pode obter novos tokens de acesso quando os mais antigos expirarem.

Observação

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

Na plataforma de identidade da Microsoft (solicitações feitas ao ponto de extremidade v2.0), o aplicativo deve solicitar explicitamente o escopo do offline_access 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ê só receberá um token de acesso do ponto de extremidade /token.

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

O token de atualização tem uma validade mais longa que o token de acesso e costuma ser válido por um dia. Para saber mais sobre como obter e usar tokens de atualização, veja a referência de protocolo da plataforma de identidade da Microsoft.

O escopo .default

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

O valor do parâmetro de escopo é construído usando o URI do identificador do 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 de scope={resource-identifier}/.default funciona como resource={resource-identifier} no ponto de extremidade da v1.0 (em que {resource-identifier} é o URI do identificador da API, por exemplo, https://graph.microsoft.com para o Microsoft Graph).

O escopo .default 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 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 parâmetro de escopo .default dispara um prompt de consentimento somente quando 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 com relação a esse recurso para o usuário conectado. No entanto, se nenhuma permissão tiver sido concedida para o recurso solicitado (ou se o parâmetro prompt=consent 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 solicitará um token de acesso para a API do Microsoft Graph. Se pelo menos uma permissão delegada tiver sido concedida ao Microsoft Graph em nome do usuário conectado, as credenciais continuarão e todas as permissões delegadas do Microsoft Graph concedidas a 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 de locatários, concedeu permissões

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

Se o cliente solicita scope=https://graph.microsoft.com/.default, nenhuma solicitação de consentimento é exibida, independentemente do conteúdo das permissões registradas pelos aplicativos 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 foi registrado para o escopo https://vault.azure.net/user_impersonation do Azure Key Vault.

Quando o cliente solicita um token para scope=https://graph.microsoft.com/.default, o usuário vê uma página de consentimento para os escopos User.Read e Contacts.Read do Microsoft Graph e para o escopo user_impersonation do Azure Key Vault. 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 com Mail.Read para o cliente. O cliente se registrou para o escopo Contacts.Read.

Primeiro, o cliente entra com scope=https://graph.microsoft.com/.default. Com base no parâmetro scopes da resposta, o código do aplicativo detecta que apenas Mail.Read foi concedido. Em seguida, o cliente inicia uma segunda entrada com scope=https://graph.microsoft.com/.default e, desta vez, força o consentimento usando prompt=consent. Se o usuário tiver permissão para consentir com todas as permissões que o aplicativo registrou, o prompt de consentimento será exibido. (Caso contrário, será mostrada uma mensagem de erro ou o formulário de solicitação de consentimento do administrador.) Tanto Contacts.Read como Mail.Read estarão no prompt de consentimento. Se o consentimento for concedido e o logon continuar, o token retornado será para o Microsoft Graph e conterá Mail.Read e Contacts.Read.

Como usar o escopo .default com o cliente

Em alguns casos, um cliente pode solicitar seu próprio escopo .default. 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 e .default se 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 que se destinam à plataforma de identidade da Microsoft. Lembre-se de migrar da ADAL (Biblioteca de Autenticação do Azure AD) para a MSAL (Biblioteca de Autenticação da Microsoft).

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

Outro uso para .default é 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 de cliente para chamar uma API Web.

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

As solicitações de credenciais de cliente em seu serviço cliente devem incluir scope={resource}/.default. Aqui, {resource} é a API Web que seu aplicativo pretende chamar e para a qual 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 de aplicativo individuais (funções). Todas as funções de aplicativo (permissões de aplicativo) concedidas para essa API Web são incluídas no token de acesso retornado.

Para conceder acesso às funções de aplicativo definidas, incluindo a concessão de consentimento do administrador para o aplicativo, confira Configurar um aplicativo cliente para acessar uma API Web.

Barra à direita e .default

Alguns URIs de recurso 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 de recurso significa que a barra deve estar presente quando o token é solicitado. Assim, quando você solicitar um token para https://management.azure.com/ e usar .default, deverá 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 estiver sendo rejeitado pela API que deve aceitá-lo, considere adicionar uma segunda barra e tentar novamente.

Confira também