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 fornece 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 usado por aplicativos de terceiros para acessar em nome de um usuário os recursos hospedados na Web. Qualquer recurso hospedado na Web que se integra à plataforma de identidade da Microsoft tem um identificador de recurso ou um URI de ID do aplicativo.

Confira alguns exemplos de recursos da Microsoft hospedados na Web:

  • 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 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 possam ser usadas para dividir a funcionalidade que ele oferece em partes menores. Quando a funcionalidade de um recurso é agrupada em pequenos conjuntos de permissões, aplicativos de terceiros podem ser criados para solicitar apenas as permissões necessárias para executar a função pretendida. Os usuários e administradores podem saber quais dados o aplicativo tem permissão para acessar.

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-as no parâmetro de consulta scope. A plataforma de identidade aceita diversos escopos bem definidos do OpenID Connect e permissões baseadas em recursos (elas são individualmente indicadas pelo acréscimo do respectivo valor ao identificador do recurso ou ao URI de 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 com muitos privilégios só podem ser concedidas por meio do consentimento do administrador. Elas podem ser solicitadas ou concedidas por meio do ponto de extremidade de consentimento do administrador.

Observação

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

Tipos de permissões

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. No caso desses aplicativos, o usuário ou um administrador consente com as permissões solicitadas pelo aplicativo. O aplicativo recebe permissão para atuar como usuário conectado ao fazer 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 do consentimento para obter acesso às APIs ou aos recursos necessários. 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 do consentimento estático do usuário, você precisa 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 forneçam consentimento em nome de todos os usuários da organização.

Embora as permissões estáticas do aplicativo definidas no portal do Azure simplifiquem o código, podem ocorrer alguns problemas para os desenvolvedores:

  • O aplicativo precisa solicitar todas as permissões necessárias na primeira tentativa de logon do usuário. Isso pode resultar em uma longa lista de permissões que desencoraja os usuários finais a aprovar o acesso do aplicativo no primeiro logon.

  • O aplicativo precisa saber antecipadamente todos os recursos que acessaria. É 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 de maneira incremental. 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, já que a experiência de consentimento do administrador não tem informações sobre essas permissões no momento do consentimento. Se você precisar de permissões com privilégio de administrador ou o aplicativo usar consentimento dinâmico, será preciso 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 forneçam consentimento em nome de todos os usuários.

O consentimento do administrador é necessário quando o aplicativo precisa de acesso a determinadas permissões com privilégios muito grandes. 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 requer as permissões estáticas registradas para o aplicativo. Defina essas permissões no portal de registro do aplicativo se for preciso que um administrador dê o consentimento 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 faz logon 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 separada por espaço de permissões delegadas que o aplicativo está solicitando. Cada permissão é indicada pelo acréscimo do valor da permissão ao identificador do recurso (o URI de ID do aplicativo). No exemplo de solicitação, o aplicativo precisa de permissão para ler o calendário do usuário e enviar emails em nome dele.

Depois que o usuário insere as credenciais, a plataforma de identidade da Microsoft verifica se há algum registro correspondente de consentimento do usuário. Se o usuário não consentiu com nenhuma das permissões solicitadas no passado e, se o administrador não consentiu com essas permissões em nome de toda a organização, a plataforma de identidade da Microsoft solicita que ele conceda as permissões solicitadas.