Noções básicas de autenticação e autorização

O Microsoft Graph é um gateway de API protegido para acessar dados nos serviços de nuvem da Microsoft, como o Microsoft Entra ID e o Microsoft 365. Ele é protegido pela plataforma de identidade da Microsoft, que autoriza e verifica se um aplicativo está autorizado a chamar o Microsoft Graph.

Este artigo fornece uma visão geral dos requisitos para que um aplicativo seja autorizado a acessar dados por meio de qualquer API do Graph. Se você já estiver familiarizado com o funcionamento da autenticação e da autorização, explore exemplos de código da plataforma de identidade da Microsoft ou tutoriais do Microsoft Graph para aplicativos criados usando diferentes SDKs do Microsoft Graph e que chamam APIs do Microsoft Graph.

Registrar o aplicativo

Antes que seu aplicativo possa ser autorizado a chamar qualquer API do Graph, a plataforma de identidade da Microsoft deve primeiro estar ciente disso. Esse processo não envolve o upload do código do aplicativo para a plataforma. Em vez disso, envolve registrar o aplicativo no centro de administração do Microsoft Entra para estabelecer suas informações de configuração, incluindo os seguintes parâmetros principais:

• ID do aplicativo: um identificador exclusivo atribuído pela Microsoft Identity Platform.
• URI/URL de redirecionamento: um ou mais pontos de extremidade nos quais seu aplicativo recebe respostas da plataforma de identidade da Microsoft. A plataforma de identidade da Microsoft atribui o URI a aplicativos nativos e móveis.
• Credencial: pode ser um segredo do cliente (uma cadeia de caracteres ou senha), um certificado ou uma credencial de identidade federada. Seu aplicativo usa a credencial para autenticar com a plataforma de identidade da Microsoft. Essa propriedade só é necessária para aplicativos cliente confidenciais; Ele não é necessário para clientes públicos como aplicativos nativos, móveis e de página única. Para obter mais informações, consulte Cliente público e aplicativos cliente confidenciais.

Em seguida, você adiciona essas informações de volta ao código uma vez e o aplicativo usa as informações sempre que precisar provar sua identidade durante um processo de autenticação, antes de ser autorizado a acessar seus dados.

Para obter mais informações, consulte Registrar um aplicativo na plataforma de identidade da Microsoft.

Cenários de acesso

Um aplicativo pode acessar dados de duas maneiras, conforme ilustrado na imagem a seguir.

• Acesso delegado, um aplicativo agindo em nome de um usuário conectado.
• Acesso somente app, um app agindo com sua própria identidade.

Acesso delegado (acesso em nome de um usuário)

Nesse cenário de acesso, um usuário entra em um aplicativo cliente que chama o Microsoft Graph em seu nome. Tanto o aplicativo cliente quanto o usuário devem ser autorizados a fazer a solicitação.

Para que o aplicativo cliente seja autorizado a acessar os dados em nome do usuário conectado, ele deve ter as permissões necessárias, que ele recebe por meio de uma combinação de dois fatores:

• Permissões delegadas, também conhecidas como escopos: as permissões expostas pelo Microsoft Graph e que representam as operações que o aplicativo pode executar em nome do usuário conectado. O aplicativo tem permissão para executar uma operação em nome do usuário conectado, mas não de outro.
• Permissões de usuário: as permissões que o usuário conectado tem para o recurso. O usuário pode ser o proprietário do recurso, o recurso pode ser compartilhado com eles ou pode receber permissões por meio de um RBAC (sistema de controle de acesso baseado em função), como o Microsoft Entra RBAC.

Cenário de exemplo: acesso delegado no Microsoft Graph

O https://graph.microsoft.com/v1.0/me ponto de extremidade é o ponto de acesso às informações do usuário conectado, que representa um recurso protegido pela plataforma de identidade da Microsoft. Para acesso delegado, os dois fatores são atendidos da seguinte forma:

• O aplicativo deve receber uma permissão delegada do Microsoft Graph com suporte, por exemplo, a permissão delegada User.Read , em nome do usuário conectado.
• O usuário conectado neste cenário é o proprietário dos dados.

Acesso somente aplicativo (acesso sem um usuário)

Nesse cenário de acesso, o aplicativo pode interagir com os dados por conta própria, sem um usuário conectado. O acesso somente ao aplicativo é usado em cenários como automação e backup e é usado principalmente por aplicativos executados como serviços em segundo plano ou daemons. Ela é adequada quando é indesejável que um usuário esteja conectado ou quando os dados obrigatórios não podem ser delimitados a um único usuário.

Para que um aplicativo cliente seja autorizado a acessar os dados com sua própria identidade, ele deve ter as permissões necessárias, que ele recebe por meio de uma das seguintes maneiras:

• O aplicativo recebe permissões de aplicativo Microsoft Graph com suporte, também chamadas de funções de aplicativo
• O aplicativo recebe a propriedade do recurso que pretende gerenciar

Cenário de exemplo: Acesso somente aplicativo no Microsoft Graph

O https://graph.microsoft.com/v1.0/users/delta ponto de extremidade permite pesquisar alterações nos dados do usuário. No acesso somente ao aplicativo, o aplicativo deve receber uma permissão com suporte, por exemplo, a permissão do aplicativo User.Read.All do Microsoft Graph para ter permissão para consultar e receber com êxito alterações nos dados do usuário.

Permissões do Microsoft Graph

Conforme mencionado anteriormente, um aplicativo deve ter permissões para acessar os dados que deseja acessar, independentemente do cenário de acesso.

O Microsoft Graph expõe permissões granulares que controlam o acesso aos recursos do Microsoft Graph, como usuários, grupos e email. Dois tipos de permissões estão disponíveis para os cenários de acesso com suporte:

• Permissões delegadas: também chamadas de escopos, permitem que o aplicativo atue em nome do usuário conectado.
• Permissões de aplicativo: também chamadas de funções de aplicativo, permitem que o aplicativo acesse dados por conta própria, sem um usuário conectado.

Como desenvolvedor, você decide quais permissões do Microsoft Graph solicitar para seu aplicativo com base no cenário de acesso e nas operações que deseja executar. Quando um usuário entra em um aplicativo, o aplicativo deve especificar as permissões necessárias para ser incluído no token de acesso. Estas permissões:

• Pode ser pré-autorizado para o aplicativo por um administrador.
• Pode ser consentido diretamente pelo usuário.
• Se não for pré-autorizado, requer privilégios de administrador para conceder consentimento. Por exemplo, para permissões com um impacto de segurança potencial maior.

Para obter mais informações sobre permissões e consentimento, consulte Introdução a permissões e consentimento.

Para obter mais informações sobre as permissões do Microsoft Graph e como usá-las, consulte a Visão geral das permissões do Microsoft Graph.

Tokens de acesso

Para acessar um recurso protegido, um aplicativo deve provar que está autorizado a fazer isso enviando um token de acesso válido. O aplicativo obtém esse token de acesso quando faz uma solicitação de autenticação para a plataforma de identidade da Microsoft, que por sua vez usa o token de acesso para verificar se o aplicativo está autorizado a chamar o Microsoft Graph.

Tokens de acesso que a plataforma de identidade da Microsoft emite declarações que são detalhes sobre o aplicativo e, em cenários de acesso delegado, o usuário conectado. APIs Web, como o Microsoft Graph, protegidas pela plataforma de identidade da Microsoft, usam as declarações para validar o chamador e garantir que o chamador esteja autorizado a executar a operação que está solicitando. Para cenários de acesso delegado, as permissões do usuário de chamada e do aplicativo fazem parte das declarações. Para cenários de aplicativo, as permissões do aplicativo fazem parte das declarações. Para obter mais informações sobre as partes que constituem tokens de acesso, consulte Referência de declarações de token de acesso.

Para chamar o Microsoft Graph, o aplicativo faz uma solicitação de autorização anexando o token de acesso como um token de Portador ao cabeçalho de Autorização em uma solicitação HTTP. Por exemplo, veja uma chamada que retorna as informações de perfil do usuário conectado (o token de acesso foi reduzido para facilitar a leitura):

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

Para saber mais sobre os tokens de acesso da plataforma de identidade da Microsoft, confira Tokens de ID na plataforma de identidade da Microsoft.

Obter um token de acesso

Recomendamos que você use bibliotecas de autenticação para gerenciar suas interações simbólicas com a plataforma de identidade da Microsoft. As bibliotecas de autenticação abstraem muitos detalhes do protocolo, como validação, tratamento de cookies, cache de token e manutenção de conexões seguras, que permitem que você concentre seu desenvolvimento na funcionalidade do seu aplicativo. A Microsoft publica bibliotecas de cliente de software livre e middleware de servidor.

Sobre o ponto de extremidade da plataforma de identidade para desenvolvedores da Microsoft:

• As bibliotecas de cliente da Biblioteca de Autenticação da Microsoft (MSAL) estão disponíveis para várias estruturas, incluindo para .NET, JavaScript, Android e iOS. Todas as plataformas estão em versão prévia com suporte de produção e, caso alterações significativas sejam introduzidas, a Microsoft garante um caminho para atualização.
• O middleware de servidor da Microsoft está disponível para .NET Core e ASP.NET (OWIN, OpenID, Connect e OAuth) e para Node.js (plataforma de identidade da Microsoft Passport.js).
• A plataforma de identidade da Microsoft também é compatível com muitas bibliotecas de autenticação de terceiros.

Para obter uma lista completa de bibliotecas de cliente da Microsoft, middleware de servidor da Microsoft e bibliotecas de terceiros compatíveis, consulte a documentação da plataforma de identidade da Microsoft.

Como alternativa, você pode usar os pontos de extremidade da plataforma de identidade da Microsoft diretamente, sem a ajuda de uma biblioteca de autenticação. Para saber mais, confira os seguintes artigos:

• Obter acesso em nome de um usuário
• Obter acesso sem um usuário

Conteúdo relacionado

• Documentação da plataforma de identidade da Microsoft
• Visão geral das permissões do Microsoft Graph
• Tutoriais do Microsoft Graph