Compartilhar via

Consentimento do administrador na plataforma Microsoft Identity

Algumas permissões exigem consentimento de um administrador antes que possam ser concedidas em um locatário. Você também pode usar o ponto de extremidade de consentimento do administrador para conceder permissões a um locatário inteiro.

Normalmente, quando você cria um aplicativo que usa o ponto de extremidade de 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. Essa página pode fazer parte do fluxo de inscrição do aplicativo, fazer parte das configurações do aplicativo ou pode ser um fluxo de "conexão" dedicado. Em muitos casos, faz mais sentido o aplicativo mostrar essa exibição de "conexão" somente após o usuário fazer logon com uma conta da Microsoft corporativa ou de estudante.

Ao conectar o usuário em seu aplicativo, você pode identificar a organização à qual o administrador pertence antes de pedir que ele aprove as permissões necessárias. Embora não seja estritamente necessário, isso 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 você estiver pronto para solicitar permissões de administrador da empresa, redirecione o usuário para o ponto de extremidade de consentimento do administrador da plataforma de identidade da Microsoft.

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent
        ?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
        &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 Descrição
tenant Obrigatório O locatário do diretório para o qual você deseja solicitar permissão. Pode ser fornecido no GUID ou no formato de nome amigável OU referenciado genericamente como organizations visto no exemplo. Não use "comum", pois as contas pessoais não podem fornecer consentimento do administrador, exceto no contexto de um locatário. Para garantir melhor compatibilidade com as contas pessoais que gerenciam locatários, use a ID do locatário se possível.
client_id Obrigatório A ID do aplicativo (cliente) que a experiência centro de administração do Microsoft Entra – Registros de aplicativo atribui ao seu aplicativo.
redirect_uri Obrigatório O URI de redirecionamento para onde você deseja que a resposta seja enviada para ser processada pelo seu aplicativo. Ela deve corresponder exatamente a um redirecionamento de URIs que você registrou no portal de registro de aplicativo.
state Recomendado Um valor incluído na solicitação que também será retornado na resposta do token. Pode ser uma cadeia de caracteres de qualquer conteúdo desejado. Use o estado 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.
scope Obrigató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, a ID do Microsoft Entra requer um administrador de locatários para entrar e concluir a solicitação. O administrador é solicitado a aprovar todas as permissões solicitadas no scope parâmetro. Se você tiver usado um valor estático (/.default), ele funcionará como o ponto de extremidade de consentimento do administrador v1.0 e solicitará consentimento para todos os escopos encontrados nas permissões necessárias (usuá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 do administrador o tempo todo quando você usa /.default, a melhor prática é 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 estar na tela de consentimento em tempo de execução, em vez de usar /.default.

Resposta bem-sucedida

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=aaaabbbb-0000-cccc-1111-dddd2222eeee
    &scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
    &state=12345
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 que também será retornado 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.
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 da 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 maus atores 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+0000aaaa-11bb-cccc-dd22-eeeeee333333%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 Descrição
error Uma cadeia de caracteres de códigos de erro que pode ser usada para classificar tipos de erro que ocorrem e pode ser usada para responder aos 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 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 Será definido para True indicar que essa resposta ocorreu em um fluxo de consentimento do administrador.

Próximas etapas