Obter acesso em nome de um usuário

  • Artigo

Para chamar o Microsoft Graph, um aplicativo deve obter um token de acesso do 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 diretrizes 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 um fluxo popular chamado fluxo de concessão de código de autorização OAuth 2.0. Como alternativa, você pode evitar escrever solicitações HTTP brutas e usar uma biblioteca de autenticação criada pela Microsoft ou com suporte que manipula muitos desses detalhes para você e ajuda você 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).

Pré-requisitos

Antes de prosseguir com as etapas deste artigo:

  1. Entenda os conceitos de autenticação e autorização no plataforma de identidade da Microsoft. Para obter mais informações, confira Noções básicas de autenticação e autorização.
  2. Registre o aplicativo com Microsoft Entra ID. Para obter mais informações, consulte Registrar um aplicativo com o plataforma de identidade da Microsoft.

Etapas de autenticação e autorização

Para que um aplicativo obtenha autorização e acesso ao Microsoft Graph usando o fluxo de código de autorização, você deve seguir estas cinco etapas:

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

1. Registrar o aplicativo

Antes que o aplicativo possa chamar os pontos de extremidade plataforma de identidade da Microsoft ou o Microsoft Graph, ele deve ser registrado corretamente. Siga as etapas para registrar seu aplicativo no centro de administração do Microsoft Entra.

No registro do aplicativo, salve os seguintes valores:

  • A ID do aplicativo (conhecida como ID do objeto no centro de administração do Microsoft Entra) atribuída pelo portal de registro do aplicativo.
  • Um URI de redirecionamento (ou URL de resposta) para que o aplicativo receba respostas de Microsoft Entra ID.
  • 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.

2. Solicitar autorização

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

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

Solicitação de autorização

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

Na URL de 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
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, consulte noções básicas de protocolo.
    		•
    client_id Obrigatório A ID do aplicativo (cliente) que o portal de registro atribuiu ao aplicativo. Também conhecido como appId no objeto de entidade de serviço e aplicativo do Microsoft Graph.
    response_type Obrigatório Deve incluir code para o fluxo de código de autorização do OAuth 2.0.
    redirect_uri Recomendado O URI de redirecionamento do aplicativo, para o qual as respostas de autenticação são enviadas e recebidas pelo aplicativo. Ele deve corresponder exatamente a uma das URIs de redirecionamento que você registrou no portal de registro do aplicativo, exceto que ela deve ser codificada por URL. Para aplicativos nativos e móveis, você deve usar o valor padrão 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. Essas permissões podem incluir permissões de recurso, como escopos User.Read e Mail.Read e OIDC, como offline_access, o que indica que o aplicativo precisa de um token de atualização para acesso de longa duração aos recursos.
    response_mode Recomendado Especifica o método que deve ser usado para enviar o token resultante de volta para o aplicativo. Pode ser query ou form_post.
    estado Recomendado Um valor incluído na solicitação que também é retornada na resposta do token. Pode ser uma cadeia de caracteres de qualquer conteúdo desejado. Um valor exclusivo gerado aleatoriamente normalmente é usado para evitar ataques de falsificação de solicitação entre sites. Essa propriedade também é usada para codificar informações sobre o estado do usuário no aplicativo antes da solicitação de autenticação ocorrer, como a página ou a exibição em que eles estavam.

    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 plataforma de identidade da Microsoft v2.0 garante que o usuário tenha consentido com as permissões indicadas no parâmetro de scope consulta. Se houver alguma permissão para a qual o usuário ou administrador não tenha consentido, eles serão solicitados a consentir com as permissões necessárias. Para obter mais informações sobre a experiência de consentimento Microsoft Entra, consulte Experiência de consentimento do aplicativo e Introdução a 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 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
    Parâmetro Descrição
    código O código de autorização solicitado pelo aplicativo. O aplicativo usa o código de autorização para solicitar um token de acesso para o recurso de destino. Os códigos de autorização são de curta duração, normalmente expiram após cerca de 10 minutos.
    state Se um parâmetro de estado for incluído na solicitação, o mesmo valor deverá aparecer na resposta. O aplicativo deve verificar se os valores de estado na solicitação e resposta são idênticos. Esse marcar ajuda a detectar ataques CSRF (Falsificação de Solicitação entre Sites) 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.

    3. 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
    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, consulte noções básicas de protocolo.
    		•
    client_id Obrigatório A ID do aplicativo (cliente) que o portal de registro atribuiu ao aplicativo. Também conhecido como appId no objeto de entidade de serviço e aplicativo 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 de escopos separados por espaço. Os escopos que seu aplicativo solicita nesta etapa devem ser equivalentes ou a um subconjunto dos escopos solicitados na etapa de autorização na Etapa 2. Se os escopos especificados nesta solicitação abrangem vários servidores de recursos, o ponto de extremidade v2.0 retornará um token para o recurso especificado no primeiro escopo.
    código Obrigatório O código de autorização que você adquiriu na etapa de autorização na Etapa 2.
    redirect_uri Obrigatório O mesmo valor de URI de redirecionamento que foi usado para adquirir o código de autorização na Etapa 2.
    client_secret Obrigatório para aplicativos Web O segredo do cliente que você criou no portal de registro do aplicativo para seu aplicativo. Ele não deve ser usado em um aplicativo nativo, pois os segredos do cliente não podem ser armazenados de forma confiável em dispositivos. Ele é necessário para aplicativos Web e APIs Web, que têm a capacidade de armazenar o client_secret com segurança 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 é bom 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
    Parâmetro Descrição
    token_type Indica o valor do tipo de token. O único tipo que Microsoft Entra ID dá suporte é Bearer.
    scope Uma lista separada por espaço 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 um tempo de vida estendido para o token de acesso (em segundos) e usado para dar suporte à resiliência quando o serviço de emissão de token não está respondendo.
    access_token O token de acesso solicitado. O aplicativo pode usar esse token para chamar o Microsoft Graph.
    refresh_token Um token de atualização OAuth 2.0. O aplicativo pode usar esse 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á retornado se offline_access for incluído como um scope parâmetro. Para obter detalhes, confira a referência de token v2.0.

    4. Use o token de acesso para chamar o Microsoft Graph

    Depois de ter um token de acesso, o aplicativo o usa para chamar o Microsoft Graph anexando o token de acesso como um token bearer ao cabeçalho Autorização 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

    Resposta

    Uma resposta bem-sucedida é 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"
}

    5. Use 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 faz isso 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
    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, consulte noções básicas de protocolo.
    		•
    client_id Obrigatório A ID do aplicativo (cliente) que o portal de registro atribuiu ao seu aplicativo. Também conhecido como appId no objeto de entidade de serviço e aplicativo do Microsoft Graph.
    grant_type Obrigatório Deve ser refresh_token.
    escopo Opcional Uma lista separada por espaço de permissões (escopos). As permissões que seu aplicativo solicita devem ser equivalentes ou um subconjunto das permissões solicitadas na solicitação de código de autorização original na Etapa 2.
    refresh_token Obrigatório O refresh_token que seu aplicativo adquiriu durante a solicitação de token na Etapa 3.
    client_secret Obrigatório para aplicativos Web O segredo do cliente que você criou no portal de registro do aplicativo para seu aplicativo. Não use o segredo em um aplicativo nativo, pois client_secrets não podem ser armazenados de forma confiável em dispositivos. Ele é necessário para aplicativos Web e APIs Web, que têm a capacidade de armazenar o client_secret com segurança no lado do servidor.

    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
    Parâmetro Descrição
    access_token O token de acesso solicitado. O aplicativo pode usar esse token em chamadas para o Microsoft Graph.
    token_type Indica o valor do tipo de token. O único tipo que Microsoft Entra ID dá suporte é 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 esse token de atualização recém-adquirido para garantir que seus tokens de atualização permaneçam válidos pelo maior tempo possível.

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

    Neste artigo, você percorreu os detalhes do protocolo de baixo nível geralmente necessários somente ao criar manualmente e emitir 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 pela Microsoft, como o Microsoft Graph.

    O MSAL e outras bibliotecas de autenticação com suporte simplificam o processo para você lidando com detalhes como validação, manipulação de cookie, cache de token e conexões seguras, permitindo que você se concentre 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 com suporte com o plataforma de identidade da Microsoft. Para acessar esses exemplos de código, consulte os exemplos de código plataforma de identidade da Microsoft.

    Conteúdo relacionado

    • Você pode chamar o Microsoft Graph em nome de um usuário de diferentes tipos de aplicativos, como aplicativos de página única, aplicativos Web e aplicativos móveis. Para obter mais informações, consulte Cenários e fluxos de autenticação com suporte.
    • Escolha entre exemplos de código criados e mantidos pela Microsoft para executar aplicativos personalizados que usam bibliotecas de autenticação com suporte, usuários de entrada e chamar o Microsoft Graph. Confira tutoriais do Microsoft Graph.