Descobrir permissões e 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 . 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.

Aqui estão 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. 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 de que precisam para executar sua função. Os usuários e administradores podem saber quais dados o aplicativo pode 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 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 é usada para solicitar permissão para ler calendários de https://graph.microsoft.com/Calendars.Read 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 podem ser concedidas somente por meio do consentimento do administrador. Eles podem ser solicitados ou concedidos usando o ponto de extremidade de consentimento do administrador.

Nota

Em solicitações para os pontos de extremidade de autorização, token ou consentimento para a plataforma Microsoft Identity, 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.

Tipos de permissão

A plataforma de identidade da Microsoft oferece suporte a dois tipos de permissões: permissões delegadas e acesso somente para aplicativos.

  • As permissões delegadas são utilizadas por aplicações que têm um utilizador com sessão iniciada presente. Para estas aplicações, o utilizador ou um administrador consentem as permissões solicitadas pela aplicação. A aplicação é delegada com a permissão para agir como um utilizador com sessão iniciada quando faz chamadas ao recurso de destino.

  • As permissões de acesso somente para aplicativos 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 permissões de acesso somente para aplicativos.

Os aplicativos na plataforma de identidade da Microsoft dependem do consentimento para obter acesso aos recursos ou APIs necessários. Há muitos tipos de consentimento que seu aplicativo pode precisar saber para ser bem-sucedido. Se você estiver definindo permissões, também precisará entender como seus usuários obtêm acesso ao seu aplicativo ou API.

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

No cenário de consentimento de 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 administrador, conforme apropriado) não tiver concedido consentimento para este aplicativo, a plataforma de identidade da Microsoft solicitará que o usuário forneça consentimento neste momento. As permissões estáticas também permitem que os administradores consintam em nome de todos os usuários da organização.

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

  • O aplicativo precisa solicitar todas as permissões necessárias no primeiro login do usuário. Isso pode levar a uma longa lista de permissões que desencoraja os usuários finais de aprovar o acesso do aplicativo no login inicial.

  • O aplicativo precisa saber todos os recursos que acessaria com antecedência. É 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 pedir um conjunto mínimo de permissões antecipadamente e solicitar mais ao longo do tempo à medida que o cliente usa mais recursos do aplicativo.

Para fazer isso, você pode especificar os escopos de que seu aplicativo precisa a qualquer momento, incluindo os novos escopos scope no parâmetro ao solicitar um token de acesso - sem a necessidade de predefini-los nas informações de registro do aplicativo. Se o usuário ainda não tiver consentido com 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 para aplicativos.

Importante

O consentimento dinâmico pode ser prático, mas apresenta um desafio grande para as permissões que precisam de consentimento de administrador, uma vez que a experiência deste tipo de consentimento desconhece essas permissões no momento do consentimento. Se você precisar de permissões privilegiadas de administrador ou se seu aplicativo usar consentimento dinâmico, deverá registrar todas as permissões no portal do Azure (não apenas o subconjunto de permissões que exigem consentimento de administrador). Isso permite que os administradores de locatários consintam em nome de todos os seus usuários.

O consentimento do administrador é necessário quando seu aplicativo precisa de acesso a determinadas permissões de alto privilégio. O consentimento do administrador garante que os administradores tenham alguns outros controles 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 para aplicativos no portal de registro de aplicativos se precisar que um administrador dê consentimento em nome de toda a organização. Isso reduz os ciclos exigidos pelo administrador da organização para configurar o aplicativo.

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

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&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 scope parâmetro é uma lista separada por espaços de permissões delegadas que o aplicativo está solicitando. Cada permissão é indicada anexando o valor de permissão ao identificador do recurso (o URI do ID do aplicativo). No exemplo de solicitação, o aplicativo precisa de permissão para ler o calendário do usuário e enviar e-mails como o usuário.

Depois que o usuário insere suas credenciais, a plataforma de identidade da Microsoft verifica se há um 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 solicitará que o usuário conceda as permissões solicitadas.