Consentimento do administrador na plataforma de identidades da Microsoft

  • Artigo

Algumas permissões requerem o consentimento de um administrador antes de poderem ser concedidas dentro de um inquilino. Você também pode usar o ponto de extremidade de consentimento de administrador para conceder permissões a um locatário inteiro.

Normalmente, quando você cria um aplicativo que usa o ponto de extremidade de consentimento de 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 fazer parte do fluxo de inscrição do aplicativo, parte das configurações do aplicativo ou pode ser um fluxo de "conexão" dedicado. Em muitos casos, faz sentido que a aplicação mostre esta vista de "ligação" apenas depois de um utilizador ter iniciado sessão com uma conta Microsoft escolar ou profissional.

Quando inicia sessão no 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 não seja estritamente necessário, ele pode ajudá-lo a criar uma experiência mais intuitiva para seus usuários organizacionais.

Solicitar as permissões de um administrador de diretório

Quando estiver pronto para solicitar permissões ao administrador da sua organização, você poderá redirecionar o usuário para o ponto de extremidade de consentimento de administrador da plataforma de identidade da Microsoft.

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent
        ?client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
        &scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
        &redirect_uri=http://localhost/myapp/permissions
        &state=12345
Parâmetro Condição Description
tenant Necessário O locatário do diretório do qual você deseja solicitar permissão. Pode ser fornecido em GUID ou formato de nome amigável OU referenciado genericamente com organizations como visto no exemplo. Não use 'comum', pois as contas pessoais não podem fornecer consentimento de administrador, exceto no contexto de um locatário. Para garantir a melhor compatibilidade com contas pessoais que gerenciam locatários, use o ID do locatário quando possível.
client_id Necessário A ID do Aplicativo (cliente) que o Centro de administração do Microsoft Entra – Registros de aplicativos atribuiu ao seu aplicativo.
redirect_uri Necessário O URI de redirecionamento para onde você deseja que a resposta seja enviada para seu aplicativo manipular. Ele deve corresponder exatamente a um dos URIs de redirecionamento que você registrou no portal de registro do aplicativo.
state Recomendado 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. Use o estado 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.
scope Necessário Define o conjunto de permissões que estão sendo solicitadas pelo aplicativo. Isso pode ser estático (usando /.default) ou escopos dinâmicos. Isso pode incluir os escopos OIDC (openid, profile, email).

Neste ponto, o Microsoft Entra ID requer que um administrador de locatário entre para concluir a solicitação. O administrador é solicitado a aprovar todas as permissões que você solicitou no scope parâmetro. Se você tiver usado um valor estático (), ele funcionará como o ponto de extremidade de consentimento de administrador v1.0 e solicitará consentimento para todos os escopos encontrados nas permissões necessárias (/.defaultusuário e aplicativo). Para solicitar permissões de aplicativo, você deve usar o /.default valor. Se você não quiser que os administradores vejam uma determinada permissão na tela de consentimento de administrador o tempo todo quando você usar /.default, a prática recomendada é não colocar a permissão na seção de permissões necessárias. Em vez disso, você pode usar o consentimento dinâmico para adicionar as permissões que deseja que estejam na tela de consentimento em tempo de execução, em vez de usar /.defaulto .

Resposta com êxito

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

http://localhost/myapp/permissions
    ?admin_consent=True
    &tenant=fa00d692-e9c7-4460-a743-29f2956fd429
    &scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
    &state=12345
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.
scope O conjunto de permissões às quais foi concedido acesso para o aplicativo.
admin_consent Será definido como True.

Aviso

Nunca use o valor de ID do locatário do tenant parâmetro para autenticar ou autorizar usuários. O valor da ID do locatário pode ser atualizado e enviado por agentes mal-intencionados para representar uma resposta ao seu aplicativo. Isso pode fazer com que seu aplicativo seja exposto a incidentes de segurança.

Resposta de erro

http://localhost/myapp/permissions
        ?admin_consent=True
        &error=consent_required
        &error_description=AADSTS65004%3a+The+resource+owner+or+authorization+server+denied+the+request.%0d%0aTrace+ID%3a+d320620c-3d56-42bc-bc45-4cdd85c41f00%0d%0aCorrelation+ID%3a+8478d534-5b2c-4325-8c2c-51395c342c89%0d%0aTimestamp%3a+2019-09-24+18%3a34%3a26Z
        &state=12345

Adicionando aos parâmetros vistos em uma resposta bem-sucedida, os parâmetros de erro são vistos como abaixo.

Parâmetro Description
error Uma cadeia de caracteres de código de erro que pode ser usada para classificar tipos de erros que ocorrem e 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.
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 para True indicar que essa resposta ocorreu em um fluxo de consentimento de administrador.

Próximos passos