Escopos e permissões na plataforma de identidade da Microsoft

The Microsoft identity platform implements the OAuth 2.0 authorization protocol. 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 vale para quaisquer recursos de terceiros que se integrem à plataforma de identidade da Microsoft. Qualquer um desses recursos também pode definir um conjunto de permissões que dividem a funcionalidade desse recurso em partes menores. As an example, Microsoft Graph defines permissions to do the following tasks, among others:

• 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.

In OAuth 2.0, these types of permission sets are called scopes. They're also often referred to as permissions. 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.

Admin-restricted permissions

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

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. Instead, the client application is granted permissions directly. 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 e phone escopos OpenID Connect não são suportados. Esses escopos às vezes são opcionais e considerados para enriquecimento de token de ID. Esses escopos nem sempre aparecerão em linhas separadas em um prompt de consentimento para um usuário.

If you request the OpenID Connect scopes and a token, you get a token to call the UserInfo endpoint.

O openid âmbito

If an app signs in by using OpenID Connect, it must request the openid scope. O openid escopo aparece na página de consentimento da conta profissional como a permissão para iniciar sessão.

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

O email âmbito

O email escopo pode ser usado com o openid escopo e quaisquer outros escopos. Dá ao aplicativo acesso ao endereço de e-mail principal do usuário na forma da email declaraçã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.

O profile âmbito

O profile escopo pode ser usado com o openid 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.

O offline_access âmbito

O offline_access escopo dá à sua aplicação acesso a recursos em nome do utilizador por um longo período de tempo. Na página de consentimento, este âmbito aparece como a permissão Manter acesso aos dados aos quais deu acesso.

Se alguma permissão delegada for concedida, offline_access é implicitamente concedida. Você pode supor que o aplicativo tenha offline_access se houver permissões delegadas concedidas. Os tokens de atualização são duradouros. Seu aplicativo pode obter novos tokens de acesso à medida que os mais antigos expiram.

Na plataforma de identidade da Microsoft (solicitações feitas ao ponto final v2.0), a sua aplicação deve solicitar explicitamente offline_access escopo para receber tokens de atualização. Portanto, quando você resgata um código de autorização no fluxo de código de autorização OAuth 2.0, você recebe um token de acesso do ponto de extremidade /token.

O token de acesso é válido por cerca de uma hora. Nesse ponto, a sua aplicação precisa redirecionar o utilizador 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 normalmente é válido por 90 dias. 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.

A inclusão do token de atualização na resposta pode depender de vários fatores, incluindo a configuração específica do seu aplicativo e os escopos solicitados durante o processo de autorização. Se você espera receber um token de atualização na resposta, mas não recebe, considere os seguintes fatores:

• Scope requirements: Ensure that you're requesting the offline_access scopes along with any other necessary scopes.
• Tipo de concessão de autorização: O token de renovação é fornecido quando se usa o tipo de concessão de código de autorização. Se o seu fluxo for diferente, a resposta pode ser afetada.
• Client configuration: Check your application's settings in the identity platform. Algumas configurações podem restringir a emissão de refresh_tokens.

O .default âmbito

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 , 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 deverá incluir uma segunda barra para solicitar corretamente o token, consulte a seção sobre barras finais.

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

The .default scope can be used in any OAuth 2.0 flow and to initiate admin consent. Its use is required in the On-Behalf-Of flow and client credentials flow.

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.

.default quando o utilizador dá o seu consentimento

O parâmetro de escopo .default 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 foi concedida para o recurso solicitado (ou se o parâmetro prompt=consent for 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, o logon continuará. 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 permissões Mail.Read 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 registou-se nas permissões User.Read e Contacts.Read e registou-se no âmbito do Cofre de Chaves do Azure https://vault.azure.net/user_impersonation.

Quando o cliente solicita um token para scope=https://graph.microsoft.com/.default, o utilizador vê uma página de consentimento para as permissões do Microsoft Graph User.Read e Contacts.Read, e para a permissão 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 utilizador já consentiu em Mail.Read para o cliente. O cliente se registrou para o Contacts.Read escopo.

O cliente primeiro efetua um login com scope=https://graph.microsoft.com/.default. 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 for permitido ao utilizador consentir todas as permissões que a aplicação registou, ser-lhe-á apresentado o aviso de consentimento. (Caso contrário, ser-lhes-á apresentada uma mensagem de erro ou o formulário de pedido de consentimento de administrador .) Tanto Contacts.Read como Mail.Read estão no prompt de consentimento. Se o consentimento for concedido e o início de sessão continuar, o token retornado será para o Microsoft Graph e conterá Mail.Read e Contacts.Read.

Usando o escopo .default com o cliente

Em alguns casos, um cliente poderá solicitar o 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 registadas, caso as descrições anteriores de consentimento e .default sejam aplicáveis ao cenário. Em seguida, o código retorna um id_token, em vez de um token de acesso.

Novos clientes direcionados à plataforma de identidade da Microsoft não devem usar essa configuração. Certifique-se de migrar da Biblioteca de Autenticação do Azure AD (ADAL) para a Biblioteca de Autenticação da Microsoft (MSAL).

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

Another use of .default is to request app roles (also known as application permissions) in a non-interactive application like a daemon app that uses the client credentials grant flow to call a web API.

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

Client credentials requests in your client service must include scope={resource}/.default. {resource} Aqui está a API da Web que seu aplicativo pretende chamar e deseja obter um token de acesso. Issuing a client credentials request by using individual application permissions (roles) is not supported. 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 final e .default

Alguns URIs têm uma barra final, por exemplo, https://contoso.com/ em oposição a https://contoso.com. A barra final 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 final no URI do recurso significa que a barra deve estar incluída 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 verificar que o token está a ser emitido e se o token está a ser rejeitado pela API que deve aceitá-lo, considere adicionar uma segunda barra oblíqua e tentar novamente.

See also

• Solicitar permissões através do consentimento na plataforma de identidade
• Tokens de ID na plataforma de identidade da Microsoft
• Tokens de acesso na plataforma de identidade da Microsoft