Noções básicas de autenticação e autorização
O Microsoft Graph é uma API Web protegida para acessar dados em serviços de nuvem da Microsoft, como Microsoft Entra ID e Microsoft 365. Ele é protegido pelo plataforma de identidade da Microsoft, que usa tokens de acesso OAuth para verificar se um aplicativo está autorizado a chamar o Microsoft Graph.
Este artigo fornece uma visão geral da plataforma de identidade da Microsoft, tokens de acesso e como seu aplicativo pode obter tokens de acesso. Para obter mais informações sobre a plataforma de identidade da Microsoft, confira O que é a plataforma de identidade da Microsoft?. Se você souber como integrar um aplicativo ao plataforma de identidade da Microsoft para obter tokens, consulte o plataforma de identidade da Microsoft exemplos de código para obter informações e exemplos específicos do Microsoft Graph.
Registrar o aplicativo
Antes que seu aplicativo possa obter um token de acesso do plataforma de identidade da Microsoft, ele deve ser registrado no centro de administração do Microsoft Entra. O registro integra o aplicativo com a Microsoft Identity Platform e estabelece as informações que ele usa para acessar os tokens, incluindo:
- 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 do plataforma de identidade da Microsoft. (Para aplicativos nativos e móveis, o URI é atribuído pelo plataforma de identidade da Microsoft.)
- Segredo do cliente: uma senha que seu aplicativo usa para autenticar com o plataforma de identidade da Microsoft. Opcionalmente, você pode usar um certificado ou uma credencial de identidade federada. Essa propriedade não é necessária para clientes públicos, como aplicativos nativos, móveis e de página única.
Para obter mais informações, consulte Registrar um aplicativo com o plataforma de identidade da Microsoft.
Cenários de acesso
O método que um aplicativo usa para autenticar com o plataforma de identidade da Microsoft depende de como você deseja que o aplicativo acesse os dados. Esse acesso pode ser de duas maneiras, conforme ilustrado na imagem a seguir.
- Acesso delegado, um aplicativo agindo em nome de um usuário conectado.
- Acesso somente aplicativo, um aplicativo agindo com sua própria identidade.
Acesso delegado (acesso em nome de um usuário)
Nesse cenário de acesso, um usuário entrou em um aplicativo cliente e o aplicativo cliente chama o Microsoft Graph em nome do usuário. O cliente e o usuário devem ser autorizados a fazer a solicitação.
O acesso delegado requer permissões delegadas, também conhecidas como escopos. Escopos são permissões que são expostas por um determinado recurso e representam as operações que um aplicativo pode executar em nome de um usuário.
Como o aplicativo e o usuário devem estar autorizados a fazer a solicitação, o recurso concede ao aplicativo cliente as permissões delegadas, para que o aplicativo cliente acesse dados em nome do usuário especificado. Para o usuário, as ações que podem ser executadas no recurso dependem das permissões que eles têm para acessar o recurso. Por exemplo, o usuário pode ser o proprietário do recurso ou pode receber uma função específica por meio de um RBAC (sistema de controle de acesso baseado em função), como Microsoft Entra RBAC.
Observação
Pontos de extremidade e APIs com o alias /me operam apenas no usuário conectado e, portanto, são chamados em cenários de acesso delegado.
Acesso somente aplicativo (acesso sem um usuário)
Nesse cenário de acesso, o aplicativo pode interagir com dados por conta própria, sem um usuário conectado. O acesso somente aplicativo é usado em cenários como automação e backup e é usado principalmente por aplicativos executados como serviços em segundo plano ou daemons. É adequado quando é indesejável ter um usuário conectado ou quando os dados necessários não podem ser escopo para um único usuário.
Os aplicativos obtêm privilégios para chamar o Microsoft Graph com sua própria identidade por meio de uma das seguintes maneiras:
- Quando o aplicativo recebe permissões de aplicativo, também chamado de funções de aplicativo
- Quando o aplicativo é atribuído a propriedade do recurso que ele pretende gerenciar
Observação
Um aplicativo também pode obter privilégios por meio de permissões concedidas por um sistema de controle de acesso baseado em função, como Microsoft Entra RBAC.
Permissões do Microsoft Graph
O Microsoft Graph expõe permissões granulares que controlam o acesso que os aplicativos têm aos recursos do Microsoft Graph, como usuários, grupos e emails. 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.
O Microsoft Graph expõe dois tipos de permissões para os cenários de acesso com suporte:
- Permissões delegadas: também chamados 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.
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é-autenticado para o aplicativo por um administrador.
- Pode ser consentido diretamente pelo usuário.
- Se não for pré-autenticado, poderá exigir privilégios de administrador para conceder o 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.
Observação
Como melhor prática, solicite as permissões com menos privilégios de que seu aplicativo precisa para acessar os dados e funcionar corretamente. Solicitar permissões com mais do que os privilégios necessários é uma prática de segurança ruim, o que pode fazer com que os usuários evitem o consentimento e afetem o uso do aplicativo.
Para obter mais informações sobre as permissões do Microsoft Graph e como usá-las, confira a visão geral das permissões do Microsoft Graph.
Tokens de acesso
Um aplicativo faz uma solicitação de autenticação ao plataforma de identidade da Microsoft para obter tokens de acesso que ele usa para chamar uma API, como o Microsoft Graph. Os tokens de acesso que o plataforma de identidade da Microsoft problemas contêm declarações que são detalhes sobre o aplicativo e em cenários de acesso delegado, o usuário. As APIs Web protegidas pelo plataforma de identidade da Microsoft, como o Microsoft Graph, usam as declarações para validar o chamador e garantir que o chamador tenha os privilégios adequados para executar a operação que está solicitando. O chamador deve tratar tokens de acesso como cadeias de caracteres opacos porque o conteúdo do token destina-se apenas à API. Ao chamar o Microsoft Graph, sempre proteja tokens de acesso transmitindo-os por um canal seguro que usa o protocolo TLS (segurança de camada de transporte).
O exemplo a seguir mostra um token de acesso à plataforma de identidade da Microsoft:
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt
Os tokens de acesso são um tipo de token de segurança que o plataforma de identidade da Microsoft fornece. Eles são de curta duração, mas com tempo de vida padrão variável.
Para chamar o Microsoft Graph, o aplicativo faz uma solicitação de autorização anexando o token de acesso como um token Bearer ao cabeçalho 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==
Obter um token de acesso
Recomendamos que você use bibliotecas de autenticação para gerenciar suas interações de token com o plataforma de identidade da Microsoft. As bibliotecas de autenticação abstraem muitos detalhes do protocolo, como validação, manipulação de cookie, cache de token e manutenção de conexões seguras, o que permite que você concentre seu desenvolvimento na funcionalidade do aplicativo. A Microsoft publica bibliotecas de clientes de software livre e middleware de servidor.
Sobre o ponto de extremidade da plataforma de identidade para desenvolvedores da Microsoft:
- Bibliotecas de clientes MSAL (Biblioteca de Autenticação da Microsoft) 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 à produção e, no caso de alterações de interrupção serem introduzidas, a Microsoft garante um caminho para a atualização.
- O middleware do servidor da Microsoft está disponível para o .NET core e ASP.NET (OWIN OpenID Connect e OAuth) e para Node.js (plataforma de identidade da Microsoft Passport.js).
- O 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 clientes da Microsoft, middleware do microsoft server e bibliotecas de terceiros compatíveis, consulte plataforma de identidade da Microsoft documentação.
Você não precisa usar uma biblioteca de autenticação para obter um token de acesso. Para saber mais sobre como usar diretamente os pontos de extremidade plataforma de identidade da Microsoft sem a ajuda de uma biblioteca de autenticação, confira os seguintes artigos: