Obter acesso em nome de um usuário

Para chamar o Microsoft Graph, uma aplicação tem de obter um token de acesso a partir do plataforma de identidade da Microsoft. Este token de acesso inclui informações sobre se a aplicação está autorizada a aceder ao Microsoft Graph em nome de um utilizador com sessão iniciada ou com a sua própria identidade. Este artigo fornece orientações sobre como uma aplicação pode aceder ao Microsoft Graph em nome de um utilizador, também denominado acesso delegado.

Este artigo detalha os pedidos HTTP não processados envolvidos para que uma aplicação obtenha acesso em nome de um utilizador através de um fluxo popular chamado fluxo de concessão de código de autorização OAuth 2.0. Em alternativa, pode evitar escrever pedidos HTTP não processados e utilizar uma biblioteca de autenticação criada pela Microsoft ou suportada que processa muitos destes detalhes automaticamente e o ajuda a obter tokens de acesso e a chamar o Microsoft Graph. Para obter mais informações, consulte Utilizar a Biblioteca de Autenticação da Microsoft (MSAL).

Neste artigo, vai concluir os seguintes passos ao utilizar o fluxo de concessão de código de autorização OAuth 2.0:

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

Pré-requisitos

Antes de prosseguir com os passos neste artigo:

1. Compreenda os conceitos de autenticação e autorização no plataforma de identidade da Microsoft. Para obter mais informações, veja Noções básicas de autenticação e autorização.
2. Registe a aplicação com Microsoft Entra ID. Para obter mais informações, veja Registar uma aplicação no plataforma de identidade da Microsoft. Guarde os seguintes valores do registo de aplicações:
   • O ID da aplicação (conhecido como ID do Objeto no centro de administração do Microsoft Entra).
   • Um segredo do cliente (palavra-passe da aplicação), 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.
   • Um URI de redirecionamento para a aplicação receber respostas de tokens de Microsoft Entra ID.

Passo 1: Pedir autorização

O primeiro passo no fluxo de código de autorização é que o utilizador autorize a aplicação a agir em seu nome.

No fluxo, a aplicação redireciona o utilizador para o ponto final plataforma de identidade da Microsoft/authorize. Através deste ponto final, Microsoft Entra ID inicia sessão do utilizador e pede o seu consentimento para as permissões que a aplicação pede. Após a obtenção do consentimento, Microsoft Entra ID devolve um código de autorização à aplicação. Em seguida, a aplicação pode resgatar este código no ponto final plataforma de identidade da Microsoft /token para um token de acesso.

Solicitação de autorização

O exemplo seguinte mostra um pedido para o /authorize ponto final.

No URL do pedido, chama o /authorize ponto final e especifica as propriedades necessárias e recomendadas como parâmetros de consulta.

No exemplo seguinte, a aplicação pede as permissões User.Read e Mail.Read Microsoft Graph, que permitem à aplicação ler o perfil e o e-mail do utilizador com sessão iniciada, respetivamente. A permissão offline_access é um âmbito OIDC padrão pedido para que a aplicação possa obter um token de atualização. A aplicação pode utilizar 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 utilizador

Depois de a aplicação enviar o pedido de autorização, é pedido ao utilizador que introduza as respetivas credenciais para se autenticar com a Microsoft. O ponto final plataforma de identidade da Microsoft v2.0 garante que o utilizador consentiu as permissões indicadas no scope parâmetro de consulta. Se existir alguma permissão para a qual o utilizador ou administrador não tenha consentido, ser-lhe-á pedido para dar consentimento às permissões necessárias. Para obter mais informações sobre a experiência de consentimento do Microsoft Entra, veja Experiência de consentimento da aplicação 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 utilizador consentir as permissões pedidas pela aplicação, a resposta contém o código de autorização no code parâmetro . Eis um exemplo de uma resposta bem-sucedida ao pedido anterior. Uma vez que o response_mode parâmetro no pedido foi definido como query, a resposta é devolvida na cadeia de consulta do 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

Passo 2: Pedir um token de acesso

A aplicação utiliza a autorização code recebida no passo anterior para pedir um token de acesso ao enviar um POST pedido para o /token ponto final.

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 contém uma lista das permissões para as quais o token de acesso é válido no scope parâmetro . A resposta é semelhante à seguinte amostra.

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

Passo 3: utilizar o token de acesso para chamar o Microsoft Graph

Depois de ter um token de acesso, a aplicação utiliza-o para chamar o Microsoft Graph ao anexar o token de acesso como token de Portador ao cabeçalho Autorização num pedido HTTP. O pedido seguinte obtém o perfil do utilizador com sessão iniciada.

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 com êxito é semelhante à seguinte (alguns cabeçalhos de resposta foram 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"
}

Passo 4: Utilizar o token de atualização para renovar um token de acesso expirado

Os tokens de acesso são de curta duração e a aplicação tem de atualizá-los depois de expirarem para continuar a aceder aos recursos. A aplicação fá-lo ao submeter outro POST pedido para o /token ponto final, desta vez:

• Fornecer o refresh_token em vez do código no corpo do pedido
• Especificar 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 com êxito é 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

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

Neste artigo, percorreu os detalhes do protocolo de baixo nível que são necessários apenas ao criar e emitir manualmente pedidos HTTP não processados para executar o fluxo de código de autorização. Nas aplicações de produção, utilize uma biblioteca de autenticação criada pela Microsoft ou suportada, como a Biblioteca de Autenticação da Microsoft (MSAL), para obter tokens de segurança e chamar APIs Web protegidas, como o Microsoft Graph. Além disso, explore como escolher um fornecedor de autenticação do Microsoft Graph com base no cenário.

A MSAL e outras bibliotecas de autenticação suportadas simplificam o processo ao processar detalhes como validação, processamento de cookies, colocação em cache de tokens e ligações seguras, permitindo-lhe concentrar-se na funcionalidade da sua aplicação.

A Microsoft criou e mantém uma vasta seleção de exemplos de código que demonstram a utilização de bibliotecas de autenticação suportadas com o plataforma de identidade da Microsoft. Para aceder a estes exemplos de código, veja os plataforma de identidade da Microsoft exemplos de código.

Conteúdo relacionado

• Explore os tutoriais do Microsoft Graph para obter exemplos de código criados com diferentes SDKs para criar aplicações básicas que autenticam e acedem a dados em cenários delegados.
• Escolha a partir de exemplos de código criados com SDKs diferentes e mantidos pela Microsoft para executar aplicações personalizadas que utilizam bibliotecas de autenticação suportadas, utilizadores de início de sessão e chamar o Microsoft Graph. Veja Tutoriais do Microsoft Graph.