Obter acesso em nome de um usuário

Para chamar o Microsoft Graph, um aplicativo deve obter um token de acesso da plataforma de identidade da Microsoft. Esse token de acesso inclui informações sobre se o aplicativo está autorizado a acessar o Microsoft Graph em nome de um usuário conectado ou com sua própria identidade. Este artigo fornece orientações sobre como um aplicativo pode acessar o Microsoft Graph em nome de um usuário, também chamado de acesso delegado.

Este artigo detalha as solicitações HTTP brutas envolvidas para que um aplicativo obtenha acesso em nome de um usuário usando o popular fluxo de concessão de código de autorização OAuth 2.0. Normalmente, você não precisa escrever solicitações HTTP brutas e, em vez disso, usa uma biblioteca de autenticação criada ou com suporte pela Microsoft que lida com muitos desses detalhes para você e o ajuda a obter tokens de acesso e chamar o Microsoft Graph. Para obter mais informações, consulte Usar a MSAL (Biblioteca de Autenticação da Microsoft).

Neste artigo, conclua as seguintes etapas para usar o fluxo de concessão de código de autorização OAuth 2.0:

1. Solicitar autorização.
2. Solicite um token de acesso.
3. Use o token de acesso para chamar o Microsoft Graph.
4. [Opcional] Use o token de atualização para renovar um token de acesso expirado.

Pré-requisitos

Antes de prosseguir com as etapas deste artigo:

1. Entenda os conceitos de autenticação e autorização na plataforma de identidade da Microsoft. Para obter mais informações, consulte Noções básicas de autenticação e autorização.
2. Registre o aplicativo com o Microsoft Entra ID. Para obter mais informações, consulte Registrar um aplicativo na plataforma de identidade da Microsoft. Salve os seguintes valores do registro do aplicativo:
   • A ID do aplicativo (chamada de ID do Objeto no centro de administração do Microsoft Entra).
   • Um segredo do cliente (senha do aplicativo), 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.
   • Um URI de redirecionamento para o aplicativo receber respostas de token do Microsoft Entra ID.

Etapa 1: Solicitar autorização

A primeira etapa no fluxo do código de autorização é o usuário autorizar o aplicativo a agir em seu nome.

No fluxo, o aplicativo redireciona o usuário para o ponto de extremidade da plataforma de identidade da Microsoft/authorize. Por meio desse ponto de extremidade, o Microsoft Entra ID no usuário e solicita seu consentimento para as permissões solicitadas pelo aplicativo. Depois que o consentimento é obtido, o Microsoft Entra ID retorna um código de autorização para o aplicativo. O aplicativo pode resgatar esse código no ponto de extremidade da plataforma de identidade da Microsoft para um token de /token acesso.

Solicitação de autorização

O exemplo a seguir mostra uma solicitação para o /authorize ponto de extremidade.

Na URL da solicitação, você chama o /authorize ponto de extremidade e especifica as propriedades necessárias e recomendadas como parâmetros de consulta.

No exemplo a seguir, o aplicativo solicita as permissões User.Read e Mail.Read do Microsoft Graph, que permitem que o aplicativo leia o perfil e o email do usuário conectado, respectivamente. A permissão offline_access é um escopo OIDC padrão solicitado para que o aplicativo possa obter um token de atualização. O aplicativo pode usar o token de atualização para obter um novo token de acesso quando o atual expirar.

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=11111111-1111-1111-1111-111111111111
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=offline_access%20user.read%20mail.read
&state=12345  HTTP/1.1

curl --location --request GET 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?client_id=11111111-1111-1111-1111-111111111111&response_type=code&redirect_uri=https%3A%2F%2Flocalhost%2Fmyapp%2F&response_mode=query&scope=offline_access%20User.Read%20Mail.Read&state=12345'

Parâmetros

Experiência de consentimento do usuário

Depois que o aplicativo envia a solicitação de autorização, o usuário é solicitado a inserir suas credenciais para se autenticar com a Microsoft. O ponto de extremidade da plataforma de identidade da Microsoft v2.0 garante que o usuário concorde com as permissões indicadas no scope parâmetro de consulta. Se o usuário ou administrador não consentiu com nenhuma permissão, ele será solicitado a consentir com as permissões necessárias. Para obter mais informações sobre a experiência de consentimento do Microsoft Entra, consulte Experiência de consentimento do aplicativo e Introdução às permissões e consentimento.

A captura de tela a seguir é um exemplo de caixa de diálogo de consentimento apresentada para uma conta de usuário da Microsoft.

Resposta da autorização

Se o usuário consentir com as permissões solicitadas pelo aplicativo, a resposta conterá o código de autorização no code parâmetro. Aqui está um exemplo de uma resposta bem-sucedida à solicitação anterior. Como o response_mode parâmetro na solicitação foi definido como query, a resposta é retornada na cadeia de caracteres de consulta da URL de redirecionamento.

HTTP/1.1 200 OK

https://localhost/myapp/?code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d&state=12345&session_state=fe1540c3-a69a-469a-9fa3-8a2470936421#

Parâmetros de consulta

Etapa 2: solicitar um token de acesso

O aplicativo usa a autorização code recebida na etapa anterior para solicitar um token de acesso enviando uma POST solicitação ao /token ponto de extremidade.

Solicitação de token

// Line breaks for legibility only

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

client_id=11111111-1111-1111-1111-111111111111
&scope=user.read%20mail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=HF8Q~Krjqh4r...    // NOTE: Only required for web apps

curl --location --request POST 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=11111111-1111-1111-1111-111111111111' \
--data-urlencode 'scope=User.Read Mail.Read' \
--data-urlencode 'code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d' \
--data-urlencode 'redirect_uri=https://localhost/myapp/' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_secret=zHF8Q~Krjqh4r...''

Parâmetros

Resposta do token

O token de acesso inclui uma lista de permissões no scope parâmetro. A resposta é semelhante ao exemplo a seguir.

HTTP/1.1 200 OK
Content-type: application/json

{
    "token_type": "Bearer",
    "scope": "Mail.Read User.Read",
    "expires_in": 3736,
    "ext_expires_in": 3736,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4..."
}

Propriedades do corpo da resposta

Etapa 3: usar o token de acesso para ligar para o Microsoft Graph

Depois de obter um token de acesso, o aplicativo o usa para chamar o Microsoft Graph anexando o token de acesso como um token de portador ao cabeçalho Authorization em uma solicitação HTTP. A solicitação a seguir obtém o perfil do usuário conectado.

Solicitação

GET https://graph.microsoft.com/v1.0/me  HTTP/1.1
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com

curl --location --request GET 'https://graph.microsoft.com/v1.0/me' \
--header 'Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw' \
--data ''

Resposta

Uma resposta bem-sucedida é semelhante ao exemplo a seguir (alguns cabeçalhos de resposta são removidos).

HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8
request-id: f45d08c0-6901-473a-90f5-7867287de97f
client-request-id: f45d08c0-6901-473a-90f5-7867287de97f
OData-Version: 4.0
Duration: 727.0022
Date: Thu, 20 Apr 2017 05:21:18 GMT
Content-Length: 407

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "businessPhones": [
        "425-555-0100"
    ],
    "displayName": "MOD Administrator",
    "givenName": "MOD",
    "jobTitle": null,
    "mail": "admin@contoso.com",
    "mobilePhone": "425-555-0101",
    "officeLocation": null,
    "preferredLanguage": "en-US",
    "surname": "Administrator",
    "userPrincipalName": "admin@contoso.com",
    "id": "10a08e2e-3ea2-4ce0-80cb-d5fdd4b05ea6"
}

Etapa 4: Usar o token de atualização para renovar um token de acesso expirado

Os tokens de acesso são de curta duração e o aplicativo deve atualizá-los depois que expirarem para continuar acessando recursos. O aplicativo atualiza um token de acesso enviando outra POST solicitação ao /token ponto de extremidade, desta vez:

• Fornecendo o refresh_token em vez do código no corpo da solicitação
• Especificando refresh_token como o grant_type, em vez de authorization_code.

Solicitação

// Line breaks for legibility only

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

client_id=11111111-1111-1111-1111-111111111111
&scope=user.read%20mail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=jXoM3iz...      // NOTE: Only required for web apps

curl --location --request POST 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=11111111-1111-1111-1111-111111111111' \
--data-urlencode 'scope=User.Read Mail.Read' \
--data-urlencode 'refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_secret=jXoM3iz...'

Parâmetros

Resposta

Uma resposta de token bem-sucedida é semelhante à seguinte.

HTTP/1.1 200 OK
Content-type: application/json

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "Mail.Read User.Read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
}

Parâmetros do corpo da resposta

Usar a Biblioteca de Autenticação da Microsoft (MSAL)

Neste artigo, você viu os detalhes do protocolo de baixo nível que são necessários somente ao criar e emitir manualmente solicitações HTTP brutas para executar o fluxo de código de autorização. Em aplicativos de produção, use uma biblioteca de autenticação criada pela Microsoft ou com suporte, como a MSAL (Biblioteca de Autenticação da Microsoft), para obter tokens de segurança e chamar APIs Web protegidas, como o Microsoft Graph. Além disso, explore como escolher um provedor de autenticação do Microsoft Graph com base no cenário.

A MSAL e outras bibliotecas de autenticação com suporte simplificam o processo para você, manipulando detalhes como validação, manipulação de cookies, cache de token e conexões seguras, para que você possa se concentrar na funcionalidade do seu aplicativo.

A Microsoft criou e mantém uma ampla seleção de exemplos de código que demonstram o uso de bibliotecas de autenticação compatíveis com a plataforma de identidade da Microsoft. Para acessar esses exemplos de código, consulte os exemplos de código da plataforma de identidade da Microsoft.

Conteúdo relacionado

• Explore os tutoriais do Microsoft Graph para obter exemplos de código criados usando SDKs diferentes para criar aplicativos básicos que autenticam e acessam dados em cenários delegados.
• Escolha entre exemplos de código criados usando SDKs diferentes e mantidos pela Microsoft para executar aplicativos personalizados que usam bibliotecas de autenticação compatíveis, conectar usuários e chamar o Microsoft Graph. Veja os tutoriais do Microsoft Graph.