OAuth 2.0 para aplicativos da Web do lado do cliente

Endpoints do 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 é acessível por HTTPS. conexões HTTP simples são recusadas.

O servidor de autorização do Google aceita os seguintes parâmetros de string de consulta para aplicativos de servidor:

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&
 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 OAuth 2.0 não suporta o Compartilhamento de recursos entre origens (CORS), 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',
                '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 do OAuth 2.0

O servidor OAuth 2.0 envia uma resposta para o redirect_uri especificado no 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 é retornada 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 do fragmento também contém o parâmetro token_type, que é sempre definido como Bearer e o parâmetro expires_in, que especifica do token, em segundos. Se o parâmetro state tiver sido especificado na solicitação do token de acesso, seu valor 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

É possível testar esse fluxo clicando no exemplo de URL a seguir, que solicita acesso somente leitura para visualizar metadados de arquivos no Google Drive:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.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 resultará em uma 404 NOT FOUND, a menos que sua máquina local exiba um arquivo em esse endereço. A próxima etapa fornece mais detalhes sobre as informações retornadas URI quando o usuário é redirecionado de volta para seu aplicativo.

Endpoints do OAuth 2.0

Depois que o aplicativo obtém um token de acesso, você pode usá-lo para fazer chamadas a um serviço em nome de um determinado 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 à API incluindo uma consulta access_token ou um valor Bearer do cabeçalho HTTP Authorization. Quando possível, o cabeçalho HTTP é preferível, porque as strings de consulta tendem a ser visíveis nos registros do servidor. Na maioria casos, você pode usar uma biblioteca de cliente para configurar suas chamadas para as APIs do Google (por exemplo, quando chamando a API Drive Files).

Você pode experimentar todas as APIs do Google e visualizar seus escopos em OAuth 2.0 Playground.

Exemplos GET HTTP

Uma chamada ao drive.files endpoint (a API Drive Files) usando a API 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 para o usuário autenticado com o access_token parâmetro da string de consulta:

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. Este é 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, alternativamente, a opção do parâmetro da 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 Compartilhamento de recursos entre origens (CORS) para enviar uma para 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 do cliente, a guia de suporte ao CORS na documentação da biblioteca provavelmente ajudará você para entender melhor essas solicitações.

Neste snippet de código, a variável access_token representa o token que você tem. para fazer solicitações de API em nome do usuário autorizado. A página completa example 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 do OAuth 2.0

Este exemplo de código demonstra como completar o fluxo do OAuth 2.0 em JavaScript sem usar o Biblioteca cliente de APIs do Google para JavaScript. O código é de uma página HTML que exibe um botão para tente uma solicitação de API. Se você clicar no botão, o código verificará se a página armazenou uma Token de acesso à API no armazenamento local do navegador. Nesse caso, ele executa a solicitação de API. Caso contrário, ele inicia o fluxo do OAuth 2.0.

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

1. Ele direciona o usuário para o servidor OAuth 2.0 do Google, que solicita acesso à escopo https://www.googleapis.com/auth/drive.metadata.readonly.
2. Após conceder (ou negar) acesso a um ou mais escopos solicitados, o usuário é redirecionado para página original, que analisa o token de acesso a partir da string do identificador de fragmento.

3. A página usa o token de acesso para fazer o exemplo de solicitação de API.

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

4. Se a solicitação for executada com êxito, a resposta da API será registrada no arquivo de depuração do navegador no console do Google Cloud.

É possível revogar o acesso ao app pela página Permissões para sua Conta do Google. O aplicativo estará listado como OAuth 2.0 Demo for Google API Docs.

Para executar este código localmente, você precisa definir valores para o YOUR_CLIENT_ID e YOUR_REDIRECT_URI variáveis que correspondem à sua credenciais de autorização. A variável YOUR_REDIRECT_URI deve ser definido como o mesmo URL em que a página é veiculada. O valor precisa corresponder exatamente a os URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou no API Console Credentials page. Se esse valor não corresponder a um URI autorizado, você vai receber um redirect_uri_mismatch erro. Seu projeto também deve ter ativou a API apropriada para a 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']) {
      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 {
      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',
                  '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 do OAuth 2.0

Para adicionar escopos a um token de acesso atual, inclua o include_granted_scopes na sua solicitação para o servidor OAuth 2.0 do Google.

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

O snippet compara os escopos nos 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 abranger esse escopo, o fluxo do OAuth 2.0 será iniciado. Aqui, a função oauth2SignIn é a mesma que foi fornecida no etapa 2 (e é fornecida mais tarde na etapa exemplo).

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 do OAuth 2.0

Para revogar programaticamente um token, seu aplicativo 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 um token de acesso ou de atualização. Se o token for de acesso e tiver um token de atualização correspondente, o token de atualização também será revogado.

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

O snippet de JavaScript a seguir mostra como revogar um token em JavaScript sem usar a propriedade Biblioteca cliente de APIs do Google para JavaScript. Como o endpoint OAuth 2.0 do Google para revogação não oferece suporte ao Compartilhamento de recursos entre origens (CORS), o código cria um formulário e envia o formulário no endpoint em vez de usar o método XMLHttpRequest() para publicar 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();
}