Noções básicas de autenticação e autorização
O Microsoft Graph é uma API Web protegida para aceder a dados em serviços cloud da Microsoft, como o Microsoft Entra ID e o Microsoft 365. Está protegido pelo plataforma de identidade da Microsoft, que utiliza tokens de acesso OAuth para verificar se uma aplicação está autorizada 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 souber como integrar uma aplicação com o plataforma de identidade da Microsoft para obter tokens, veja o plataforma de identidade da Microsoft exemplos de código para obter informações e exemplos específicos do Microsoft Graph.
Registrar o aplicativo
Para que a sua aplicação possa obter um token de acesso a partir do plataforma de identidade da Microsoft, este tem de estar registado 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 finais nos quais a sua aplicação recebe respostas do plataforma de identidade da Microsoft. (Para aplicações nativas e móveis, o URI é atribuído pelo plataforma de identidade da Microsoft.)
- Segredo do cliente: uma palavra-passe que a sua aplicação utiliza para autenticar com o plataforma de identidade da Microsoft. Opcionalmente, pode utilizar um certificado ou uma credencial de identidade federada. Esta propriedade não é necessária para clientes públicos, como aplicações nativas, móveis e de página única.
Para obter mais informações, veja Registar uma aplicação no plataforma de identidade da Microsoft.
Cenários de acesso
O método que uma aplicação utiliza para autenticar com o plataforma de identidade da Microsoft depende de como pretende que a aplicação aceda aos dados. Este acesso pode ser de uma de duas formas, conforme ilustrado na imagem seguinte.
- Acesso delegado, uma aplicação a agir em nome de um utilizador com sessão iniciada.
- Acesso apenas à aplicação, uma aplicação a agir com a sua própria identidade.
Acesso delegado (acesso em nome de um utilizador)
Neste cenário de acesso, um utilizador iniciou sessão numa aplicação cliente e a aplicação cliente chama o Microsoft Graph em nome do utilizador. Tanto o cliente como o utilizador têm de estar autorizados a fazer o pedido.
O acesso delegado requer permissões delegadas, também referidas como âmbitos. Os âmbitos são permissões que são expostas por um determinado recurso e representam as operações que uma aplicação pode realizar em nome de um utilizador.
Uma vez que a aplicação e o utilizador têm de estar autorizados a fazer o pedido, o recurso concede à aplicação cliente as permissões delegadas para que a aplicação cliente aceda aos dados em nome do utilizador especificado. Para o utilizador, as ações que podem realizar no recurso dependem das permissões que têm para aceder ao recurso. Por exemplo, o utilizador pode ser o proprietário do recurso ou pode ser-lhe atribuída uma função específica através de um sistema de controlo de acesso baseado em funções (RBAC), como Microsoft Entra RBAC.
Observação
Os pontos finais e as APIs com o alias /me operam apenas no utilizador com sessão iniciada e, por conseguinte, são chamados em cenários de acesso delegado.
Acesso apenas à aplicação (acesso sem um utilizador)
Neste cenário de acesso, a aplicação pode interagir com os dados por si só, sem um utilizador com sessão iniciada. O acesso apenas à aplicação é utilizado em cenários como automatização e cópia de segurança e é utilizado principalmente por aplicações que são executadas como serviços em segundo plano ou daemons. É adequado quando é indesejável ter um utilizador com sessão iniciada ou quando os dados necessários não podem ser confinados a um único utilizador.
As aplicações obtêm privilégios para chamar o Microsoft Graph com a sua própria identidade através de uma das seguintes formas:
- Quando a aplicação tem permissões de aplicação atribuídas, também denominadas funções de aplicação
- Quando é atribuída à aplicação a propriedade do recurso que pretende gerir
Observação
Uma aplicação também pode obter privilégios através de permissões concedidas por um sistema de controlo de acesso baseado em funções, como Microsoft Entra RBAC.
Permissões do Microsoft Graph
O Microsoft Graph expõe permissões granulares que controlam o acesso que as aplicações têm aos recursos do Microsoft Graph, como utilizadores, grupos e correio. Enquanto programador, decide que permissões do Microsoft Graph pedir para a sua aplicação com base no cenário de acesso e nas operações que pretende realizar.
O Microsoft Graph expõe dois tipos de permissões para os cenários de acesso suportados:
- Permissões delegadas: também denominadas âmbitos, permitem que a aplicação atue em nome do utilizador com sessão iniciada.
- Permissões da aplicação: também denominadas funções de aplicação, permitem que a aplicação aceda aos dados por si só, sem um utilizador com sessão iniciada.
Quando um utilizador inicia sessão numa aplicação, a aplicação tem de especificar as permissões de que precisa de ser incluída no token de acesso. Estas permissões:
- Pode ser pré-autorizado para a aplicação por um administrador.
- Pode ser consentido diretamente pelo utilizador.
- Se não for pré-autenticado, pode exigir privilégios de administrador para conceder consentimento. Por exemplo, para permissões com um maior impacto de segurança potencial.
Para obter mais informações sobre permissões e consentimento, consulte Introdução às 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 utilizá-las, consulte a Descrição geral das permissões do Microsoft Graph.
Tokens de acesso
Uma aplicação faz um pedido de autenticação ao plataforma de identidade da Microsoft para obter tokens de acesso que utiliza para chamar uma API, como o Microsoft Graph. Os tokens de acesso que o plataforma de identidade da Microsoft problemas contêm afirmações que são detalhes sobre a aplicação e, em cenários de acesso delegado, o utilizador. As APIs Web protegidas pelo plataforma de identidade da Microsoft, como o Microsoft Graph, utilizam as afirmações para validar o autor da chamada e para garantir que o autor da chamada tem os privilégios adequados para executar a operação que está a pedir. 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).
Os tokens de acesso são uma espécie de token de segurança fornecido pelo plataforma de identidade da Microsoft. São de curta duração, mas com durações predefinidas variáveis.
Para chamar o Microsoft Graph, a aplicação faz um pedido de autorização ao anexar o token de acesso como um token de Portador ao cabeçalho Autorização num pedido 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 plataforma de identidade da Microsoft tokens de acesso, veja Tokens de ID no plataforma de identidade da Microsoft.
Obter um token de acesso
Recomendamos que utilize bibliotecas de autenticação para gerir as interações de tokens com o plataforma de identidade da Microsoft. As bibliotecas de autenticação abstraem muitos detalhes do protocolo, como a validação, o processamento de cookies, a colocação em cache de tokens e a manutenção de ligações seguras, que lhe permitem concentrar o seu desenvolvimento na funcionalidade da sua aplicação. A Microsoft publica bibliotecas de cliente open source 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 arquiteturas, incluindo para .NET, JavaScript, Android e iOS. Todas as plataformas estão em pré-visualização suportada pela produção e, no caso de serem introduzidas alterações interruptivas, a Microsoft garante um caminho para a 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).
- O plataforma de identidade da Microsoft também é compatível com muitas bibliotecas de autenticação de terceiros.
Para obter uma lista completa das bibliotecas de cliente da Microsoft, middleware do servidor da Microsoft e bibliotecas de terceiros compatíveis, veja 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 utilizar diretamente os pontos finais plataforma de identidade da Microsoft sem a ajuda de uma biblioteca de autenticação, consulte os seguintes artigos: