Entendendo as permissões e consentimento do Microsoft Graph

  • 6 minutos

Para desenvolver um aplicativo de cliente que recupere dados do Microsoft 365, você precisa entender como as permissões e o consentimento funcionam no Microsoft Graph. Você deseja fazer as escolhas certas sobre quais dados seu aplicativo pode ou não acessar. Por exemplo, se quiser mostrar as próximas reuniões de um vendedor conectado, você desejará que seu aplicativo tenha permissão para acessar seus dados de calendário do Microsoft 365.

Os aplicativos exigempermissão para acessar recursos do Microsoft 365 específicos por meio do Microsoft Graph. Essas solicitações podem ser feitas antecipadamente (quando o aplicativo é registrado) ou dinamicamente (quando o aplicativo está em execução). Quando um aplicativo solicita permissão, um usuário ou administrador deve consentir à permissão antes de o Microsoft Graph autorizar as solicitações.

Há três conceitos principais a serem entendidos quando seu aplicativo precisa interagir com o Microsoft Graph:

  • Permissões ou escopos do Microsoft Graph
  • Tipo de permissão
  • Tokens de acesso

Permissões ou escopos do Microsoft Graph

As permissões do Microsoft Graph contêm escopos que controlam o acesso que seu aplicativo tem a recursos específicos, como usuários, emails e arquivos. Os escopos também controlam as operações que podem ser executadas nesses recursos. O padrão de exemplo a seguir define uma permissão para uma operação do Microsoft Graph para um recurso:

Resource-name.operation.constraint

Por exemplo, User.Read.All concede a um aplicativo a permissão para ler o perfil de todos os usuários em um diretório. Para ler o perfil de um usuário conectado, a permissão necessária é User.Read.

Tipo de permissão

Existem dois tipos de permissões no Microsoft Entra ID:

  • Seu aplicativo usa permissão delegada quando está fazendo uma chamada Microsoft Graph em nome do usuário. O usuário pode consentir com alguns escopos de permissão, como User.Read. Mas alguns escopos de permissão são altamente privilegiados e exigem o consentimento de um administrador. Um exemplo de um escopo de permissão altamente privilegiado é Channel.Delete.All, que exclui canais em qualquer equipe em nome do usuário conectado.

    O exemplo mais simples de um escopo de permissão delegado é User.Read, que é necessário para chamar o ponto de extremidade /me. No Microsoft Graph, todas as chamadas à API com /me usam o contexto do usuário conectado no momento.

  • A permissão de aplicativo não requer um usuário conectado no aplicativo. Geralmente, ele é usado quando um usuário não está presente, como em um processo em segundo plano ou para elevar a permissão. Um administrador concorda com a permissão com antecedência.

    Um exemplo de escopo de permissão de aplicativo é Calendars.ReadWrite, que permite que o aplicativo crie, leia, atualize e exclua eventos de todos os calendários sem um usuário conectado. Você não pode usar uma API /me para um escopo de permissão de aplicativo, porque não há nenhum usuário conectado para extrair essas informações.

Tokens de acesso

Depois que seu aplicativo solicitar permissão e um usuário ou administrador tiver consentido, o aplicativo poderá obter um token de acesso da plataforma de identidade da Microsoft. Você pode pensar no token de acesso como um tíquete de filme que você dá a um atendedor para provar que pagou para ver o filme. Seu aplicativo fornece um token de acesso ao Microsoft Graph para provar que ele tem permissão para acessar dados do Microsoft 365.

O Microsoft Graph requer um token de acesso válido no cabeçalho HTTP de cada solicitação. Ele é passado no cabeçalho de autorização de cada solicitação HTTP com a palavra "Portador" e um espaço antes dela. Este é um lembrete de que, como um tíquete de filme, o portador pode usar o token de acesso. Ou seja, qualquer pessoa que tenha o tíquete pode entrar sem provar sua identidade. Por esse motivo, o Microsoft Graph requer criptografia HTTPS em todas as solicitações. Além disso, como ingressos de cinema, os tokens de acesso são válidos por apenas um curto período, normalmente uma hora.

Veja um exemplo da aparência de um cabeçalho de autorização para uma solicitação do Microsoft Graph:

GET https://graph.microsoft.com/v1.0/me/ HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer EwAoA8l6BAAU ... 7PqHGsykYj7A0XqHCjbKKgWSkcAg==