Princípios Básicos de Autenticação e Autorização para o Microsoft GraphAuthentication and authorization basics for Microsoft Graph

Para chamar o Microsoft Graph, o aplicativo deve adquirir um token de acesso da Microsoft Identity Plataform.To call Microsoft Graph, your app must acquire an access token from the Microsoft identity platform. O token de acesso contém informações sobre seu aplicativo e as permissões que ele possui para os recursos e APIs disponíveis no Microsoft Graph.The access token contains information about your app and the permissions it has for the resources and APIs available through Microsoft Graph. Para obter um token de acesso, o aplicativo deve ser registrado com a Microsoft Identity Platform e ter autorização de um usuário ou administrador para acessar os recursos necessários do Microsoft Graph.To get an access token, your app must be registered with the Microsoft identity platform and be authorized by either a user or an administrator for access to the Microsoft Graph resources it needs.

Este tópico fornece uma visão geral dos tokens de acesso, da Microsoft Identidade Platform e de como seu aplicativo pode obter tokens de acesso.This topic provides an overview of access tokens, the Microsoft identity platform, and how your app can get access tokens. Se você já estiver familiarizado com a integração de um aplicativo com o Microsoft Identity Platform para obter tokens, confira a seção Próximas Etapas para obter informações e exemplos específicos do Microsoft Graph.If you are already familiar with integrating an app with the Microsoft identity platform to get tokens, see the Next Steps section for information and samples specific to Microsoft Graph.

Tokens de acessoAccess tokens

Os tokens de acesso emitidos pela Microsoft Identity Platform são codificados em base 64 de JSON Web Tokens (JWT).Access tokens issued by the Microsoft identity platform are base 64 encoded JSON Web Tokens (JWT). Eles contêm informações (declarações) que as APIs da Web protegidas pela Microsoft Identity Platform, como o Microsoft Graph, usam para validar o chamador e para garantir que o chamador tenha as permissões adequadas para executar a operação solicitada.They contain information (claims) that web APIs secured by the Microsoft identity platform, like Microsoft Graph, use to validate the caller and to ensure that the caller has the proper permissions to perform the operation they're requesting. Ao chamar o Microsoft Graph, você pode tratar os tokens de acesso como opacos.When calling Microsoft Graph, you can treat access tokens as opaque. Você deve sempre transmitir tokens de acesso em canais seguros, como protocolo TLS (HTTPS).You should always transmit access tokens over a secure channel, such as transport layer security (HTTPS).

Este é um exemplo de um token de acesso da Microsoft Identity Platform:The following is an example of a Microsoft identity platform access token:

EwAoA8l6BAAU7p9QDpi/D7xJLwsTgCg3TskyTaQAAXu71AU9f4aS4rOK5xoO/SU5HZKSXtCsDe0Pj7uSc5Ug008qTI+a9M1tBeKoTs7tHzhJNSKgk7pm5e8d3oGWXX5shyOG3cKSqgfwuNDnmmPDNDivwmi9kmKqWIC9OQRf8InpYXH7NdUYNwN+jljffvNTewdZz42VPrvqoMH7hSxiG7A1h8leOv4F3Ek/oeJX6U8nnL9nJ5pHLVuPWD0aNnTPTJD8Y4oQTp5zLhDIIfaJCaGcQperULVF7K6yX8MhHxIBwek418rKIp11om0SWBXOYSGOM0rNNN59qNiKwLNK+MPUf7ObcRBN5I5vg8jB7IMoz66jrNmT2uiWCyI8MmYDZgAACPoaZ9REyqke+AE1/x1ZX0w7OamUexKF8YGZiw+cDpT/BP1GsONnwI4a8M7HsBtDgZPRd6/Hfqlq3HE2xLuhYX8bAc1MUr0gP9KuH6HDQNlIV4KaRZWxyRo1wmKHOF5G5wTHrtxg8tnXylMc1PKOtaXIU4JJZ1l4x/7FwhPmg9M86PBPWr5zwUj2CVXC7wWlL/6M89Mlh8yXESMO3AIuAmEMKjqauPrgi9hAdI2oqnLZWCRL9gcHBida1y0DTXQhcwMv1ORrk65VFHtVgYAegrxu3NDoJiDyVaPZxDwTYRGjPII3va8GALAMVy5xou2ikzRvJjW7Gm3XoaqJCTCExN4m5i/Dqc81Gr4uT7OaeypYTUjnwCh7aMhsOTDJehefzjXhlkn//2eik+NivKx/BTJBEdT6MR97Wh/ns/VcK7QTmbjwbU2cwLngT7Ylq+uzhx54R9JMaSLhnw+/nIrcVkG77Hi3neShKeZmnl5DC9PuwIbtNvVge3Q+V0ws2zsL3z7ndz4tTMYFdvR/XbrnbEErTDLWrV6Lc3JHQMs0bYUyTBg5dThwCiuZ1evaT6BlMMLuSCVxdBGzXTBcvGwihFzZbyNoX+52DS5x+RbIEvd6KWOpQ6Ni+1GAawHDdNUiQTQFXRxLSHfc9fh7hE4qcD7PqHGsykYj7A0XqHCjbKKgWSkcAg==

Para chamar o Microsoft Graph, anexe o token de acesso como um token de portador ao cabeçalho de autorização em uma solicitação HTTP.To call Microsoft Graph, you attach the access token as a Bearer token to the Authorization header in an HTTP request. 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):For example, the following call that returns the profile information of the signed-in user (the access token has been shortened for readability):

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

Registre um aplicativo na Microsoft Identity PlatformRegister your app with the Microsoft identity platform

Antes que seu aplicativo possa receber um token da Microsoft Identity Platform, ele deve ser registrado no portal do Azure.Before your app can get a token from the Microsoft identity platform, it must be registered in the Azure portal. O registro integra o aplicativo com a Microsoft Identity Platform e estabelece as informações que ele usa para acessar os tokens, incluindo:Registration integrates your app with the Microsoft identity platform and establishes the information that it uses to get tokens, including:

  • ID do aplicativo: um identificador exclusivo atribuído pela Microsoft Identity Platform.Application ID: A unique identifier assigned by the Microsoft identity platform.
  • Redirecionamento de URL/URI: um ou mais pontos de extremidade no qual seu aplicativo receberá respostas da Microsoft Identity Platform.Redirect URI/URL: One or more endpoints at which your app will receive responses from the Microsoft identity platform. (Para aplicativos móveis e nativos, será um URI atribuído pela Microsoft Identity Platform.)(For native and mobile apps, this is a URI assigned by the Microsoft identity platform.)
  • Segredo do Aplicativo: uma senha ou um par de chaves públicas/particulares que seu aplicativo usa para se autenticar com a Microsoft Identity Platform.Application Secret: A password or a public/private key pair that your app uses to authenticate with the Microsoft identity platform. (Não é necessário para aplicativos nativos ou móveis.)(Not needed for native or mobile apps.)

As propriedades definidas durante o registro são usadas na solicitação.The properties configured during registration are used in the request. Por exemplo, na solicitação de token a seguir: client_id é a ID do Aplicativo, redirect_uri é um URIs de Redirecionamento de seu aplicativo registrado, e client_secret é o Segredo do Aplicativo.For example, in the following token request: client_id is the Application ID, redirect_uri is one of your app's registered Redirect URIs, and client_secret is the Application Secret.

// Line breaks for legibility only

POST /common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=user.read%20mail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps

Permissões do Microsoft GraphMicrosoft Graph permissions

O Microsoft Graph expõe as permissões granulares que controlam o acesso que os aplicativos têm aos recursos, como usuários, grupos e email.Microsoft Graph exposes granular permissions that control the access that apps have to resources, like users, groups, and mail. Como desenvolvedor, você decide quais permissões seu aplicativo deverá solicitar para o Microsoft Graph.As a developer, you decide which permissions to request for Microsoft Graph. Quando um usuário entra no aplicativo, ele, ou, em alguns casos, um administrador, tem a opção de consentir essas permissões.When a user signs in to your app they, or, in some cases, an administrator, are given a chance to consent to these permissions. Se o usuário consentir, seu aplicativo receberá acesso aos recursos e APIs solicitados.If the user consents, your app is given access to the resources and APIs that it has requested. Para aplicativos que não aceitam usuários conectados, as permissões podem ser previamente consentidas pelo administrador quando o aplicativo é instalado.For apps that don't take a signed-in user, permissions can be pre-consented to by an administrator when the app is installed.

O Microsoft Graph tem dois tipos de permissões:Microsoft Graph has two types of permissions:

  • As permissões delegadas são usadas pelos aplicativos que têm um usuário conectado atualmente.Delegated permissions are used by apps that have a signed-in user present. Para esses aplicativos, o usuário ou um administrador concorda com as permissões que o aplicativo solicita e o aplicativo pode agir como o usuário conectado ao fazer chamadas ao Microsoft Graph.For these apps either the user or an administrator consents to the permissions that the app requests and the app can act as the signed-in user when making calls to Microsoft Graph. Algumas permissões delegadas podem ser autorizadas por usuários não administradores, mas algumas permissões com maiores privilégios exigem o consentimento do administrador.Some delegated permissions can be consented by non-administrative users, but some higher-privileged permissions require administrator consent.

  • As permissões de aplicativo são usadas pelos aplicativos que são executados sem um usuário conectado. Por exemplo, aplicativos executados em segundo plano ou como daemons.Application permissions are used by apps that run without a signed-in user present; for example, apps that run as background services or daemons. As permissões de aplicativo só podem ser concedidas por um administrador.Application permissions can only be consented by an administrator.

As permissões efetivas são as permissões que seu aplicativo terá ao fazer solicitações ao Microsoft Graph. É importante compreender a diferença entre as Permissões Delegadas e as Permissões de aplicativo que o aplicativo tem autorização para usar e as respectivas Permissões Efetivas ao fazer chamadas para o Microsoft GraphEffective permissions are the permissions that your app will have when making requests to Microsoft Graph. It is important to understand the difference between the delegated and application permissions that your app is granted and its effective permissions when making calls to Microsoft Graph.

  • No caso de permissões delegadas, as permissões efetivas do aplicativo estarão na interseção menos privilegiada das permissões delegadas que o aplicativo recebeu (por meio de consentimento) e dos privilégios do usuário atualmente conectado.For delegated permissions, the effective permissions of your app will be the intersection of the delegated permissions the app has been granted (via consent) and the privileges of the currently signed-in user. O aplicativo jamais pode ter mais privilégios do que o usuário conectado.Your app can never have more privileges than the signed-in user. Nas organizações, os privilégios do usuário conectado podem ser determinados por uma política ou pela associação a uma ou mais funções de administrador.Within organizations, the privileges of the signed-in user may be determined by policy or by membership in one or more administrator roles. Para obter mais informações sobre funções de administrador, confira Atribuindo funções de administrador no Azure Active Directory.For more information about administrator roles, see Assigning administrator roles in Azure Active Directory.

    Por exemplo, digamos que o aplicativo recebeu a permissão delegada User.ReadWrite.All.For example, assume your app has been granted the User.ReadWrite.All delegated permission. Essa permissão autoriza o aplicativo a ler e atualizar o perfil de todos os usuários em uma organização.This permission nominally grants your app permission to read and update the profile of every user in an organization. Se o usuário conectado for um administrador global, seu aplicativo conseguirá atualizar o perfil de todos os usuários na organização.If the signed-in user is a global administrator, your app will be able to update the profile of every user in the organization. No entanto, se o usuário conectado não tiver uma função de administrador, seu aplicativo conseguirá atualizar apenas o perfil do usuário conectado.However, if the signed-in user is not in an administrator role, your app will be able to update only the profile of the signed-in user. Ele não conseguirá atualizar os perfis de outros usuários na organização porque o usuário que tem permissão para agir em nome de outra pessoa não tem esses privilégios.It will not be able to update the profiles of other users in the organization because the user that it has permission to act on behalf of does not have those privileges.

  • No caso de permissões de aplicativo, as permissões efetivas do aplicativo estarão no nível completo de privilégios implícitos na permissão.For application permissions, the effective permissions of your app will be the full level of privileges implied by the permission. Por exemplo, um aplicativo que tem a permissão de aplicativo User.ReadWrite.All pode atualizar o perfil de todos os usuários na organização.For example, an app that has the User.ReadWrite.All application permission can update the profile of every user in the organization.

Observação Por padrão, os aplicativos que receberam permissões de aplicativo para os seguintes conjuntos de dados podem acessar todas as caixas de correio na organização:Note By default, apps that have been granted application permissions to the following data sets can access all the mailboxes in the organization:

Os administradores podem configurar a política de acesso a aplicativos para limitar o acesso do aplicativo a caixas de correio específicas.Administrators can configure application access policy to limit app access to specific mailboxes.

Para obter uma lista completa das permissões do Microsoft Graph e saber quais permissões precisam de autorização de um administrador, confira a Referência de permissões.For a complete list of delegated and application permissions for Microsoft Graph, as well as which permissions require administrator consent, see the Permissions reference.

Obter um token de acessoGetting an access token

Como a maioria dos desenvolvedores, você provavelmente usará bibliotecas de autenticação para gerenciar suas interações de token com a Microsoft Identity Platform.Like most developers, you will probably use authentication libraries to manage your token interactions with the Microsoft identity platform. As bibliotecas de autenticação resumem muitos detalhes do protocolo, como validação, manipulação de cookies, armazenamento de token em cache e manutenção de conexões seguras, fora do desenvolvedor e isso permite que você foque no desenvolvimento de seu aplicativo.Authentication libraries abstract many protocol details, like validation, cookie handling, token caching, and maintaining secure connections, away from the developer and let you focus your development on your app. A Microsoft publica bibliotecas de software livre do cliente e servidor middleware.Microsoft publishes open source client libraries and server middleware.

Sobre o ponto de extremidade da Microsoft Identity Platform:For the Microsoft identity platform endpoint:

  • As bibliotecas de cliente da Biblioteca de Autenticação da Microsoft (MSAL) estão disponíveis para .NET, JavaScript, Android e Objective-c. Todas as plataformas estão em pré-visualização com suporte à produção e, no caso de alterações serem introduzidas, a Microsoft garante um caminho para a atualização.Microsoft Authentication Library (MSAL) client libraries are available for .NET, JavaScript, Android, and Objective-c. All platforms are in production-supported preview, and, in the event breaking changes are introduced, Microsoft guarantees a path to upgrade.
  • O middleware de servidor da Microsoft está disponível para .NET core e ASP.NET (OWIN OpenID Connect e OAuth) e para Node.js (Microsoft Identity Platform Passport.js).Server middleware from Microsoft is available for .NET core and ASP.NET (OWIN OpenID Connect and OAuth) and for Node.js (Microsoft the Microsoft identity platform Passport.js).
  • A Microsoft Identity Platform é compatível com várias bibliotecas de autenticação de terceiros.The Microsoft identity platform is compatible with many third-party authentication libraries.

Para obter uma lista completa de bibliotecas de cliente da Microsoft, middleware de servidor da Microsoft e bibliotecas de terceiros compatíveis, confira Bibliotecas de autenticação da Microsoft Identity Platform.For a complete list of Microsoft client libraries, Microsoft server middleware, and compatible third-party libraries, see Microsoft identity platform authentication libraries.

Não é necessário usar uma biblioteca de autenticação para obter um token de acesso.You do not need to use an authentication library to get an access token. Para saber mais do uso direto com os pontos de extremidade da Microsoft Identity Platform sem a ajuda de uma biblioteca de autenticação, confira autenticação da Microsoft Identity PlatformTo learn about directly using the Microsoft identity platform endpoints without the help of an authentication library, see Microsoft identity platform authentication

Próximas etapasNext steps

Se já estiver pronto para entrar no código, você pode usar os seguintes recursos para ajudá-lo a implementar a autenticação e a autorização com a Microsoft Identity Platform em seu aplicativo.If you're ready to jump into code, you can use the following resources to help you implement authentication and authorization with the Microsoft identity platform in your app.

Exemplos e treinamento do Microsoft GraphMicrosoft Graph training and samples

Para ajudá-lo a começar rapidamente, criamos uma série de módulos de treinamento e outros recursos que mostram como autenticar e usar a API em diversas plataformas.To help you get started quickly, we've created a series of training modules and other resources that show you how to authenticate and use the API on a variety of platforms.

Documentação e exemplos da Microsoft Identity PlatformMicrosoft identity platform samples and documentation

A documentação da Microsoft Identity Platform contém artigos e exemplos que se concentram especificamente na autenticação e autorização com a Microsoft Identity Platform.The Microsoft identity platform documentation contains articles and samples that specifically focus on authentication and authorization with the Microsoft identity platform.

Confira tambémSee also