Descobrir as permissões e o consentimento

  • 3 minutos

Os aplicativos que se integram à plataforma de identidade da Microsoft seguem um modelo de autorização que dá aos usuários e administradores controle sobre como os dados podem ser acessados.

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.

A seguir, são apresentados alguns exemplos de recursos hospedados na Web da Microsoft:

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

O mesmo vale para todos os recursos de terceiros integrados à 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. 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.

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.

Um aplicativo geralmente solicita essas permissões especificando os escopos em solicitações para o ponto de extremidade de autorização da plataforma de identidade da Microsoft. No entanto, algumas permissões de alto privilégio só podem ser concedidas com o consentimento do administrador. Eles podem ser solicitados ou concedidos usando o ponto de extremidade de consentimento do administrador.

Observação

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

Tipos de permissão

A plataforma de identidade da Microsoft dá suporte a dois tipos de permissões: acesso delegado e acesso somente de aplicativo.

  • O acesso delegado é usado por aplicativos que têm um usuário conectado presente. Para esses aplicativos, o usuário ou um administrador consente com as permissões que o aplicativo solicita. O aplicativo é delegado com a permissão para atuar como um usuário conectado quando faz chamadas para o recurso de destino.

  • As permissões de acesso somente de aplicativo são usadas por aplicativos executados sem a presença de um usuário conectado, por exemplo, aplicativos executados como serviços em segundo plano ou daemons. Somente um administrador pode consentir com as permissões de acesso somente de aplicativo.

Os aplicativos na plataforma de identidade da Microsoft dependem de consentimento para acessar os recursos necessários ou APIs. Há vários tipos de autorização que seu aplicativo precisa saber para ser bem-sucedido. Se você estiver definindo permissões, também precisará entender como seus usuários terá acesso ao seu aplicativo ou à API.

Há três tipos de consentimento: consentimento estático do usuário, consentimento incremental e dinâmico do usuário e consentimento do administrador.

No cenário de consentimento do usuário estático, você deve especificar todas as permissões necessárias na configuração do aplicativo no portal do Azure. Se o usuário (ou um administrador, conforme apropriado) não tiver concedido permissão para este aplicativo, a plataforma de identidade da Microsoft solicitará ao usuário o consentimento neste momento. As permissões estáticas também permitem que os administradores deem o consentimento em nome de todos os usuários da organização.

Embora as permissões estáticas do aplicativo definidas no portal do Azure mantivessem o código simples e agradável, ele apresenta alguns problemas para os desenvolvedores:

  • O aplicativo precisa solicitar todas as permissões que precisaria no primeiro login do usuário. Isso pode resultar em uma lista longa de permissões, o que desencorajava os usuários finais a aprovarem o acesso do aplicativo na entrada inicial.

  • O aplicativo precisa conhecer todos os recursos que jamais acessaria antes do tempo. É difícil criar aplicativos que possam acessar um número arbitrário de recursos.

Com o ponto de extremidade da plataforma de identidade da Microsoft, você pode ignorar as permissões estáticas definidas nas informações de registro do aplicativo no portal do Azure e solicitar permissões incrementalmente. Você pode solicitar um conjunto mínimo de permissões antecipadamente e depois solicitar mais conforme o cliente for usando mais recursos do aplicativo.

Para fazer isso, você pode especificar os escopos que seu aplicativo precisa, incluindo os novos escopos no parâmetro scope ao solicitar um token de acesso, sem a necessidade de pré-defini-los nas informações de registro do aplicativo. Se o usuário ainda não tiver consentido em novos escopos adicionados à solicitação, ele será solicitado a consentir apenas com as novas permissões. O consentimento incremental ou dinâmico só se aplica a permissões delegadas e não a permissões de acesso somente de aplicativo.

Importante

O consentimento dinâmico pode ser conveniente, mas apresenta um grande desafio para permissões que exigem o consentimento do administrador, desde que a experiência de consentimento do administrador não saiba sobre essas permissões no momento da autorização. Se você precisar de permissões de administrador com privilégios ou se seu aplicativo usar o consentimento dinâmico, você deverá registrar todas as permissões no portal do Azure (não apenas o subconjunto de permissões que exigem o consentimento do administrador). Isso permite que os administradores de locatários deem consentimento em nome de todos os seus usuários.

O consentimento do administrador é necessário quando seu aplicativo precisa ter acesso a determinadas permissões com alto privilégio. O consentimento do administrador faz com que os administradores tenham alguns controles adicionais antes de autorizar aplicativos ou usuários a acessar dados altamente privilegiados da organização.

O consentimento do administrador feito em nome de uma organização ainda exige as permissões estáticas registradas para o aplicativo. Defina essas permissões para aplicativos no portal de registro de aplicativo se você precisar do conselho de um administrador em nome de toda a organização. Isso reduz os ciclos exigidos pelo administrador da organização para configurar o aplicativo.

Um aplicativo pode solicitar as permissões necessárias usando o parâmetro de consulta de escopo em uma solicitação de autorização do OpenID Connect ou do OAuth 2.0. Por exemplo, quando um usuário entra em um aplicativo, o aplicativo envia uma solicitação como o exemplo a seguir. Quebras de linha são adicionadas para facilitar a leitura.

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

O parâmetro scope é uma lista de permissões delegadas separadas por espaço que o aplicativo está solicitando. Cada permissão é indicada acrescentando o valor da permissão ao identificador do recurso (URI da ID de aplicativo). No exemplo de solicitação, o aplicativo precisa de permissão para ler o calendário e enviar emails como o usuário.

Depois que o usuário inserir suas credenciais, o ponto de extremidade da plataforma de identidade da Microsoft verificará se há um registro correspondente de consentimento do usuário. Se o usuário não consentiu as permissões solicitadas no passado e se o administrador não consentiu essas permissões em nome da organização, a plataforma de identidade da Microsoft solicita que o usuário conceda as permissões solicitadas.