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

O Microsoft Graph é um gateway de API protegido para aceder a dados em serviços cloud da Microsoft, como o Microsoft Entra ID e o Microsoft 365. Está protegida pelo plataforma de identidade da Microsoft, que autoriza e verifica se uma aplicação está autorizada a chamar o Microsoft Graph.

Este artigo fornece uma descrição geral dos requisitos para que uma aplicação seja autorizada a aceder a dados através de qualquer API do Graph Microsoft. Se já estiver familiarizado com o funcionamento da autenticação e autorização, explore exemplos de código para aplicações que chamam APIs do Microsoft Graph.

Registrar o aplicativo

Antes de a sua aplicação poder ser autorizada a ligar para qualquer API do Graph da Microsoft, o plataforma de identidade da Microsoft tem primeiro de estar ciente da mesma. Este processo não envolve o carregamento do código da aplicação para a plataforma. Em vez disso, envolve registar a aplicação no centro de administração do Microsoft Entra para estabelecer as 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 finais nos quais a sua aplicação recebe respostas do plataforma de identidade da Microsoft. O plataforma de identidade da Microsoft atribui o URI a aplicações nativas e móveis.
• Credencial: pode ser um segredo do cliente (uma cadeia ou palavra-passe), um certificado ou uma credencial de identidade federada. A sua aplicação utiliza a credencial para autenticar com o plataforma de identidade da Microsoft. Esta propriedade só é necessária para aplicações cliente confidenciais; Não é necessário para clientes públicos, como aplicações nativas, móveis e de página única. Para obter mais informações, veja Clientes públicos e aplicações cliente confidenciais.

Em seguida, adicione estas informações novamente ao seu código uma vez e a aplicação utiliza sempre as informações necessárias para provar a sua identidade durante um processo de autenticação, antes de poder ser autorizada a aceder aos seus dados.

Para obter mais informações, veja Registar uma aplicação no plataforma de identidade da Microsoft.

Cenários de acesso

Uma aplicação pode aceder aos dados 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 inicia sessão numa aplicação cliente que chama o Microsoft Graph em nome do mesmo. Tanto a aplicação cliente como o utilizador têm de estar autorizados a fazer o pedido.

Para que a aplicação cliente esteja autorizada a aceder aos dados em nome do utilizador com sessão iniciada, tem de ter as permissões necessárias, que recebe através de uma combinação de dois fatores:

• Permissões delegadas, também referidas como âmbitos: as permissões expostas pelo Microsoft Graph e que representam as operações que a aplicação pode realizar em nome do utilizador com sessão iniciada. A aplicação pode ter permissão para executar uma operação em nome de um utilizador, mas não de outro.
• Permissões de utilizador: as permissões que o utilizador com sessão iniciada tem para o recurso. O utilizador pode ser o proprietário do recurso, o recurso pode ser partilhado com o mesmo ou podem ser-lhes atribuídas permissões através de um sistema de controlo de acesso baseado em funções (RBAC), como Microsoft Entra RBAC.

Cenário de exemplo: Acesso delegado no Microsoft Graph

O https://graph.microsoft.com/v1.0/me ponto final é o ponto de acesso para as informações do utilizador com sessão iniciada, que representa um recurso protegido pelo plataforma de identidade da Microsoft. Para o acesso delegado, os dois fatores são cumpridos da seguinte forma:

• A aplicação tem de receber uma permissão delegada suportada do Microsoft Graph, por exemplo, a permissão delegada User.Read , em nome do utilizador com sessão iniciada.
• O utilizador com sessão iniciada neste cenário é o proprietário dos dados.

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.

Para que uma aplicação cliente esteja autorizada a aceder aos dados com a sua própria identidade, tem de ter as permissões necessárias, que recebe através de uma das seguintes formas:

• A aplicação tem permissões de aplicação suportadas do Microsoft Graph, também denominadas funções de aplicações
• É atribuída à aplicação a propriedade do recurso que pretende gerir

Cenário de exemplo: acesso apenas à aplicação no Microsoft Graph

O https://graph.microsoft.com/v1.0/users/delta ponto final permite-lhe consultar as alterações aos dados dos utilizadores. No acesso apenas à aplicação, a aplicação tem de ter uma permissão suportada, por exemplo, a permissão da aplicação User.Read.All Microsoft Graph para poder consultar e receber alterações nos dados do utilizador com êxito.

Permissões do Microsoft Graph

Conforme mencionado anteriormente, uma aplicação tem de ter permissões para aceder aos dados aos quais pretende aceder, independentemente do cenário de acesso.

O Microsoft Graph expõe permissões granulares que controlam o acesso aos recursos do Microsoft Graph, como utilizadores, grupos e correio. Estão disponíveis 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.

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. Quando um utilizador inicia sessão numa aplicação, a aplicação tem de especificar as permissões que tem de incluir 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.

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

Para aceder a um recurso protegido, uma aplicação tem de provar que está autorizada a fazê-lo ao submeter um token de acesso válido. A aplicação obtém este token de acesso quando faz um pedido de autenticação para o plataforma de identidade da Microsoft que, por sua vez, utiliza o token de acesso para verificar se a aplicação está autorizada a chamar 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 com sessão iniciada. AS APIs Web, como o Microsoft Graph, protegidas pelo plataforma de identidade da Microsoft utilizar as afirmações para validar o autor da chamada e para garantir que o autor da chamada está autorizado a executar a operação que está a pedir. Para cenários de acesso delegado, as permissões do utilizador de chamada e da aplicação fazem parte das afirmações. Para cenários de aplicação, as permissões da aplicação fazem parte das afirmações. Para obter mais informações sobre as peças que constituem tokens de acesso, veja Referência de afirmações de tokens de acesso.

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.

Em alternativa, pode utilizar os pontos finais 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
• Descrição geral das permissões do Microsoft Graph