Solicitar permissões através do consentimento

  • Artigo

Os aplicativos na plataforma de identidade da Microsoft dependem do consentimento para obter acesso aos recursos ou APIs necessários. Diferentes tipos de consentimento são melhores para diferentes cenários de aplicação. Escolher a melhor abordagem para o 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 do consentimento.

No cenário de consentimento estático do usuário, 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 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 confiar no consentimento estático e em uma única lista de permissões mantenha o código agradável e simples, isso também significa que seu aplicativo solicitará todas as permissões que ele pode precisar antecipadamente. Isso pode desencorajar usuários e administradores de aprovar a solicitação de acesso do seu 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 à medida que o cliente usa recursos adicionais 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 aplicativos.

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

Importante

O consentimento dinâmico pode ser conveniente, mas representa um grande desafio para permissões que exigem consentimento do administrador. A experiência de consentimento do administrador nas folhas Registros de aplicativos e Aplicativos corporativos no portal não sabe sobre essas permissões dinâmicas no momento do consentimento. Recomendamos que um desenvolvedor liste todas as permissões de privilégios de administrador necessárias para o aplicativo no portal. Isso permite que os administradores de locatários consintam 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, aciona um prompt de consentimento para as permissões apropriadas e seleciona o consentimento para toda a minha organização na caixa de diálogo de consentimento.

Em uma solicitação de autorização OpenID Connect ou OAuth 2.0 , um aplicativo pode solicitar as permissões necessárias usando o scope parâmetro query. 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 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 scope parâmetro é uma lista separada por espaço 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 email 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.

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

Exemplo de captura de tela que mostra o consentimento da conta profissional.

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

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

Quando seu aplicativo solicita permissões delegadas que exigem o consentimento do administrador, o usuário recebe uma mensagem de erro informando que ele não está autorizado a consentir com as permissões do seu aplicativo. O usuário é obrigado a pedir ao administrador acesso ao aplicativo. Se o administrador conceder consentimento para todo o locatário, 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 de administrador. O prompt de consentimento do administrador fornece uma caixa de seleção que permite conceder ao aplicativo acesso aos dados solicitados em nome dos usuários para todo o locatário. 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 consentimento do administrador são:

  • Leia todos os perfis completos do usuário usando User.Read.All
  • Gravar dados no diretório de uma organização usando Directory.ReadWrite.All
  • Leia todos os grupos no diretório de uma organização usando Groups.Read.All

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

Você também pode configurar 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 requer 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, elas são avaliadas em relação a essas políticas. O usuário pode precisar solicitar o consentimento do administrador, mesmo quando não exigido por padrão. Para saber como os administradores gerenciam políticas de consentimento para aplicativos, consulte Gerenciar políticas de consentimento de aplicativos.

Nota

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

As permissões do aplicativo sempre exigem o consentimento do administrador. As permissões do aplicativo não têm um contexto de usuário e a concessão de consentimento não é feita em nome de nenhum usuário específico. Em vez disso, o aplicativo cliente recebe permissões diretamente, esses tipos de permissões são usados apenas por serviços daemon e outros aplicativos não interativos que são executados em segundo plano. Os administradores precisam configurar as permissões antecipadamente e conceder consentimento de 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 onde foi criado, portanto, as permissões não podem ser configuradas no locatário local. Se o aplicativo solicitar permissões que exijam o consentimento do administrador, o administrador precisará consentir em nome dos usuários. Para consentir com essas permissões, os administradores precisam fazer login no próprio aplicativo, para que a experiência de login de consentimento do administrador seja acionada. Para saber como configurar a experiência de consentimento de administrador para aplicativos multilocatário, consulte Habilitar logins multilocatários

Um administrador pode conceder consentimento para um aplicativo com as seguintes opções.

Normalmente, quando você cria um aplicativo que requer o consentimento do administrador, o aplicativo precisa de uma página ou exibição na qual 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 mostre o modo de exibição "conectar" somente depois que um usuário entrar com uma conta da Microsoft corporativa ou escolar.

Quando inicia sessão com o utilizador na sua aplicação, pode identificar a organização à qual o administrador pertence antes de lhe pedir para aprovar as permissões necessárias. Embora esta etapa não seja estritamente necessária, ela pode ajudá-lo a criar uma experiência mais intuitiva para seus usuários organizacionais.

Para iniciar sessão no utilizador, siga os tutoriais do protocolo da plataforma de identidade da Microsoft.

Solicitar as permissões no portal de registro do aplicativo

No portal de registro do 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 e da opção Conceder consentimento de administrador do Centro de .default 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á dinamicamente ou incrementalmente.

Nota

As permissões do aplicativo podem ser solicitadas somente através do uso do .default. Portanto, se seu aplicativo precisar de permissões de aplicativo, verifique se elas estão listadas no portal de registro do 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 um administrador de aplicativos na nuvem.
  2. Navegue até Aplicativos de identidade>>Registros de>aplicativos Todos os aplicativos.
  3. Selecione um aplicativo ou crie um aplicativo , se ainda não o fez.
  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 exige.
  6. Selecione Adicionar permissões.

Resposta com êxito

Se o administrador aprovar as permissões para seu aplicativo, a resposta bem-sucedida terá esta aparência:

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

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

Resposta de erro

Se o administrador não aprovar as permissões para seu aplicativo, a resposta com falha terá esta aparência:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Parâmetro Description
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros que ocorrem. Também pode ser usado 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 consentir com as permissões para seu aplicativo, seu aplicativo poderá adquirir tokens de acesso que representam a permissão do aplicativo para acessar um recurso em alguma capacidade. Um token de acesso só pode ser usado para um único recurso. Mas codificado dentro do token de acesso é cada permissão que seu aplicativo foi concedido para esse recurso. Para adquirir um token de acesso, seu aplicativo pode fazer uma solicitação ao ponto de extremidade do token da plataforma de identidade da Microsoft, da seguinte forma:

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 indica de forma confiável para o recurso que seu aplicativo tem a permissão adequada para executar uma tarefa específica.

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

Consulte também