Compartilhar via

Guia do desenvolvedor para solicitar permissões e consentimento na Plataforma de Identidade da Microsoft

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 aplicativo. Escolher a melhor abordagem para consentir com seu aplicativo permite que ele seja mais bem-sucedido 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 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 administrador, conforme apropriado) não conceder consentimento para este aplicativo, a plataforma de identidade da Microsoft solicitará que o usuário forneça consentimento no 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 depender do consentimento estático e de uma única lista de permissões mantenha o código agradável e simples, isso também significa que seu aplicativo solicita todas as permissões que ele pode precisar antecipadamente. Essa configuração pode desencorajar usuários e administradores a aprovar a solicitação de acesso do aplicativo.

Com o endpoint 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 mais recursos de aplicativo. Para fazer isso, você pode especificar os escopos de que seu aplicativo precisa a qualquer momento, incluindo os novos escopos no scope parâmetro ao solicitar um token de acesso , sem a necessidade de preequilá-los nas informações de registro do aplicativo.

Se o usuário não consentir com novos escopos adicionados à solicitação, ele receberá uma solicitação para 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 scope parâmetro fornece aos desenvolvedores controle total sobre a experiência do usuário. Você carrega antecipadamente sua experiência de consentimento e solicita todas as permissões em uma solicitação de autorização inicial. Se o aplicativo exigir um grande número de permissões, você poderá coletar essas permissões do usuário incrementalmente enquanto ele tenta usar determinados recursos do aplicativo ao longo do tempo.

Importante

O consentimento dinâmico pode ser conveniente, mas apresenta um desafio significativo para permissões que exigem consentimento do administrador. A experiência de consentimento do administrador nas blades Registros de Aplicativos e Aplicativos Empresariais no portal não conhece essas permissões dinâmicas no momento do consentimento. Recomendamos que um desenvolvedor liste todas as permissões com privilégios de administrador que o aplicativo precisa no portal.

Isso permite que os administradores de locatários consentam em nome de todos os usuários no portal uma vez. Os usuários não precisam passar pela experiência de consentimento dessas permissões ao entrar. A alternativa é usar o consentimento dinâmico para essas permissões. Para conceder consentimento do administrador, um administrador individual entra no aplicativo, dispara um prompt de consentimento para as permissões apropriadas e seleciona o consentimento de toda a minha organização no 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 necessárias usando o scope parâmetro de consulta. 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 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 do usuário e enviar emails como o usuário.

Após a entrada, a plataforma de identidade da Microsoft verifica se há consentimento do usuário existente. Se o usuário não aprovar as permissões solicitadas e um administrador também não as aprovar, a plataforma solicitará que o usuário conceda consentimento.

No exemplo a seguir, a offline_access permissão ("Manter o acesso aos dados aos quais você concede acesso") e User.Read a permissão ("Entrar e ler seu perfil") são incluídas automaticamente no consentimento inicial de um aplicativo. Essas permissões são necessárias para a funcionalidade de aplicativo adequada.

A offline_access permissão fornece ao aplicativo acesso a tokens de atualização críticos para aplicativos nativos e aplicativos Web. A User.Read permissão dá acesso à declaração sub . Ele permite que o cliente ou o aplicativo identifique corretamente o usuário ao longo do tempo e acesse informações rudimentares do usuário.

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

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

Solicitar consentimento para um locatário inteiro requer 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 você precisar de um administrador para dar consentimento em nome de toda a organização.

Quando o aplicativo solicita permissões delegadas que exigem consentimento do administrador, os usuários veem um erro "não autorizado a consentir" e precisam pedir acesso a um administrador. Depois que um administrador concede consentimento para todo o locatário, os usuários não são solicitados novamente, a menos que o consentimento seja revogado ou novas permissões sejam adicionadas.

Os administradores que usam o mesmo aplicativo veem o prompt de consentimento do administrador. O prompt de consentimento do administrador fornece uma caixa de seleção que permite que eles concedam 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 a experiência de consentimento do aplicativo.

Exemplos de permissões delegadas para o Microsoft Graph que exigem 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, consulte a 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, ele é avaliado em relação a essas políticas. Talvez o usuário precise 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 de autorização, token ou consentimento da plataforma de identidade da Microsoft, omitindo o identificador de recurso no parâmetro padrão para o scope Microsoft Graph. Por exemplo, scope=User.Read é tratado como https://graph.microsoft.com/User.Read.

As permissões de aplicativo sempre exigem 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 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 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 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, o administrador precisará consentir em nome dos usuários. Para consentir com essas permissões, os administradores precisam entrar no aplicativo por conta própria, para que a experiência de entrada de consentimento do administrador seja disparada. Para saber como configurar a experiência de consentimento do administrador para aplicativos multilocatários, consulte Habilitar logs multilocatários

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

Normalmente, quando você cria um aplicativo que requer 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 estiver conectado com uma conta corporativa da Microsoft ou uma conta da Microsoft da escola.

Ao conectar o usuário ao seu aplicativo, você pode identificar a organização à qual o administrador pertence antes de pedir que ele 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 seus usuários organizacionais.

Para conectar o 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 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 .default escopo 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 solicita dinamicamente ou incrementalmente.

Observação

As permissões de aplicativo só podem ser solicitadas usando .default. Portanto, se o aplicativo precisar de permissões de aplicativo, verifique se eles estão listados 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é Entra ID>Registro de aplicativos>Todos os aplicativos.
  3. Selecione um aplicativo ou crie um aplicativo , caso ainda não tenha feito isso.
  4. Na página Visão geral do aplicativo, em Gerenciar, selecione Permissões> de APIAdicionar uma permissão.
  5. Selecione o Microsoft Graph na lista de APIs disponíveis. Em seguida, adicione as permissões necessárias para seu aplicativo.
  6. Selecione Adicionar Permissões.

Resposta bem-sucedida

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 Descrição
tenant O locatário do diretório que concedeu ao aplicativo as permissões solicitadas, no formato GUID.
state Um valor incluído na solicitação retornada na resposta do token. Pode ser uma cadeia de caracteres de qualquer conteúdo desejado. 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 ele estava.
admin_consent Está definido como True.

Depois de receber uma resposta bem-sucedida do ponto de extremidade de consentimento do administrador, seu aplicativo receberá 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 será semelhante a esta:

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 usada para classificar tipos de erros que ocorrem. Ele 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 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 é todas as permissões concedidas ao seu aplicativo para esse recurso. Para adquirir um token de acesso, seu aplicativo pode fazer uma solicitação ao endpoint de token da plataforma de identidade da Microsoft, desta maneira:

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 realizar 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 de protocolo de ponto de extremidade da plataforma de identidade da Microsoft.

Conteúdo relacionado