Como usar o OAuth 2.0 para aplicativos da Web do lado do cliente

Endpoints do OAuth 2.0

Gere um URL para solicitar acesso no endpoint OAuth 2.0 do Google em https://accounts.google.com/o/oauth2/v2/auth. Este endpoint pode ser acessado 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 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. O URL solicita acesso a um escopo que permite recuperar os dados do YouTube do usuário. Ele usa a autorização incremental (include_granted_scopes=true) para garantir que o novo token de acesso abranja os escopos a que o usuário concedeu acesso anteriormente ao aplicativo. Vários outros parâmetros também são definidos no exemplo.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 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 de APIs do Google para JavaScript. Como este endpoint do OAuth 2.0 não permite 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/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 do OAuth 2.0

O servidor OAuth 2.0 envia uma resposta para o redirect_uri especificado na 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 tiver sido especificado na solicitação do 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 somente leitura para visualizar metadados de arquivos no seu Google Drive:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 client_id=client_id

Depois de concluir o fluxo do OAuth 2.0, você será redirecionado para http://localhost/oauth2callback. Esse URL gerará um erro 404 NOT FOUND, a menos que sua máquina local exiba 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 do OAuth 2.0

Depois que o aplicativo recebe um token de acesso, é possível usá-lo para fazer chamadas a 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 à API incluindo um parâmetro de consulta access_token ou um valor Bearer de cabeçalho HTTP Authorization. Recomendamos usar o cabeçalho HTTP sempre que possível, porque as strings de consulta costumam ficar visíveis nos registros do servidor. Na maioria dos casos, você pode usar uma biblioteca de cliente para configurar chamadas para as APIs do Google (por exemplo, ao chamar a API de transmissão do YouTube ao vivo).

A API de transmissão do YouTube ao vivo não é compatível com o fluxo da conta de serviço. Como não há uma forma de vincular uma conta de serviço a uma conta do YouTube, as tentativas de autorizar solicitações com esse fluxo gerarão um erro NoLinkedYouTubeAccount.

É possível testar todas as APIs do Google e ver os escopos delas no OAuth 2.0 Playground.

Exemplos GET HTTP

Uma chamada para o endpoint liveBroadcasts.list (a API YouTube Live Streaming) usando o cabeçalho HTTP Authorization: Bearer pode ter a seguinte aparência: É necessário especificar seu próprio token de acesso:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Veja abaixo uma chamada para a mesma API para o usuário autenticado com o parâmetro de string de consulta access_token:

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Exemplos com curl

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

Ou, alternativamente, a opção do parâmetro da string de consulta:

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Exemplo de código JavaScript

O snippet de código abaixo demonstra como usar o Compartilhamento de recursos entre origens (CORS) 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 ao CORS na documentação da biblioteca provavelmente ajudará você a entender melhor essas solicitações.

Nesse 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/liveBroadcasts?part=id,snippet&mine=true' +
    '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 concluir o fluxo do OAuth 2.0 em JavaScript sem usar a biblioteca de cliente das APIs do Google para JavaScript. O código é de uma página HTML que exibe um botão para testar uma solicitação de API. Se você clicar no botão, o código verificará se a página armazenou um 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 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 do identificador de fragmento.

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

   Essa solicitação de API chama o método liveBroadcasts.list da API YouTube Data para recuperar uma lista de transmissões de vídeo para o canal do YouTube do usuário autorizado.

4. Se a solicitação for executada corretamente, 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 aplicativo estará listado como OAuth 2.0 Demo for Google API 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 é veiculada. O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, configurado em API Console Credentials page. Se esse valor não corresponder a um URI autorizado, você receberá um erro redirect_uri_mismatch. Seu projeto também precisa ter ativado 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/youtube/v3/liveBroadcasts?part=id,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 do OAuth 2.0

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

Para adicionar escopos a um token de acesso existente, inclua o parâmetro include_granted_scopes na sua solicitação ao 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 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 em que o token de acesso é válido com o escopo que você quer usar em determinada consulta. 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 fornecida na etapa 2 (e será fornecida mais adiante 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 do OAuth 2.0

Para revogar um token de forma programática, o 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 for um token de acesso e tiver um token de atualização correspondente, este 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 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 de APIs do Google para JavaScript. Como o endpoint OAuth 2.0 do Google para revogar tokens não é compatível com o Compartilhamento de recursos entre origens (CORS), o código cria um formulário e o envia ao 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();
}