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

Este artigo pode ajudá-lo, como desenvolvedor, a projetar sua estratégia de permissões de aplicativo para fornecer privilégios mínimos. Antes de continuar, consulte o artigo de proteção de API para aprender as práticas recomendadas para registro, permissões e acesso.

Vamos dar uma olhada em como uma API protegida pela plataforma de identidade da Microsoft usa a estrutura de consentimento de identidade da Microsoft. Usamos a API do Microsoft Graph como nosso exemplo porque ela faz o uso mais abrangente 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ão do Microsoft Graph aderem a um padrão simples resource.operation.constraint . 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 suporta estas restrições:

• All 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 seu aplicativo executar as operações em recursos que outros usuários compartilharam 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 Files permissions e só é válida para contas da Microsoft.
• Se você especificar Sem restrição, seu aplicativo só poderá executar as operações nos recursos que o usuário conectado possui.

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

Vamos examinar 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 relação a recursos específicos:

Permissão	String de exibição	Description
User.Read	Iniciar sessão e ler o perfil de utilizador	Permite que os usuários entrem no aplicativo e permite que o aplicativo leia o perfil dos usuários conectados. Ele também permite que o aplicativo leia informações básicas da empresa de usuários conectados.
User.ReadWrite	Acesso de leitura e gravação ao perfil do usuário	Permite que o aplicativo leia o perfil completo do usuário conectado. Ele também permite que o aplicativo atualize as informações de perfil do usuário conectado em seu nome.

User.Read e User.ReadWrite existem (ao contrário de uma única permissão como User.Access essa não existir) para que os aplicativos possam seguir o princípio Zero Trust de menor privilégio. 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.ReadWriteo . Portanto, um invasor não pode comprometer o aplicativo e usá-lo para alterar dados.

Observe que User.Read isso não apenas dá ao aplicativo acesso ao objeto de usuário. 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 permitir a leitura do perfil completo do usuário atual, permite que o aplicativo veja as informações básicas do objeto Organizations no Microsoft Graph.

Vejamos outra permissão:

Permissão	String de exibição	Description
User.ReadBasic.All	Ler os perfis básicos de todos os utilizadores	Permite que o aplicativo leia um conjunto básico de propriedades de perfil de outros usuários em sua organização em nome do usuário conectado. Inclui nome para exibição, nome próprio e familiar, endereço de e-mail, extensões abertas e foto. Permite que o aplicativo leia o perfil completo do usuário conectado.

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

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

Permissão	String de exibição	Description
User.Read.All	Leia os perfis completos de todos os utilizadores	Permite que o aplicativo leia o conjunto completo de propriedades de perfil, relatórios e gerentes de outros usuários em sua organização, em nome do usuário conectado.
User.ReadWrite.All	Ler e escrever os perfis completos de todos os utilizadores	Permite que o aplicativo leia e escreva o conjunto completo de propriedades de perfil, relatórios e gerentes de outros usuários em sua organização, em nome do usuário conectado. Também permite que o aplicativo crie e exclua usuários e redefina senhas de usuário em nome do usuário conectado.

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 Zero Trust de privilégios mínimos.

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

User.ReadWrite.All é uma poderosa gama de operação. Um aplicativo concedido 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, o aplicativo 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 usa 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 locatário em mente.

Permissões que requerem consentimento do administrador

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

Permissão	String de exibição	Description	Administrador?
User.Read	Iniciar sessão e ler o perfil de utilizador	Permite que os usuários entrem no aplicativo e permite que o aplicativo leia o perfil dos usuários conectados. Ele também permite que o aplicativo leia informações básicas da empresa de usuários conectados.	Não
User.ReadWrite	Acesso de leitura e gravação ao perfil do usuário	Permite que o aplicativo leia o perfil completo do usuário conectado. Ele também permite que o aplicativo atualize as informações de perfil do usuário conectado em seu nome.	Não
User.ReadBasic.All	Ler os perfis básicos de todos os utilizadores	Permite que o aplicativo leia um conjunto básico de propriedades de perfil de outros usuários em sua organização em nome do usuário conectado. Inclui nome para exibição, nome próprio e familiar, endereço de e-mail, extensões abertas e foto. Permite que o aplicativo leia o perfil completo do usuário conectado.	Não
User.Read.All	Leia os perfis completos de todos os utilizadores	Permite que o aplicativo leia o conjunto completo de propriedades de perfil, relatórios e gerentes de outros usuários em sua organização, em nome do usuário conectado.	Sim
User.ReadWrite.All	Ler e escrever os perfis completos de todos os utilizadores	Permite que o aplicativo leia e escreva o conjunto completo de propriedades de perfil, relatórios e gerentes de outros usuários em sua organização, em nome do usuário conectado. Também permite que o aplicativo crie e exclua usuários e redefina senhas de usuário em nome do usuário conectado.	Sim

Conforme demonstrado no artigo Solicitar permissões que exigem consentimento administrativo, os administradores de locatários podem anular os requisitos e designar qualquer ou todas as permissões de aplicativo em seu locatário como exigindo consentimento do administrador. Você é sábio para projetar seu aplicativo para lidar graciosamente quando não receber um token de sua solicitação. A falta de consentimento é uma das muitas razões pelas quais seu aplicativo pode não receber um token.

Próximos passos

• Chamar uma API de outra API ajuda você a garantir o Zero Trust quando você tem uma API que precisa chamar outra API e desenvolver seu aplicativo com segurança quando ele está trabalhando em nome de um usuário.
• Adquirir autorização para acessar recursos ajuda você a entender a melhor forma de garantir o Zero Trust ao adquirir permissões de acesso a recursos para seu aplicativo.
• Personalizar tokens descreve as informações que você pode receber nos tokens do Microsoft Entra. Ele explica como personalizar tokens para melhorar a flexibilidade e o controle e, ao mesmo tempo, aumentar a segurança de confiança zero do aplicativo com o menor privilégio.
• 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 e, ao mesmo tempo, aumentam a segurança de confiança zero do aplicativo com o menor privilégio.
• Solicitar permissões que exigem consentimento administrativo descreve a experiência de permissão e consentimento quando as permissões do aplicativo exigem consentimento administrativo.
• Neste Guia de início rápido: proteja uma API da Web com a plataforma de identidade da Microsoft, baixe e execute um exemplo de código que demonstra como proteger uma API da Web ASP.NET.
• Neste Tutorial - Transformar e proteger sua API no Gerenciamento de API do Azure, saiba como configurar políticas comuns para ocultar informações da pilha de tecnologia e URLs originais no corpo de resposta HTTP da API.
• As práticas recomendadas de autorização ajudam você a implementar os melhores modelos de autorização, permissão e consentimento para seus aplicativos.