OAuth 2.0 para aplicativos da Web do lado do cliente

Endpoints OAuth 2.0

Gere um URL para solicitar acesso ao endpoint OAuth 2.0 do Google em https://accounts.google.com/o/oauth2/v2/auth. Esse endpoint pode ser acessado por HTTPS. Conexões HTTP simples são recusadas.

O servidor de autorização do Google oferece suporte aos seguintes parâmetros de string de consulta para aplicativos de servidor da Web:

Exemplo de redirecionamento para o servidor de autorização do Google

Um exemplo de URL é mostrado abaixo, com quebras de linha e espaços para facilitar a leitura.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Depois de criar o URL da solicitação, redirecione o usuário para ele.

Exemplo de código JavaScript

O snippet de JavaScript a seguir mostra como iniciar o fluxo de autorização em JavaScript sem usar a biblioteca de cliente das APIs do Google para JavaScript. Como esse endpoint OAuth 2.0 não oferece suporte ao compartilhamento de recursos entre origens (CORS, na sigla em inglês), o snippet cria um formulário que abre a solicitação para esse endpoint.

/*
 * Create form to request access token from Google's OAuth 2.0 server.
 */
function oauthSignIn() {
  // Google's OAuth 2.0 endpoint for requesting an access token
  var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

  // Create <form> element to submit parameters to OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'GET'); // Send as a GET request.
  form.setAttribute('action', oauth2Endpoint);

  // Parameters to pass to OAuth 2.0 endpoint.
  var params = {'client_id': 'YOUR_CLIENT_ID',
                'redirect_uri': 'YOUR_REDIRECT_URI',
                'response_type': 'token',
                'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly',
                'include_granted_scopes': 'true',
                'state': 'pass-through value'};

  // Add form parameters as hidden input values.
  for (var p in params) {
    var input = document.createElement('input');
    input.setAttribute('type', 'hidden');
    input.setAttribute('name', p);
    input.setAttribute('value', params[p]);
    form.appendChild(input);
  }

  // Add form to page and submit it to open the OAuth 2.0 endpoint.
  document.body.appendChild(form);
  form.submit();
}

Endpoints OAuth 2.0

O servidor OAuth 2.0 envia uma resposta para o redirect_uri especificado na sua solicitação de token de acesso.

Se o usuário aprovar a solicitação, a resposta conterá um token de acesso. Se o usuário não aprovar a solicitação, a resposta conterá uma mensagem de erro. O token de acesso ou a mensagem de erro é retornado no fragmento de hash do URI de redirecionamento, conforme mostrado abaixo:

• Uma resposta de token de acesso:

  https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600

  Além do parâmetro access_token, a string de fragmento também contém o parâmetro token_type, que é sempre definido como Bearer, e o parâmetro expires_in, que especifica o ciclo de vida do token em segundos. Se o parâmetro state foi especificado na solicitação de token de acesso, o valor dele também será incluído na resposta.

• Uma resposta de erro:

  https://oauth2.example.com/callback#error=access_denied

Exemplo de resposta do servidor OAuth 2.0

Para testar esse fluxo, clique no seguinte URL de exemplo, que solicita acesso de leitura somente para visualizar metadados de arquivos no Google Drive e acesso de leitura somente para conferir seus eventos do Google Agenda:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Depois de concluir o fluxo do OAuth 2.0, você será redirecionado para http://localhost/oauth2callback. Esse URL vai gerar um erro 404 NOT FOUND, a menos que sua máquina local forneça um arquivo nesse endereço. A próxima etapa fornece mais detalhes sobre as informações retornadas no URI quando o usuário é redirecionado de volta para o aplicativo.

Endpoints OAuth 2.0

Para verificar se o usuário concedeu ao seu app acesso a um escopo específico, examine o campo scope na resposta do token de acesso. Os escopos de acesso concedidos pelo access_token expressos como uma lista de strings sensíveis a maiúsculas e minúsculas delimitadas por espaço.

Por exemplo, a resposta de token de acesso de exemplo a seguir indica que o usuário concedeu ao seu app acesso às permissões de eventos da Agenda e de atividade do Drive somente leitura:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Endpoints OAuth 2.0

Depois que o aplicativo receber um token de acesso, ele poderá usá-lo para fazer chamadas para uma API do Google em nome de uma determinada conta de usuário, se os escopos de acesso exigidos pela API tiverem sido concedidos. Para fazer isso, inclua o token de acesso em uma solicitação para a API incluindo um parâmetro de consulta access_token ou um valor Bearer de cabeçalho HTTP Authorization. Quando possível, o cabeçalho HTTP é preferível, porque as strings de consulta tendem a ficar visíveis nos registros do servidor. Na maioria dos casos, é possível usar uma biblioteca de cliente para configurar suas chamadas para as APIs do Google. Por exemplo, ao chamar a API Drive Files.

Teste todas as APIs do Google e confira os escopos delas no OAuth 2.0 Playground.

Exemplos de GET HTTP

Uma chamada para o endpoint drive.files (a API Drive Files) usando o cabeçalho HTTP Authorization: Bearer pode ser semelhante ao seguinte. É necessário especificar seu próprio token de acesso:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Esta é uma chamada para a mesma API do usuário autenticado usando o parâmetro de string de consulta access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Exemplos de curl

É possível testar esses comandos com o aplicativo de linha de comando curl. Confira um exemplo que usa a opção de cabeçalho HTTP (preferencial):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Ou, como alternativa, a opção de parâmetro de string de consulta:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Exemplo de código JavaScript

O snippet de código abaixo demonstra como usar o CORS (compartilhamento de recursos entre origens) para enviar uma solicitação a uma API do Google. Este exemplo não usa a biblioteca de cliente de APIs do Google para JavaScript. No entanto, mesmo que você não esteja usando a biblioteca de cliente, o guia de suporte a CORS na documentação dessa biblioteca provavelmente vai ajudar você a entender melhor essas solicitações.

Neste snippet de código, a variável access_token representa o token que você recebeu para fazer solicitações de API em nome do usuário autorizado. O exemplo completo demonstra como armazenar esse token no armazenamento local do navegador e recuperá-lo ao fazer uma solicitação de API.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/drive/v3/about?fields=user&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

Endpoints OAuth 2.0

Este exemplo de código demonstra como concluir o fluxo do OAuth 2.0 em JavaScript sem usar a biblioteca de cliente das APIs do Google para JavaScript. O código é para uma página HTML que mostra um botão para testar uma solicitação de API. Se você clicar no botão, o código vai verificar se a página armazenou um token de acesso à API no armazenamento local do navegador. Se sim, ele executa a solicitação de API. Caso contrário, ele inicia o fluxo do OAuth 2.0.

Para o fluxo OAuth 2.0, a página segue estas etapas:

1. Ele direciona o usuário ao servidor OAuth 2.0 do Google, que solicita acesso aos escopos https://www.googleapis.com/auth/drive.metadata.readonly e https://www.googleapis.com/auth/calendar.readonly.
2. Depois de conceder (ou negar) acesso a um ou mais escopos solicitados, o usuário é redirecionado para a página original, que analisa o token de acesso da string de identificador de fragmento.
3. A página verifica quais escopos o usuário concedeu acesso ao aplicativo.

4. Se o usuário tiver concedido acesso aos escopos() solicitados, a página vai usar o token de acesso para fazer a solicitação de API de exemplo.

   A solicitação da API chama o método about.get da API Drive para recuperar informações sobre a conta do Google Drive do usuário autorizado.

5. Se a solicitação for executada com sucesso, a resposta da API será registrada no console de depuração do navegador.

É possível revogar o acesso ao app na página Permissões da sua Conta do Google. O app será listado como Demonstração do OAuth 2.0 para a API Google Docs.

Para executar esse código localmente, defina valores para as variáveis YOUR_CLIENT_ID e YOUR_REDIRECT_URI que correspondem às suas credenciais de autorização. A variável YOUR_REDIRECT_URI precisa ser definida como o mesmo URL em que a página está sendo veiculada. O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou no . Se esse valor não corresponder a um URI autorizado, você vai receber um erro redirect_uri_mismatch. Seu projeto também precisa ter ativado a API apropriada para essa solicitação.

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';

  // Parse query string to see if page request is coming from OAuth 2.0 server.
  var fragmentString = location.hash.substring(1);
  var params = {};
  var regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(fragmentString)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }
  if (Object.keys(params).length > 0 && params['state']) {
    if (params['state'] == localStorage.getItem('state')) {
      localStorage.setItem('oauth2-test-params', JSON.stringify(params) );

      trySampleRequest();
    } else {
      console.log('State mismatch. Possible CSRF attack');
    }
  }

  // Function to generate a random state value
  function generateCryptoRandomState() {
    const randomValues = new Uint32Array(2);
    window.crypto.getRandomValues(randomValues);

    // Encode as UTF-8
    const utf8Encoder = new TextEncoder();
    const utf8Array = utf8Encoder.encode(
      String.fromCharCode.apply(null, randomValues)
    );

    // Base64 encode the UTF-8 data
    return btoa(String.fromCharCode.apply(null, utf8Array))
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=+$/, '');
  }

  // If there's an access token, try an API request.
  // Otherwise, start OAuth 2.0 flow.
  function trySampleRequest() {
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    if (params && params['access_token']) { 
      // User authorized the request. Now, check which scopes were granted.
      if (params['scope'].includes('https://www.googleapis.com/auth/drive.metadata.readonly')) {
        // User authorized read-only Drive activity permission.
        // Calling the APIs, etc.
        var xhr = new XMLHttpRequest();
        xhr.open('GET',
          'https://www.googleapis.com/drive/v3/about?fields=user&' +
          'access_token=' + params['access_token']);
        xhr.onreadystatechange = function (e) {
          if (xhr.readyState === 4 && xhr.status === 200) {
            console.log(xhr.response);
          } else if (xhr.readyState === 4 && xhr.status === 401) {
            // Token invalid, so prompt for user permission.
            oauth2SignIn();
          }
        };
        xhr.send(null);
      }
      else {
        // User didn't authorize read-only Drive activity permission.
        // Update UX and application accordingly
        console.log('User did not authorize read-only Drive activity permission.');
      }

      // Check if user authorized Calendar read permission.
      if (params['scope'].includes('https://www.googleapis.com/auth/calendar.readonly')) {
        // User authorized Calendar read permission.
        // Calling the APIs, etc.
        console.log('User authorized Calendar read permission.');
      }
      else {
        // User didn't authorize Calendar read permission.
        // Update UX and application accordingly
        console.log('User did not authorize Calendar read permission.');
      } 
    } else {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // create random state value and store in local storage
    var state = generateCryptoRandomState();
    localStorage.setItem('state', state);

    // Google's OAuth 2.0 endpoint for requesting an access token
    var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

    // Create element to open OAuth 2.0 endpoint in new window.
    var form = document.createElement('form');
    form.setAttribute('method', 'GET'); // Send as a GET request.
    form.setAttribute('action', oauth2Endpoint);

    // Parameters to pass to OAuth 2.0 endpoint.
    var params = {'client_id': YOUR_CLIENT_ID,
                  'redirect_uri': YOUR_REDIRECT_URI,
                  'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly',
                  'state': state,
                  'include_granted_scopes': 'true',
                  'response_type': 'token'};

    // Add form parameters as hidden input values.
    for (var p in params) {
      var input = document.createElement('input');
      input.setAttribute('type', 'hidden');
      input.setAttribute('name', p);
      input.setAttribute('value', params[p]);
      form.appendChild(input);
    }

    // Add form to page and submit it to open the OAuth 2.0 endpoint.
    document.body.appendChild(form);
    form.submit();
  }
</script>

<button onclick="trySampleRequest();">Try sample request</button>
</body></html>

Endpoints OAuth 2.0

Para adicionar escopos a um token de acesso existente, inclua o parâmetro include_granted_scopes na solicitação para o servidor OAuth 2.0 do Google.

O snippet de código a seguir demonstra como fazer isso. O snippet pressupõe que você armazenou os escopos para os quais seu token de acesso é válido no armazenamento local do navegador. O código do exemplo completo armazena uma lista de escopos para os quais o token de acesso é válido definindo a propriedade oauth2-test-params.scope no armazenamento local do navegador.

O snippet compara os escopos para os quais o token de acesso é válido com o escopo que você quer usar para uma consulta específica. Se o token de acesso não cobrir esse escopo, o fluxo do OAuth 2.0 será iniciado. Aqui, a função oauth2SignIn é a mesma fornecida na etapa 2 (e que será fornecida mais tarde no exemplo completo).

var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));

var current_scope_granted = false;
if (params.hasOwnProperty('scope')) {
  var scopes = params['scope'].split(' ');
  for (var s = 0; s < scopes.length; s++) {
    if (SCOPE == scopes[s]) {
      current_scope_granted = true;
    }
  }
}

if (!current_scope_granted) {
  oauth2SignIn(); // This function is defined elsewhere in this document.
} else {
  // Since you already have access, you can proceed with the API request.
}

Endpoints OAuth 2.0

Para revogar um token de forma programática, seu app faz uma solicitação para https://oauth2.googleapis.com/revoke e inclui o token como um parâmetro:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

O token pode ser de acesso ou de atualização. Se o token for de acesso e tiver um token de atualização correspondente, ele também será revogado.

Se a revogação for processada, o código de status HTTP da resposta será 200. Para condições de erro, um código de status HTTP 400 é retornado com um código de erro.

O snippet de JavaScript a seguir mostra como revogar um token em JavaScript sem usar a biblioteca de cliente das APIs do Google para JavaScript. Como o endpoint OAuth 2.0 do Google para revogar tokens não oferece suporte ao compartilhamento de recursos entre origens (CORS, na sigla em inglês), o código cria um formulário e o envia para o endpoint em vez de usar o método XMLHttpRequest() para postar a solicitação.

function revokeAccess(accessToken) {
  // Google's OAuth 2.0 endpoint for revoking access tokens.
  var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';

  // Create <form> element to use to POST data to the OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'post');
  form.setAttribute('action', revokeTokenEndpoint);

  // Add access token to the form so it is set as value of 'token' parameter.
  // This corresponds to the sample curl request, where the URL is:
  //      https://oauth2.googleapis.com/revoke?token={token}
  var tokenField = document.createElement('input');
  tokenField.setAttribute('type', 'hidden');
  tokenField.setAttribute('name', 'token');
  tokenField.setAttribute('value', accessToken);
  form.appendChild(tokenField);

  // Add form to page and submit it to actually revoke the token.
  document.body.appendChild(form);
  form.submit();
}