Exemplo de API protegida pela estrutura de consentimento de identidade da Microsoft

Este artigo pode ajudar você, como desenvolvedor, a projetar sua estratégia de permissões de aplicativos para fornecer privilégios mínimos. Antes de continuar, consulte o artigo Proteção da API para conhecer as melhores práticas de registro, permissões e acesso.

Vamos dar uma olhada em como uma API protegida pela plataforma de identidade da Microsoft utiliza a estrutura de consentimento de identidade da Microsoft. Usamos a API do Microsoft Graph como exemplo porque ela faz o uso mais amplo da estrutura de consentimento da plataforma de identidade da Microsoft.

Convenção de nomenclatura para nomes de permissão

A equipe do Microsoft Graph criou uma convenção de nomenclatura para nomes de permissão para facilitar a conexão da permissão ao acesso ao recurso que a permissão permite. Os nomes de permissões do Microsoft Graph seguem um padrão resource.operation.constraint simples. As duas operações principais são Read e ReadWrite (que inclui atualização e exclusão).

O elemento de restrição afeta o grau de acesso que seu aplicativo tem dentro do diretório. O Microsoft Graph oferece suporte a estas restrições:

• Tudo concede permissão para seu aplicativo executar as operações em todos os recursos do tipo especificado em um diretório.
• Compartilhado concede permissão para que seu aplicativo execute as operações em recursos compartilhados por outros usuários com o usuário conectado.
• AppFolder concede permissão para seu aplicativo ler e gravar arquivos em uma pasta dedicada no OneDrive. Essa restrição é exposta somente no objeto de permissões de Arquivos e só é válida para contas da Microsoft.
• Se você especificar Sem restrição, o aplicativo apenas poderá executar as operações nos recursos que o usuário conectado possui.

Acesso e operações em relação a recursos específicos

Vejamos algumas permissões, ou escopos, para o objeto de usuário no Microsoft Graph para ver como os designers de API da Microsoft habilitaram acesso e operações específicos em recursos específicos:

User.Read e User.ReadWrite existem (em oposição a uma única permissão como User.Access que não existe) para que os aplicativos possam seguir o princípio de Confiança Zero de privilégio mínimo. Se o desenvolvedor não tiver um requisito e um código para atualizar o perfil do usuário, o aplicativo não solicitará User.ReadWrite. Portanto, um invasor não pode comprometer o aplicativo e usá-lo para alterar dados.

Observe que User.Read não concede apenas acesso ao objeto de usuário para o aplicativo. Cada permissão representa um intervalo específico de operação. É importante que os desenvolvedores e administradores leiam a descrição da permissão para ver exatamente o que qualquer permissão específica permite. User.Read, além de habilitar a leitura do perfil completo do usuário atual, permite que o aplicativo veja as informações básicas do objeto Organizações no Microsoft Graph.

Vejamos outra permissão:

A faixa de operação que User.ReadBasic.All começa com tudo o que User.Read faz. Além disso, você pode acessar o nome de exibição, o nome e o sobrenome, o endereço de email, a foto e as extensões abertas de outros usuários da organização. O intervalo específico de operação permite que os aplicativos tenham uma interface do usuário de seletor de pessoas agradável e é um exemplo dos designers de API que usam uma permissão para habilitar um intervalo específico de operação.

Vejamos mais algumas permissões no objeto de usuário do Microsoft Graph:

Tal como acontece com User.Read e User.ReadWrite, User.Read.All e User.ReadWrite.All são permissões distintas que permitem que um aplicativo siga o princípio de Confiança Zero de privilégio mínimo.

User.Read.All é interessante, porque cada usuário na organização tem esse recurso (por exemplo, abrir o Outlook, subir e descer em uma cadeia de relatórios). Você, como indivíduo, pode ver o perfil de usuário completo de todos os outros usuários na sua organização. No entanto, os designers da API do Microsoft Graph decidiram que somente os administradores devem permitir que um aplicativo execute a mesma operação, pois User.Read.All inclui a hierarquia organizacional do locatário. Se um ator mal-intencionado acessasse essas informações, ele poderia montar um ataque de phishing direcionado em que o e-mail de phishing veio do gerente de uma pessoa ou do gerente de seu gerente.

User.ReadWrite.All é uma poderosa faixa de operação. Um aplicativo que recebeu essa permissão pode atualizar, ou até mesmo excluir, todos os usuários no locatário. Como uma permissão delegada, quando um usuário está na frente do aplicativo, este pode fazer apenas o que o usuário atual pode fazer. Os usuários comuns não podem atualizar ou excluir outros usuários, independentemente das permissões do aplicativo. No entanto, quando um administrador de locatário utiliza o aplicativo, ele pode executar essas operações. Ao decidir conceder ou negar essa permissão, você deve avaliar seu aplicativo com um usuário administrador de locatário em mente.

Permissões que exigem consentimento do administrador

Devido ao poder de User.Read.All e User.ReadWrite.All, os designers da API do Microsoft Graph designaram essas permissões como exigindo consentimento do administrador. Vamos adicionar uma coluna Administrador? à nossa tabela de permissões para indicar quando a permissão requer o consentimento do administrador:

Conforme demonstrado no artigo Solicitar permissões que exigem consentimento administrativo, os administradores de locatários podem ignorar os requisitos e designar qualquer ou todas as permissões de aplicativos em seus locatários como exigindo consentimento administrativo. Você é sábio para projetar seu aplicativo para lidar normalmente quando você não recebe um token de sua solicitação. A falta de consentimento é um dos muitos motivos pelos quais seu aplicativo pode não receber um token.

Próximas etapas

• Chamar uma API de outra API ajuda você a garantir Confiança Zero quando você tem uma API que precisa chamar outra API e desenvolver seu aplicativo com segurança quando ele estiver trabalhando em nome de um usuário.
• O artigo Adquirir autorização para acessar recursos ajuda você a entender a melhor forma de garantir Confiança Zero ao adquirir permissões de acesso a recursos para o seu aplicativo.
• Personalizar tokens descreve as informações que você pode receber nos tokens do Microsoft Entra. Esse artigo explica como personalizar tokens para melhorar a flexibilidade e o controle, aumentando a segurança de confiança zero do aplicativo com privilégios mínimos.
• Configurar declarações de grupo e funções de aplicativo em tokens mostra como configurar seus aplicativos com definições de função de aplicativo e atribuir grupos de segurança a funções de aplicativo. Esses métodos ajudam a melhorar a flexibilidade e o controle, aumentando a segurança de confiança zero do aplicativo com privilégios mínimos.
• O artigo Solicitar permissões que requerem consentimento administrativo descreve a experiência de permissão e consentimento quando as permissões de aplicativo requerem consentimento administrativo.
• Neste Guia de início rápido: proteger uma API Web com a plataforma de identidade da Microsoft, baixe e execute um exemplo de código que demonstra como proteger uma API Web ASP.NET.
• Neste Tutorial: transformar e proteger sua API no Gerenciamento de APIs do Azure, aprenda a configurar políticas comuns para ocultar informações de pilha de tecnologia e URLs originais no corpo de resposta HTTP da API.
• O artigo Práticas recomendadas de autorização ajuda você a implementar os melhores modelos de autorização, permissão e consentimento para aplicativos.