Compartilhar via

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

  • Artigo

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:

Permissão Cadeia de Exibição Descrição
User.Read Entrada e leitura de perfil do usuário Permite que os usuários entrem no aplicativo e permite que o aplicativo leia o perfil dos usuários conectados. 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 do perfil do usuário conectado no seu nome.

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:

Permissão Cadeia de Exibição Descrição
User.ReadBasic.All Ler os perfis básicos de todos os usuários Permite que o aplicativo leia um conjunto básico de propriedades de perfil de outros usuários na sua organização em nome do usuário conectado. Inclui nome de exibição, nome e sobrenome, endereço de email, extensões abertas e foto. Permite que o aplicativo leia o perfil completo do usuário conectado.

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:

Permissão Cadeia de Exibição Descrição
User.Read.All Ler os perfis completos de todos os usuários Permite que o aplicativo leia o conjunto completo de propriedades de perfil, relatórios e gerentes de outros usuários na sua organização, em nome do usuário conectado.
User.ReadWrite.All Ler e escrever perfis completos de todos os usuários Permite que o aplicativo leia e grave o conjunto completo de propriedades de perfil, relatórios e gerentes de outros usuários na 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 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.

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:

Permissão Cadeia de Exibição Descrição Admin?
User.Read Entrada e leitura de perfil do usuário Permite que os usuários entrem no aplicativo e permite que o aplicativo leia o perfil dos usuários conectados. 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 do perfil do usuário conectado no seu nome. Não
User.ReadBasic.All Ler os perfis básicos de todos os usuários Permite que o aplicativo leia um conjunto básico de propriedades de perfil de outros usuários na sua organização em nome do usuário conectado. Inclui nome de exibição, nome e sobrenome, endereço de email, extensões abertas e foto. Permite que o aplicativo leia o perfil completo do usuário conectado. Não
User.Read.All Ler os perfis completos de todos os usuários Permite que o aplicativo leia o conjunto completo de propriedades de perfil, relatórios e gerentes de outros usuários na sua organização, em nome do usuário conectado. Sim
User.ReadWrite.All Ler e escrever perfis completos de todos os usuários Permite que o aplicativo leia e grave o conjunto completo de propriedades de perfil, relatórios e gerentes de outros usuários na 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 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