Compartilhar via

Obter acesso em nome de um usuário

  • Artigo

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
Parâmetros
Parâmetro Obrigatório Descrição
locatário Obrigatório O valor de {tenant} no caminho da solicitação pode ser usado para controlar quem pode entrar no aplicativo. Os valores permitidos são:
  • common tanto para contas Microsoft como para contas corporativas e de estudante.
  • organizations para contas corporativas ou de estudante
  • consumers somente para contas Microsoft
  • identificadores de locatário, como a ID do locatário ou o nome de domínio.
    Para obter mais informações, veja noções básicas do protocolo.
    		•
    client_id Obrigatório O ID da Aplicação (cliente) que o portal de registo atribuiu à aplicação. Também referido como appId no objeto de aplicação e principal de serviço do Microsoft Graph.
    response_type Obrigatório Tem de incluir code para o fluxo de código de autorização OAuth 2.0.
    redirect_uri Recomendado O URI de redirecionamento da aplicação, para o qual as respostas de autenticação são enviadas e recebidas pela aplicação. Tem de corresponder exatamente a um dos URIs de redirecionamento que registou no portal de registo de aplicações, exceto que tem de estar codificado com URL. Para aplicações nativas e móveis, deve utilizar o valor predefinido de https://login.microsoftonline.com/common/oauth2/nativeclient.
    escopo Obrigatório Uma lista separada por espaços das permissões do Microsoft Graph que você deseja que o usuário concorde. Estas permissões podem incluir permissões de recursos, como os âmbitos User.Read e Mail.Read e OIDC, como offline_access, o que indica que a aplicação precisa de um token de atualização para um acesso de longa duração aos recursos.
    response_mode Recomendado Especifica o método que deve ser utilizado para enviar o token resultante de volta para a aplicação. Pode ser query ou form_post.
    estado Recomendado Um valor incluído no pedido que também é devolvido na resposta do token. Pode ser uma cadeia de qualquer conteúdo que pretenda. Normalmente, é utilizado um valor exclusivo gerado aleatoriamente para impedir ataques de falsificação de pedidos entre sites. Esta propriedade também é utilizada para codificar informações sobre o estado do utilizador na aplicação antes do pedido de autenticação ter ocorrido, como a página ou vista em que se encontravam.

    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.

    Caixa de diálogo de consentimento da conta 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
    Parâmetro Descrição
    código O código de autorização que a aplicação pediu. A aplicação utiliza o código de autorização para pedir um token de acesso para o recurso de destino. Os códigos de autorização têm uma duração curta, normalmente expiram após cerca de 10 minutos.
    state Se um parâmetro de estado estiver incluído no pedido, o mesmo valor deverá aparecer na resposta. A aplicação deve verificar se os valores de estado no pedido e na resposta são idênticos. Este marcar ajuda a detetar ataques de Falsificação de Pedidos entre Sites (CSRF) contra o cliente.
    session_state Um valor exclusivo que identifica a sessão de usuário atual. Esse valor é um GUID, mas deve ser tratado como um valor opaco passado sem ser examinado.

    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
    Parâmetros
    Parâmetro Obrigatório Descrição
    locatário Obrigatório O valor de {tenant} no caminho da solicitação pode ser usado para controlar quem pode entrar no aplicativo. Os valores permitidos são:
  • common tanto para contas Microsoft como para contas corporativas e de estudante.
  • organizations para contas corporativas ou de estudante
  • consumers somente para contas Microsoft
  • identificadores de locatário, como a ID do locatário ou o nome de domínio.
    Para obter mais informações, veja noções básicas do protocolo.
    		•
    client_id Obrigatório O ID da Aplicação (cliente) que o portal de registo atribuiu à aplicação. Também referido como appId no objeto de aplicação e principal de serviço do Microsoft Graph.
    grant_type Obrigatório Deve ser authorization_code para o fluxo de código de autorização.
    escopo Obrigatório Uma lista separada por espaços de âmbitos. Os âmbitos que a sua aplicação pede nesta perna têm de ser equivalentes ou um subconjunto dos âmbitos que pediu na etapa de autorização no Passo 2. Se os âmbitos especificados neste pedido abranger vários servidores de recursos, o ponto final v2.0 devolve um token para o recurso especificado no primeiro âmbito.
    código Obrigatório O código de autorização que adquiriu na etapa de autorização no Passo 2.
    redirect_uri Obrigatório O mesmo valor de URI de redirecionamento que foi utilizado para adquirir o código de autorização no Passo 2.
    client_secret Obrigatório para aplicativos Web O segredo do cliente que criou no portal de registo de aplicações da sua aplicação. Não deve ser utilizada numa aplicação nativa, porque os segredos do cliente não podem ser armazenados em dispositivos de forma fiável. É necessário para aplicações Web e APIs Web, que têm a capacidade de armazenar o client_secret de forma segura no lado do servidor.

    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
    Parâmetro Descrição
    token_type Indica o valor do tipo de token. O único tipo que Microsoft Entra ID suporta é Bearer.
    scope Uma lista separada por espaços das permissões do Microsoft Graph para as quais o token de acesso é válido.
    expires_in Por quanto tempo o token de acesso é válido (em segundos).
    ext_expires_in Indica uma duração prolongada para o token de acesso (em segundos) e utilizada para suportar resiliência quando o serviço de emissão de tokens não está a responder.
    access_token O token de acesso solicitado. A aplicação pode utilizar este token para chamar o Microsoft Graph.
    refresh_token Um token de atualização OAuth 2.0. A aplicação pode utilizar este token para adquirir tokens de acesso adicionais após a expiração do token de acesso atual. Os tokens de atualização são de longa duração e podem ser usados para manter o acesso aos recursos por longos períodos de tempo. Um token de atualização só será devolvido se offline_access tiver sido incluído como um scope parâmetro. Para obter detalhes, veja a referência do token v2.0.

    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

    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
    Parâmetros
    Parâmetro Obrigatório Descrição
    locatário Obrigatório O valor de {tenant} no caminho da solicitação pode ser usado para controlar quem pode entrar no aplicativo. Os valores permitidos são:
  • common tanto para contas Microsoft como para contas corporativas e de estudante.
  • organizations para contas corporativas ou de estudante
  • consumers somente para contas Microsoft
  • identificadores de locatário, como a ID do locatário ou o nome de domínio.
    Para obter mais informações, veja noções básicas do protocolo.
    		•
    client_id Obrigatório O ID da Aplicação (cliente) que o portal de registo atribuiu à sua aplicação. Também referido como appId no objeto de aplicação e principal de serviço do Microsoft Graph.
    grant_type Obrigatório Deve ser refresh_token.
    escopo Opcional Uma lista separada por espaços de permissões (âmbitos). As permissões a que os pedidos da aplicação têm de ser equivalentes ou um subconjunto das permissões pedidas no pedido de código de autorização original no Passo 2.
    refresh_token Obrigatório O refresh_token que a sua aplicação adquiriu durante o pedido de token no Passo 3.
    client_secret Obrigatório para aplicativos Web O segredo do cliente que criou no portal de registo de aplicações da sua aplicação. Não utilize o segredo numa aplicação nativa, porque client_secrets não podem ser armazenados em dispositivos de forma fiável. É necessário para aplicações Web e APIs Web, que têm a capacidade de armazenar o client_secret de forma segura no lado do servidor.

    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
    Parâmetro Descrição
    access_token O token de acesso solicitado. A aplicação pode utilizar este token em chamadas para o Microsoft Graph.
    token_type Indica o valor do tipo de token. O único tipo que Microsoft Entra ID suporta é Bearer.
    expires_in Por quanto tempo o token de acesso é válido (em segundos).
    escopo As permissões (escopos) para as quais o access_token é válido.
    refresh_token Um novo token de atualização do OAuth 2.0. Substitua o token de atualização antigo por este token de atualização recentemente adquirido para garantir que os tokens de atualização permanecem válidos durante o máximo de tempo possível.

    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.

    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

    • Pode chamar o Microsoft Graph em nome de um utilizador a partir de diferentes tipos de aplicações, como aplicações de página única, aplicações Web e aplicações móveis. Para obter mais informações, veja Cenários e fluxos de autenticação suportados.
    • Escolha a partir de exemplos de código criados 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.