Como usar o OAuth 2.0 para aplicativos da Web JavaScript

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

O URL de exemplo abaixo solicita acesso off-line (access_type=offline) a um escopo que permite acesso para visualizar a conta do YouTube do usuário. Ele usa a autorização incremental para garantir que o novo token de acesso abranja todos os escopos aos quais o usuário concedeu acesso ao aplicativo anteriormente. O URL também define valores para os parâmetros redirect_uri, response_type e client_id obrigatórios, bem como para o parâmetro state. O URL contém quebras de linha e espaços para facilitar a leitura.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 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/youtube.force-ssl',
                '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%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 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 exemplo do token de acesso a seguir indica que o usuário concedeu ao seu aplicativo permissão para ver, editar e excluir permanentemente vídeos, classificações, comentários e legendas do YouTube do usuário:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
    "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 Data do YouTube.

A API YouTube Data só oferece suporte a contas de serviço para proprietários de conteúdo do YouTube que possuem e gerenciam vários canais do YouTube, como gravadoras e estúdios de cinema.

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 youtube.channels (a API YouTube Data) usando o cabeçalho HTTP Authorization: Bearer pode ser semelhante ao seguinte. É necessário especificar seu próprio token de acesso:

GET /youtube/v3/channels?part=snippet&mine=true 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/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

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/youtube/v3/channels?part=snippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

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/youtube/v3/channels?part=snippet&mine=true&' +
    '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 ao escopo https://www.googleapis.com/auth/youtube.force-ssl.
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.

   Essa solicitação de API chama o método channels.list da API Data do YouTube para extrair dados sobre o canal 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 API Console Credentials page. 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']) { 
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true&' +
          '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/youtube.force-ssl',
                  '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

Neste exemplo, o aplicativo de chamada solicita acesso para extrair os dados do YouTube Analytics do usuário, além de qualquer outro acesso que o usuário já tenha concedido ao aplicativo.

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/youtube.force-ssl';
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();
}