Solicitar permissões por meio de consentimento

  • Artigo

Os aplicativos na plataforma de identidade da Microsoft dependem de consentimento para acessar os recursos necessários ou APIs. Diferentes tipos de consentimento são melhores para diferentes cenários de aplicativo. A escolha da melhor abordagem de consentimento para seu aplicativo ajudará a ter mais sucesso com usuários e organizações.

Neste artigo, você aprenderá sobre os diferentes tipos de consentimento e como solicitar permissões para seu aplicativo por meio de consentimento.

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 centro de administração do Microsoft Entra. Se o usuário (ou um administrador, conforme apropriado) não concedeu 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 a confiança no consentimento estático e de uma única lista de permissões mantenha o código eficiente e simples, isso também significa que seu aplicativo solicitará todas as permissões necessárias antecipadamente. Isso pode desencorajar os usuários e administradores a aprovar a solicitação de acesso do aplicativo.

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 centro de administração do Microsoft Entra. Em vez disso, você pode solicitar permissões incrementalmente. Você pode solicitar um conjunto mínimo de permissões antecipadamente, e solicitar mais ao longo do tempo, pois o cliente usa recursos adicionais 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 aplicativo.

Permitir que um aplicativo solicite permissões dinamicamente por meio do parâmetro scope fornece aos desenvolvedores controle total sobre a experiência do usuário. Você também pode optar por carregar sua experiência de consentimento e solicitar todas as permissões em uma solicitação inicial de autorização. Ou, se seu aplicativo precisar de um grande número de permissões, você pode reunir essas permissões do usuário de forma incremental, à medida que ele tentar usar determinados recursos do seu aplicativo ao longo do tempo.

Importante

O consentimento dinâmico pode ser conveniente, mas apresenta um grande desafio para permissões que exigem consentimento do administrador. A experiência de consentimento do administrador nas folhas Registros de aplicativo e Aplicativo empresarial no portal não sabe sobre essas permissões dinâmicas no momento do consentimento. Recomendamos que um desenvolvedor liste todas as permissões com privilégios de administrador necessárias para o aplicativo no portal. Isso permite que os administradores de locatários deem consentimento em nome de todos os seus usuários no portal, uma vez. Os usuários não precisarão passar pela experiência de consentimento para essas permissões ao entrar. A alternativa é usar o consentimento dinâmico para essas permissões. Para conceder o consentimento do administrador, um administrador individual entra no aplicativo, dispara uma solicitação de consentimento para as permissões apropriadas e seleciona o consentimento de toda a minha organização na caixa de diálogo de consentimento.

Em uma solicitação de autorização do OpenID Connect ou OAuth 2.0, um aplicativo pode solicitar as permissões de que precisa usando o parâmetro de consulta scope. Por exemplo, quando um usuário entra em um aplicativo, o aplicativo envia uma solicitação como o exemplo a seguir. (Quebras de linha adicionadas para legibilidade).

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.

No exemplo a seguir, as permissões offline_access ("Manter o acesso aos dados para os quais recebeu acesso") e a permissão User.Read ("Entrar e ler o seu perfil") são incluídas automaticamente no consentimento inicial para um aplicativo. Essas permissões são necessárias para a funcionalidade adequada do aplicativo. A permissão offline_access concede ao aplicativo acesso para atualizar tokens que são essenciais para aplicativos nativos e aplicativos Web. A permissão User.Read concede acesso à declaração sub. Ela permite que o cliente ou aplicativo identifique corretamente o usuário ao longo do tempo e acesse informações de usuário rudimentares.

Captura de tela de exemplo que mostra o consentimento da conta corporativa.

Quando o usuário aprova a solicitação de permissão, o consentimento é registrado. O usuário não precisa consentir novamente ao entrar mais tarde no aplicativo.

A solicitação de consentimento para um locatário inteiro exige o consentimento do administrador. O consentimento do administrador feito em nome de uma organização exige as permissões estáticas registradas para o aplicativo. Defina essas permissões no portal de registro de aplicativo se você precisar do conselho de um administrador em nome de toda a organização.

Quando o aplicativo solicita permissões delegadas que exigem consentimento do administrador, o usuário recebe uma mensagem de erro informando que não está autorizado a consentir com as permissões do aplicativo. É necessário que o usuário solicite ao administrador acesso ao aplicativo. Se o administrador conceder o consentimento para um locatário inteiro, os usuários da organização não verão uma página de consentimento para o aplicativo, a menos que as permissões concedidas anteriormente sejam revogadas ou o aplicativo solicite uma nova permissão incrementalmente.

Os administradores que usam o mesmo aplicativo verão o prompt de consentimento do administrador. O prompt de consentimento do administrador fornece uma caixa de seleção que permite que ele conceda ao aplicativo acesso aos dados solicitados em nome dos usuários para o locatário inteiro. Para obter mais informações sobre a experiência de consentimento do usuário e do administrador, consulte Experiência de consentimento do aplicativo.

Exemplos de permissões delegadas para o Microsoft Graph que exigem o consentimento do administrador são:

  • Ler o perfil completo de todos os usuários usando o User.Read.All
  • Gravar dados no diretório da organização usando o Directory.ReadWrite.All
  • Ler todos os grupos no diretório da organização usando o Groups.Read.All

Para exibir a lista completa de permissões do Microsoft Graph, confira Referência de permissões do Microsoft Graph.

Você também pode configurar as permissões em seus próprios recursos para exigir o consentimento do administrador. Para obter mais informações sobre como adicionar escopos que exigem consentimento do administrador, consulte Adicionar um escopo que exige consentimento do administrador.

Algumas organizações podem alterar a política de consentimento do usuário padrão para o locatário. Quando seu aplicativo solicita acesso a permissões, eles são avaliados com base nessas políticas. O usuário pode precisar solicitar o consentimento do administrador mesmo quando não for necessário por padrão. Para saber como os administradores gerenciam políticas de consentimento para aplicativos, consulte Gerenciar políticas de consentimento do aplicativo.

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.

As permissões de aplicativo sempre exigem o consentimento do administrador. As permissões de aplicativo não têm um contexto de usuário e a concessão de consentimento não é feita em nome de um usuário específico. Em vez disso, o aplicativo cliente recebe permissões diretamente. Essas permissões são usadas apenas por serviços daemon e outros aplicativos não interativos executados em segundo plano. Os administradores precisam configurar as permissões antecipadamente e conceder consentimento do administrador por meio do centro de administração do Microsoft Entra.

Caso o aplicativo que solicita a permissão seja um aplicativo multilocatário, seu registro de aplicativo só existe no locatário em que ele foi criado, portanto, as permissões não podem ser configuradas no locatário local. Se o aplicativo solicitar permissões que exijam consentimento do administrador, ele precisará consentir em nome dos usuários. Para consentir com essas permissões, os administradores precisam fazer logon no aplicativo por conta própria, para que a experiência de entrada do consentimento do administrador seja disparada. Para saber como configurar a experiência de consentimento do administrador para aplicativos multilocatário, confira Habilitar logons multilocatário

Um administrador pode consentir com um aplicativo com as opções a seguir.

Normalmente, quando você cria um aplicativo que exige o consentimento do administrador, o aplicativo precisa de uma página ou de um modo de exibição em que o administrador possa aprovar as permissões do aplicativo. Esta página pode ser:

  • Parte do fluxo de inscrição do aplicativo.
  • Parte das configurações do aplicativo.
  • Um fluxo de "conexão" dedicado.

Em muitos casos, faz sentido que o aplicativo somente mostre o modo de exibição "conectar" depois que o usuário entra com uma conta corporativa ou de estudante da Microsoft.

Quando o usuário entra em seu aplicativo, você pode identificar a organização à qual o administrador pertence antes de pedir a ele que aprove as permissões necessárias. Embora essa etapa não seja estritamente necessária, ela pode ajudá-lo a criar uma experiência mais intuitiva para os usuários empresariais.

Para conectar um usuário, siga os tutoriais de protocolo da plataforma de identidade da Microsoft.

Solicitar as permissões no portal de registro do aplicativo

No portal de registro de aplicativo, os aplicativos podem listar as permissões necessárias, incluindo permissões delegadas e permissões de aplicativo. Essa configuração permite o uso do escopo .default e da opção Conceder consentimento de administrador do centro de administração do Microsoft Entra.

Em geral, as permissões devem ser definidas estaticamente para um determinado aplicativo. Eles devem ser um superconjunto das permissões que o aplicativo solicitará de forma dinâmica ou incremental.

Observação

As permissões de aplicativo só podem ser solicitadas por meio do uso de .default. Sendo assim, se seu aplicativo precisar de permissões, verifique se elas estão listadas no portal de registro de aplicativo.

Para configurar a lista de permissões solicitadas estaticamente para um aplicativo:

  1. Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.
  2. Navegue até Identidade>Aplicativos>Registros de aplicativo>Todos os aplicativos.
  3. Selecione um aplicativo ou criar um aplicativo, caso ainda não tenha feito isso.
  4. Na página Visão geral do aplicativo, em Gerenciar, selecione Permissões de API>Adicionar uma permissão.
  5. Selecione Microsoft Graph na lista de APIs disponíveis. Em seguida, adicione as permissões que seu aplicativo requer.
  6. Selecione Adicionar Permissões.

Resposta bem-sucedida

Se o administrador aprovar as permissões para o seu aplicativo, a resposta bem-sucedida será:

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Parâmetro Descrição
tenant O locatário do diretório que concedeu as permissões solicitadas, no formato de GUID.
state Um valor incluído na solicitação também será retornado na resposta do token. Pode ser uma cadeia de caracteres de qualquer conteúdo desejado. O estado é usado para codificar as informações sobre o estado do usuário no aplicativo antes da solicitação de autenticação ocorrida, como a página ou exibição em que ele estava.
admin_consent Será definido como True.

Depois de receber uma resposta bem-sucedida do ponto de extremidade de consentimento do administrador, o aplicativo terá as permissões solicitadas por ele. Em seguida, você pode solicitar um token para o recurso desejado.

Resposta de erro

Se o administrador não aprovar as permissões para o seu aplicativo, a resposta de falha será:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Parâmetro Descrição
error Uma cadeia de caracteres de código de erro que pode ser utilizada para classificar os tipos de erros que ocorrem. Ela também pode ser usada para reagir a erros.
error_description Uma mensagem de erro específica que pode ajudar um desenvolvedor a identificar a causa raiz de um erro.

Depois que o usuário consente permissões para o aplicativo, este pode adquirir tokens de acesso que representam a permissão do aplicativo para acessar um recurso em alguma capacidade. Um token de acesso pode ser usado para um único recurso. Mas todas as permissões que seu aplicativo recebeu para esse recurso estão codificadas dentro do token de acesso. Para adquirir um token de acesso, o aplicativo poderá fazer uma solicitação ao ponto de extremidade do token da plataforma de identidade da Microsoft, como esta:

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

Você pode usar o token de acesso resultante em solicitações HTTP para o recurso. Ele confiável indica ao recurso que seu aplicativo tem a permissão apropriada para executar uma tarefa específica.

Para saber mais sobre o protocolo OAuth 2.0 e como obter tokens de acesso, consulte a referência do protocolo do ponto de extremidade da plataforma de identidade da Microsoft.

Confira também