OAuth 2.0 para aplicativos da Web do lado do cliente

Este documento explica como implementar a autorização OAuth 2.0 para acessar APIs do Google a partir de um aplicativo da web JavaScript. OAuth 2.0 permite que os usuários compartilhem dados específicos com um aplicativo, mantendo seus nomes de usuário, senhas e outras informações privadas. Por exemplo, um aplicativo pode usar OAuth 2.0 para obter permissão dos usuários para armazenar arquivos em seus Google Drives.

Este fluxo OAuth 2.0 é chamado de fluxo concessão implícita. Ele é projetado para aplicativos que acessam APIs apenas enquanto o usuário está presente no aplicativo. Esses aplicativos não podem armazenar informações confidenciais.

Nesse fluxo, seu aplicativo abre um URL do Google que usa parâmetros de consulta para identificar seu aplicativo e o tipo de acesso à API que o aplicativo requer. Você pode abrir o URL na janela do navegador atual ou em um pop-up. O usuário pode se autenticar no Google e conceder as permissões solicitadas. Em seguida, o Google redireciona o usuário de volta ao seu aplicativo. O redirecionamento inclui um token de acesso, que seu aplicativo verifica e usa para fazer solicitações de API.

Pré-requisitos

Ative APIs para seu projeto

Qualquer aplicativo que chama APIs do Google precisa para permitir que essas APIs no API Console.

Para habilitar uma API para seu projeto:

  1. Open the API Library na Google API Console.
  2. If prompted, select a project, or create a new one.
  3. O API Library listas de todas as APIs disponíveis, agrupados por família de produtos e popularidade. Se a API que você deseja ativar não é visível na lista, o uso de busca para encontrá-lo, ou clique em Ver Todos na família de produtos a que pertence.
  4. Selecione a API que você deseja ativar, em seguida, clique no botão Ativar.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Crie credenciais de autorização

Qualquer aplicativo que usa OAuth 2.0 para acessar APIs do Google deve ter credenciais de autorização que identificam o aplicativo para o servidor OAuth 2.0 do Google. As etapas a seguir explicam como criar credenciais para seu projeto. Seus aplicativos podem então usar as credenciais para acessar APIs que você habilitou para aquele projeto.

  1. Go to the Credentials page.
  2. Clique em Criar credenciais> OAuth ID do cliente.
  3. Selecione o tipo de aplicação aplicação Web.
  4. Complete a forma. Os aplicativos que usam JavaScript para tornar autorizada origens Google solicitações de API devem especificar autorizados de JavaScript. As origens identificam os domínios dos quais seu aplicativo pode enviar solicitações ao servidor OAuth 2.0. Estas origens devem aderir a regras de validação do Google .

Identificar escopos de acesso

Os escopos permitem que seu aplicativo solicite acesso apenas aos recursos de que precisa, ao mesmo tempo que permite que os usuários controlem a quantidade de acesso que concedem ao seu aplicativo. Assim, pode haver uma relação inversa entre o número de escopos solicitados e a probabilidade de obtenção do consentimento do usuário.

Antes de começar a implementar a autorização OAuth 2.0, recomendamos que você identifique os escopos que seu aplicativo precisará de permissão para acessar.

O 2.0 API Scopes OAuth documento contém uma lista completa de escopos que você pode usar para acessar o Google APIs.

Obtenção de tokens de acesso OAuth 2.0

As etapas a seguir mostram como seu aplicativo interage com o servidor OAuth 2.0 do Google para obter o consentimento de um usuário para realizar uma solicitação de API em nome do usuário. Seu aplicativo deve ter esse consentimento antes de executar uma solicitação de API do Google que requer autorização do usuário.

Etapa 1: configurar o objeto cliente

Se você estiver usando biblioteca cliente das APIs do Google para JavaScript para lidar com o fluxo OAuth 2.0, o primeiro passo é configurar os gapi.auth2 e gapi.client objetos. Esses objetos permitem que seu aplicativo obtenha autorização do usuário e faça solicitações de API autorizadas.

O objeto cliente identifica os escopos para os quais seu aplicativo está solicitando permissão de acesso. Esses valores informam a tela de consentimento que o Google exibe para o usuário.

Biblioteca cliente JS

A biblioteca cliente JavaScript simplifica vários aspectos do processo de autorização:

  1. Ele cria o URL de redirecionamento para o servidor de autorização do Google e fornece um método para direcionar o usuário para esse URL.
  2. Ele lida com o redirecionamento desse servidor de volta para o seu aplicativo.
  3. Ele valida o token de acesso retornado pelo servidor de autorização.
  4. Ele armazena o token de acesso que o servidor de autorização envia para seu aplicativo e o recupera quando seu aplicativo subsequentemente faz chamadas de API autorizadas.

O fragmento de código seguinte foi extraído a partir do exemplo completo mostrado mais adiante neste documento. Esse código inicializa o gapi.client objeto, que a sua aplicação seria mais tarde usar para fazer chamadas de API. Quando esse objeto é criado, o gapi.auth2 objeto, que a aplicação utiliza para verificar e monitorar o status de autorização do usuário, também é inicializado.

A chamada para gapi.client.init especifica os seguintes campos:

  • Os apiKey e clientId valores especificar credenciais de autorização da sua aplicação. Como discutido no credenciais de autorização criando secção, estes valores podem ser obtidos no API Console. Note que o clientId é necessária se o aplicativo faz solicitações de API autorizados. Os aplicativos que fazem apenas solicitações não autorizadas podem apenas especificar uma chave de API.
  • O scope campo especifica uma lista delimitada por espaços de acesso escopos que correspondem aos recursos que seu aplicativo pode acessar em nome do usuário. Esses valores informam a tela de consentimento que o Google exibe para o usuário.

    Recomendamos que seu aplicativo solicite acesso aos escopos de autorização no contexto, sempre que possível. Ao solicitar o acesso aos dados do usuário no contexto, através de autorização incrementais , você ajuda os usuários a compreender mais facilmente por que seu aplicativo precisa de acesso que está solicitando.

  • Os discoveryDocs identifica campo uma lista de documentos API descoberta de que seus usos de aplicativos. Um documento de descoberta descreve a superfície de uma API, incluindo seus esquemas de recursos, e a biblioteca cliente JavaScript usa essas informações para gerar métodos que os aplicativos podem usar. Neste exemplo, o código recupera o documento de descoberta para a versão 3 da API do Google Drive.

Após os gapi.client.init concluída chamada, o código define a GoogleAuth variável para identificar o objeto Google Auth. Por fim, o código define um ouvinte que chama uma função quando o status de login do usuário muda. (Essa função não está definida no snippet.)

var GoogleAuth; // Google Auth object.
function initClient() {
  gapi.client.init({
      'apiKey': 'YOUR_API_KEY',
      'clientId': 'YOUR_CLIENT_ID',
      'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
      'discoveryDocs': ['https://www.googleapis.com/discovery/v1/apis/drive/v3/rest']
  }).then(function () {
      GoogleAuth = gapi.auth2.getAuthInstance();

      // Listen for sign-in state changes.
      GoogleAuth.isSignedIn.listen(updateSigninStatus);
  });
}

Endpoints OAuth 2.0

Se você estiver acessando diretamente os pontos de extremidade OAuth 2.0, prossiga para a próxima etapa.

Etapa 2: Redirecionar para o servidor OAuth 2.0 do Google

Para solicitar permissão para acessar os dados de um usuário, redirecione o usuário para o servidor OAuth 2.0 do Google.

Biblioteca cliente JS

Chame o GoogleAuth.signIn() método para direcionar o usuário para o servidor de autorização do Google.

GoogleAuth.signIn();

Na prática, o aplicativo pode definir um valor booleano para determinar se deve chamar o signIn() método antes de tentar fazer uma chamada de API.

O snippet de código abaixo demonstra como você iniciaria o fluxo de autorização do usuário. Observe os seguintes pontos sobre o snippet:

  • O GoogleAuth objeto referenciado no código é a mesma que a variável global definida no trecho de código no passo 1 .

  • O updateSigninStatus função é um ouvinte que escuta para alterações ao status de autorização do usuário. Seu papel como um ouvinte também foi definida no trecho de código na etapa 1:
    GoogleAuth.isSignedIn.listen(updateSigninStatus);
  • O snippet define duas variáveis ​​globais adicionais:

    • isAuthorized é uma variável booleano que indica se o usuário já está conectado. Este valor pode ser definido quando as cargas de aplicativos e atualizada se o usuário assina dentro ou fora do aplicativo.

      Neste trecho, o sendAuthorizedApiRequest o valor da variável função verifica para determinar se o aplicativo deve tentar uma solicitação da API que requer autorização ou solicitar ao usuário para autorizar o aplicativo.

    • currentApiRequest é um objeto que armazena detalhes sobre o último pedido API que o usuário tentou. O valor do objeto é definido quando o aplicativo chama o sendAuthorizedApiRequest função.

      Se o usuário autorizou o aplicativo, a solicitação é executada imediatamente. Caso contrário, a função redireciona o usuário para login. Depois do usuário se, a updateSignInStatus função chama sendAuthorizedApiRequest , passando o mesmo pedido que foi tentada antes do fluxo de autorização começou.

var isAuthorized;
var currentApiRequest;

/**
 * Store the request details. Then check to determine whether the user
 * has authorized the application.
 *   - If the user has granted access, make the API request.
 *   - If the user has not granted access, initiate the sign-in flow.
 */
function sendAuthorizedApiRequest(requestDetails) {
  currentApiRequest = requestDetails;
  if (isAuthorized) {
    // Make API request
    // gapi.client.request(requestDetails)

    // Reset currentApiRequest variable.
    currentApiRequest = {};
  } else {
    GoogleAuth.signIn();
  }
}

/**
 * Listener called when user completes auth flow. If the currentApiRequest
 * variable is set, then the user was prompted to authorize the application
 * before the request executed. In that case, proceed with that API request.
 */
function updateSigninStatus(isSignedIn) {
  if (isSignedIn) {
    isAuthorized = true;
    if (currentApiRequest) {
      sendAuthorizedApiRequest(currentApiRequest);
    }
  } else {
    isAuthorized = false;
  }
}

Endpoints OAuth 2.0

Gerar um URL para solicitar acesso de endpoint OAuth 2.0 do Google em https://accounts.google.com/o/oauth2/v2/auth . Este ponto de extremidade 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:

Parâmetros
client_id Obrigatório

O ID do cliente para seu aplicativo. Você pode encontrar este valor no API ConsoleCredentials page.

redirect_uri Obrigatório

Determina para onde o servidor de API redireciona o usuário depois que ele conclui o fluxo de autorização. O valor deve corresponder exatamente um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou na do seu cliente API ConsoleCredentials page. Se este valor não corresponder a um URI de redirecionamento autorizado para o fornecido client_id você receberá um redirect_uri_mismatch erro.

Note que o http ou https esquema, caso, e à direita barra ( ' / ') deve toda a partida.

response_type Obrigatório

Aplicações JavaScript precisa definir o valor do parâmetro de token . Este valor instrui o Servidor de Autorização Google para retornar o token de acesso como um name=value par no identificador de fragmento do URI ( # ) para o qual o usuário é redirecionado após a conclusão do processo de autorização.

scope Obrigatório

Uma lista de escopos delimitada por espaço que identifica os recursos que seu aplicativo pode acessar em nome do usuário. Esses valores informam a tela de consentimento que o Google exibe para o usuário.

Os escopos permitem que seu aplicativo solicite acesso apenas aos recursos de que precisa, ao mesmo tempo que permite que os usuários controlem a quantidade de acesso que concedem ao seu aplicativo. Assim, existe uma relação inversa entre o número de escopos solicitados e a probabilidade de obtenção do consentimento do usuário.

Recomendamos que seu aplicativo solicite acesso aos escopos de autorização no contexto sempre que possível. Ao solicitar o acesso aos dados do usuário no contexto, através de autorização incrementais , você ajuda os usuários a compreender mais facilmente por que seu aplicativo precisa de acesso que está solicitando.

state Recomendado

Especifica qualquer valor de string que seu aplicativo usa para manter o estado entre sua solicitação de autorização e a resposta do servidor de autorização. O servidor retorna o valor exato que você enviar como um name=value par no identificador de fragmento de URL ( # ) do redirect_uri após o usuário consentir ou nega pedido de acesso do seu aplicativo.

Você pode usar esse parâmetro para vários fins, como direcionar o usuário ao recurso correto em seu aplicativo, enviar nonces e atenuar a falsificação de solicitação entre sites. Desde a sua redirect_uri pode ser adivinhada, usando um state valor pode aumentar a sua garantia de que uma conexão de entrada é o resultado de uma solicitação de autenticação. Se você gerar uma string aleatória ou codificar o hash de um cookie ou outro valor que capture o estado do cliente, poderá validar a resposta para garantir adicionalmente que a solicitação e a resposta foram originadas no mesmo navegador, fornecendo proteção contra ataques como entre sites pedido de falsificação. Veja o OpenID Ligação documentação para um exemplo de como criar e confirmar um state token.

include_granted_scopes Opcional

Permite que os aplicativos usem autorização incremental para solicitar acesso a escopos adicionais no contexto. Se você definir o valor deste parâmetro para true e o pedido de autorização for concedida, então o novo token de acesso também irá cobrir quaisquer âmbitos ao qual o usuário anteriormente concedidas ao acesso ao aplicativo. Veja a autorização incrementais seção para exemplos.

login_hint Opcional

Se seu aplicativo souber qual usuário está tentando autenticar, ele pode usar este parâmetro para fornecer uma dica ao servidor de autenticação do Google. O servidor usa a dica para simplificar o fluxo de login, preenchendo previamente o campo de e-mail no formulário de login ou selecionando a sessão multi-login apropriada.

Defina o valor do parâmetro para um endereço de e-mail ou sub identificador, que é equivalente ao do usuário do Google ID.

prompt Opcional

Uma lista delimitada por espaço e com distinção entre maiúsculas e minúsculas de prompts para apresentar ao usuário. Se você não especificar este parâmetro, o usuário será solicitado apenas na primeira vez que seu projeto solicitar acesso. Veja Solicitação re-consentimento para mais informações.

Os valores possíveis são:

none Não exiba nenhuma tela de autenticação ou consentimento. Não deve ser especificado com outros valores.
consent Solicite consentimento do usuário.
select_account Peça ao usuário para selecionar uma conta.

Amostra 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 de solicitação, redirecione o usuário para ele.

Amostra de código JavaScript

O seguinte snippet de JavaScript mostra como iniciar o fluxo de autorização em JavaScript sem usar a biblioteca cliente de APIs do Google para JavaScript. Como este ponto de extremidade OAuth 2.0 não suporta Compartilhamento de Recursos de Origem Cruzada (CORS), o snippet cria um formulário que abre a solicitação para esse ponto de extremidade.

/*
 * 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();
}

Etapa 3: o Google solicita consentimento do usuário

Nesta etapa, o usuário decide se concederá ao aplicativo o acesso solicitado. Nesse estágio, o Google exibe uma janela de consentimento que mostra o nome de seu aplicativo e os serviços de API do Google aos quais está solicitando permissão de acesso com as credenciais de autorização do usuário e um resumo dos escopos de acesso a serem concedidos. O usuário pode, então, consentir em conceder acesso a um ou mais escopos solicitados por seu aplicativo ou recusar a solicitação.

Seu aplicativo não precisa fazer nada neste estágio, pois aguarda a resposta do servidor OAuth 2.0 do Google indicando se algum acesso foi concedido. Essa resposta é explicada na etapa seguinte.

Erros

As solicitações para o ponto de extremidade de autorização OAuth 2.0 do Google podem exibir mensagens de erro voltadas para o usuário em vez dos fluxos de autenticação e autorização esperados. Códigos de erro comuns e soluções sugeridas estão listados abaixo.

admin_policy_enforced

A Conta do Google não pode autorizar um ou mais escopos solicitados devido às políticas do administrador do Google Workspace. Veja o artigo de ajuda do Google Workspace admin Controle quais de terceiros e aplicativos internos acessar os dados do Google Workspace para mais informações sobre como um administrador pode restringir o acesso a todos os escopos ou escopos sensíveis e restritos até que o acesso é explicitamente concedido ao seu ID do cliente OAuth.

disallowed_useragent

O ponto final de autorização é apresentada dentro de um agente de utilizador incorporado anulado por do Google Regulamentos OAuth 2.0 .

Android

Desenvolvedores Android pode encontrar essa mensagem de erro ao abrir pedidos de autorização emandroid.webkit.WebView . Desenvolvedores deve usar bibliotecas Android, como o login do Google para Android ou do OpenID Foundation AppAuth para Android .

Os desenvolvedores da web podem encontrar esse erro quando um aplicativo Android abre um link geral da web em um user-agent incorporado e um usuário navega para o endpoint de autorização OAuth 2.0 do Google a partir do seu site. Os desenvolvedores devem permitir ligações gerais para abrir no manipulador link padrão do sistema operacional, que inclui tanto Android App Ligações manipuladores ou o aplicativo navegador padrão. O Android personalizado Tabs biblioteca também é uma opção suportada.

iOS

iOS e MacOS desenvolvedores podem encontrar esse erro ao abrir pedidos de autorização emWKWebView . Desenvolvedores deve usar bibliotecas iOS, como o login do Google para iOS ou do OpenID Foundation AppAuth para iOS .

Os desenvolvedores da web podem encontrar esse erro quando um aplicativo iOS ou macOS abre um link geral da web em um user-agent integrado e um usuário navega para o endpoint de autorização OAuth 2.0 do Google a partir do seu site. Os desenvolvedores devem permitir ligações gerais para abrir no manipulador link padrão do sistema operacional, que inclui tanto Universal Ligações manipuladores ou o aplicativo navegador padrão. OSFSafariViewController biblioteca também é uma opção suportada.

org_internal

O ID do cliente OAuth no pedido é parte de um projeto limitando o acesso a contas do Google em um determinado Organização Google Cloud . Para mais informações sobre esta opção de configuração ver o tipo de usuário seção no Configurando o consentimento OAuth tela de ajuda artigo.

origin_mismatch

O esquema, domínio e / ou porta do JavaScript que origina a solicitação de autorização pode não corresponder a um URI de origem JavaScript autorizado registrado para o ID do cliente OAuth. Revisão autorizada origens JavaScript na Google API ConsoleCredentials page.

redirect_uri_mismatch

O redirect_uri passados na solicitação de autorização não coincide com um redirecionamento autorizado URI para o ID do cliente OAuth. Revisão autorizada URIs de redirecionamento na Google API Console Credentials page.

O esquema, domínio e / ou porta do JavaScript que origina a solicitação de autorização pode não corresponder a um URI de origem JavaScript autorizado registrado para o ID do cliente OAuth. Revisão autorizada origens JavaScript na Google API Console Credentials page.

Etapa 4: lidar com a resposta do servidor OAuth 2.0

Biblioteca cliente JS

A biblioteca cliente JavaScript lida com a resposta do servidor de autorização do Google. Se você definir um ouvinte para monitorar as alterações no estado de entrada do usuário atual, essa função será chamada quando o usuário conceder o acesso solicitado ao aplicativo.

OAuth 2.0 Endpoints

O servidor OAuth 2.0 envia uma resposta para o redirect_uri especificado em seu pedido de acesso token.

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 mensagem de erro é retornado no fragmento 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 access_token parâmetro, a cadeia fragmento também contém a token_type parâmetro, que é sempre definido como Bearer , e o expires_in parâmetro, que especifica o tempo de vida do símbolo, em segundos. Se o state parâmetro foi especificado no token de acesso do pedido, o seu valor também está incluído na resposta.

  • Uma resposta de erro:
    https://oauth2.example.com/callback#error=access_denied

Amostra de resposta do servidor OAuth 2.0

Você pode testar esse fluxo clicando no seguinte URL de amostra, que solicita acesso somente leitura para visualizar metadados de arquivos em seu 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 completar o fluxo OAuth 2.0, você será redirecionado para http://localhost/oauth2callback . Essa URL irá produzir um 404 NOT FOUND erro a menos que sua máquina local acontece a servir 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 ao seu aplicativo.

Chamando APIs do Google

Biblioteca cliente JS

Depois que seu aplicativo obtém um token de acesso, você pode usar a biblioteca cliente JavaScript para fazer solicitações de API em nome do usuário. A biblioteca cliente gerencia o token de acesso para você, e você não precisa fazer nada especial para enviá-lo na solicitação.

A biblioteca cliente oferece suporte a duas maneiras de chamar métodos de API. Se você carregou um documento de descoberta, a API definirá funções específicas do método para você. Você também pode usar o gapi.client.request função para chamar um método de API. Os dois trechos a seguir demonstram estas opções para a unidade de API about.get método.

// Example 1: Use method-specific function
var request = gapi.client.drive.about.get({'fields': 'user'});

// Execute the API request.
request.execute(function(response) {
  console.log(response);
});


// Example 2: Use gapi.client.request(args) function
var request = gapi.client.request({
  'method': 'GET',
  'path': '/drive/v3/about',
  'params': {'fields': 'user'}
});
// Execute the API request.
request.execute(function(response) {
  console.log(response);
});

OAuth 2.0 Endpoints

Depois que seu aplicativo obtém um token de acesso, você pode usar o token para fazer chamadas para uma API do Google em nome de uma determinada conta de usuário se o (s) escopo (s) de acesso exigido pela API tiver sido concedido. Para fazer isso, inclua o token de acesso em uma solicitação para a API, incluindo tanto uma access_token parâmetro de consulta ou um Authorization HTTP cabeçalho Bearer de valor. Quando possível, o cabeçalho HTTP é preferível, porque as sequências de consulta tendem a ser visíveis nos logs do servidor. Na maioria dos casos, você pode usar uma biblioteca cliente para configurar suas chamadas para APIs do Google (por exemplo, quando chamar a API arquivos da unidade ).

Você pode experimentar todo o Google APIs e exibir seus escopos no OAuth 2.0 Playground .

Exemplos HTTP GET

Uma chamada para a drive.files endpoint (a API Arquivos Drive) utilizando o Authorization: Bearer cabeçalho HTTP pode parecer o seguinte. Observe que você precisa especificar seu próprio token de acesso:

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

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

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

curl exemplos

Você pode testar esses comandos com a curl aplicativo de linha de comando. Aqui está 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 de parâmetro de string de consulta:

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

Amostra de código JavaScript

O trecho de código abaixo demonstra como usar CORS (Compartilhamento de recursos de origem cruzada) para enviar uma solicitação a uma API do Google. Este exemplo não usa a biblioteca cliente de APIs do Google para JavaScript. No entanto, mesmo se você não estiver usando a biblioteca cliente, os CORS apoiar guia na documentação da biblioteca provavelmente irá ajudá-lo a entender melhor essas solicitações.

Neste trecho de código, o access_token variável representa o token de ter obtido 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 da 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);

Exemplo completo

Biblioteca cliente JS

Amostra de demonstração de código

Esta seção contém uma demonstração de trabalho do exemplo de código a seguir para demonstrar como o código se comporta em um aplicativo real. Depois de autorizar o aplicativo, ele será listado entre os aplicativos conectados à sua Conta do Google . O aplicativo é chamado OAuth 2.0 Demo for Google API Docs. Da mesma forma, se você revogar o acesso e atualizar a página, o aplicativo não será mais listado.

Note-se que este aplicativo solicita acesso ao https://www.googleapis.com/auth/drive.metadata.readonly escopo. O acesso é solicitado apenas para demonstrar como iniciar o fluxo OAuth 2.0 em um aplicativo JavaScript. Este aplicativo não faz solicitações de API.

Amostra de código JavaScript

Conforme mostrado acima, este exemplo de código é para uma página (um aplicativo) que carrega a biblioteca cliente de APIs do Google para JavaScript e inicia o fluxo OAuth 2.0. A página exibe:

  • Um botão que permite ao usuário fazer login no aplicativo. Se o usuário não autorizou anteriormente o aplicativo, o aplicativo inicia o fluxo OAuth 2.0.
  • Dois botões que permitem ao usuário sair do aplicativo ou revogar o acesso concedido anteriormente ao aplicativo. Se você sair de um aplicativo, não revogou o acesso concedido ao aplicativo. Você precisará fazer login novamente antes que o aplicativo possa fazer outras solicitações autorizadas em seu nome, mas não será necessário conceder acesso novamente na próxima vez que usar o aplicativo. No entanto, se você revogar o acesso, precisará concedê-lo novamente.

Você também pode revogar o acesso ao aplicativo através da Permissão página para a sua Conta Google. O aplicativo é listado como OAuth 2.0 Demo for Google API Docs.

<script>
  var GoogleAuth;
  var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
  function handleClientLoad() {
    // Load the API's client and auth2 modules.
    // Call the initClient function after the modules load.
    gapi.load('client:auth2', initClient);
  }

  function initClient() {
    // In practice, your app can retrieve one or more discovery documents.
    var discoveryUrl = 'https://www.googleapis.com/discovery/v1/apis/drive/v3/rest';

    // Initialize the gapi.client object, which app uses to make API requests.
    // Get API key and client ID from API Console.
    // 'scope' field specifies space-delimited list of access scopes.
    gapi.client.init({
        'apiKey': 'YOUR_API_KEY',
        'clientId': 'YOUR_CLIENT_ID',
        'discoveryDocs': [discoveryUrl],
        'scope': SCOPE
    }).then(function () {
      GoogleAuth = gapi.auth2.getAuthInstance();

      // Listen for sign-in state changes.
      GoogleAuth.isSignedIn.listen(updateSigninStatus);

      // Handle initial sign-in state. (Determine if user is already signed in.)
      var user = GoogleAuth.currentUser.get();
      setSigninStatus();

      // Call handleAuthClick function when user clicks on
      //      "Sign In/Authorize" button.
      $('#sign-in-or-out-button').click(function() {
        handleAuthClick();
      });
      $('#revoke-access-button').click(function() {
        revokeAccess();
      });
    });
  }

  function handleAuthClick() {
    if (GoogleAuth.isSignedIn.get()) {
      // User is authorized and has clicked "Sign out" button.
      GoogleAuth.signOut();
    } else {
      // User is not signed in. Start Google auth flow.
      GoogleAuth.signIn();
    }
  }

  function revokeAccess() {
    GoogleAuth.disconnect();
  }

  function setSigninStatus() {
    var user = GoogleAuth.currentUser.get();
    var isAuthorized = user.hasGrantedScopes(SCOPE);
    if (isAuthorized) {
      $('#sign-in-or-out-button').html('Sign out');
      $('#revoke-access-button').css('display', 'inline-block');
      $('#auth-status').html('You are currently signed in and have granted ' +
          'access to this app.');
    } else {
      $('#sign-in-or-out-button').html('Sign In/Authorize');
      $('#revoke-access-button').css('display', 'none');
      $('#auth-status').html('You have not authorized this app or you are ' +
          'signed out.');
    }
  }

  function updateSigninStatus() {
    setSigninStatus();
  }
</script>

<button id="sign-in-or-out-button"
        style="margin-left: 25px">Sign In/Authorize</button>
<button id="revoke-access-button"
        style="display: none; margin-left: 25px">Revoke access</button>

<div id="auth-status" style="display: inline; padding-left: 25px"></div><hr>

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script async defer src="https://apis.google.com/js/api.js"
        onload="this.onload=function(){};handleClientLoad()"
        onreadystatechange="if (this.readyState === 'complete') this.onload()">
</script>

OAuth 2.0 Endpoints

Este exemplo de código demonstra como concluir o fluxo do OAuth 2.0 em JavaScript sem usar a biblioteca cliente de APIs do Google para JavaScript. O código é para uma página HTML que exibe um botão para tentar uma solicitação de API. Se você clicar no botão, o código verifica se a página armazenou um token de acesso da API no armazenamento local do seu navegador. Nesse caso, ele executa a solicitação da 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 https://www.googleapis.com/auth/drive.metadata.readonly escopo.
  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 identificadora do fragmento.
  3. A página usa o token de acesso para fazer a amostra de solicitação da API.

    O pedido chamadas de API do Drive API about.get método 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 console de depuração do navegador.

Você pode revogar o acesso ao aplicativo através da Permissão página para a sua Conta Google. O aplicativo será listado como OAuth 2.0 Demo for Google API Docs.

Para executar este código localmente, você precisa definir valores para os YOUR_CLIENT_ID e YOUR_REDIRECT_URI variáveis que correspondem à sua credenciais de autorização . O YOUR_REDIRECT_URI variável deve ser definido para o mesmo URL onde a página está sendo servido. O valor deve corresponder exatamente um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou na API Console Credentials page. Se este valor não corresponder a um URI autorizado, você vai ter um redirect_uri_mismatch erro. Seu projeto também deve ter habilitado a API apropriada para este pedido.

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
  var fragmentString = location.hash.substring(1);

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

  // 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() {
    // 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': 'try_sample_request',
                  '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>

Regras de validação de origem de JavaScript

O Google aplica as seguintes regras de validação às origens do JavaScript para ajudar os desenvolvedores a manter seus aplicativos seguros. Suas origens de JavaScript devem obedecer a essas regras. Veja RFC 3986 seção 3 para a definição de domínio, host e esquema, mencionado abaixo.

Regras de validação
Esquema

As origens do JavaScript devem usar o esquema HTTPS, não HTTP simples. URIs de host local (incluindo URIs de endereço IP de host local) estão isentos desta regra.

Hospedeiro

Os hosts não podem ser endereços IP brutos. Os endereços IP do host local estão isentos desta regra.

Domínio
  • TLDs de acolhimento ( Domínios de Alto Nível ) deve pertencer à lista de sufixos pública .
  • Domínios host não pode ser “googleusercontent.com” .
  • Origens de JavaScript não pode conter domínios shortener URL (por exemplo, goo.gl ) a menos que o aplicativo possui o domínio.
  • Informação de usuário

    As origens do JavaScript não podem conter o subcomponente userinfo.

    Caminho

    As origens do JavaScript não podem conter o componente do caminho.

    Consulta

    As origens do JavaScript não podem conter o componente de consulta.

    Fragmento

    As origens do JavaScript não podem conter o componente do fragmento.

    Personagens As origens do JavaScript não podem conter certos caracteres, incluindo:
    • Caracteres curinga ( '*' )
    • Caracteres ASCII não imprimíveis
    • Codificações de porcentagem inválidas (qualquer codificação de porcentagem que não siga a forma de codificação de URL de um sinal de porcentagem seguido por dois dígitos hexadecimais)
    • Caracteres nulos (um carácter nulo codificado, por exemplo, %00 , %C0%80 )

    Autorização incremental

    No protocolo OAuth 2.0, seu aplicativo solicita autorização para acessar recursos, que são identificados por escopos. É considerada uma prática recomendada para a experiência do usuário solicitar autorização para recursos no momento em que você precisa deles. Para habilitar essa prática, o servidor de autorização do Google oferece suporte para autorização incremental. Este recurso permite solicitar escopos conforme necessário e, se o usuário conceder permissão para o novo escopo, retorna um código de autorização que pode ser trocado por um token contendo todos os escopos que o usuário concedeu ao projeto.

    Por exemplo, um aplicativo que permite que as pessoas experimentem faixas de música e criem mixagens pode precisar de poucos recursos no momento do login, talvez nada mais do que o nome da pessoa que faz login. No entanto, salvar uma mixagem completa exigiria acesso ao Google Drive . A maioria das pessoas acharia natural se o acesso ao Google Drive fosse solicitado apenas no momento em que o aplicativo realmente precisasse.

    Neste caso, a inscrição no tempo o aplicativo pode solicitar o openid e profile escopos para realizar login básico, e depois solicitar o https://www.googleapis.com/auth/drive.file escopo no momento da o primeiro pedido para salvar um mix.

    As seguintes regras se aplicam a um token de acesso obtido de uma autorização incremental:

    • O token pode ser usado para acessar recursos correspondentes a qualquer um dos escopos incluídos na nova autorização combinada.
    • Quando você usa o token de atualização para a autorização combinados para obter um token de acesso, o token de acesso representa a autorização combinado e pode ser usado para qualquer um dos scope valores incluídos na resposta.
    • A autorização combinada inclui todos os escopos que o usuário concedeu ao projeto de API, mesmo se as concessões foram solicitadas de clientes diferentes. Por exemplo, se um usuário concedeu acesso a um escopo usando um cliente de desktop do aplicativo e, em seguida, concedeu outro escopo ao mesmo aplicativo por meio de um cliente móvel, a autorização combinada incluiria os dois escopos.
    • Se você revogar um token que representa uma autorização combinada, o acesso a todos os escopos dessa autorização em nome do usuário associado será revogado simultaneamente.

    Os exemplos de código abaixo mostram como adicionar escopos a um token de acesso existente. Essa abordagem permite que seu aplicativo evite ter que gerenciar vários tokens de acesso.

    Biblioteca cliente JS

    Para adicionar escopos a um token de acesso existente, chamar o GoogleUser.grant(options) método. As options objeto identifica os âmbitos adicionais para a qual você deseja conceder acesso.

    // Space-separated list of additional scope(s) you are requesting access to.
    // This code adds read-only access to the user's calendars via the Calendar API.
    var NEW_SCOPES = 'https://www.googleapis.com/auth/calendar.readonly';
    
    // Retrieve the GoogleUser object for the current user.
    var GoogleUser = GoogleAuth.currentUser.get();
    GoogleUser.grant({'scope': NEW_SCOPES});

    Endpoints OAuth 2.0

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

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

    O snippet compara os escopos para os quais o token de acesso é válido com o escopo que você deseja 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, o oauth2SignIn função é a mesma que a que foi fornecida no passo 2 (e que é fornecido mais adiante no exemplo completa ).

    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.
    }

    Revogando um token

    Em alguns casos, um usuário pode desejar revogar o acesso concedido a um aplicativo. Um usuário pode revogar o acesso, visitando Configurações de Conta . Veja a seção de acesso Remover site ou aplicativo de sites e aplicativos de terceiros com acesso à sua conta documento de suporte para mais informações.

    Também é possível que um aplicativo revogue programaticamente o acesso concedido a ele. A revogação programática é importante nos casos em que um usuário cancela a assinatura, remove um aplicativo ou os recursos de API exigidos por um aplicativo mudaram significativamente. Em outras palavras, parte do processo de remoção pode incluir uma solicitação de API para garantir que as permissões concedidas anteriormente ao aplicativo sejam removidas.

    Biblioteca cliente JS

    Para revogar programaticamente um símbolo, chamada GoogleAuth.disconnect() :

    GoogleAuth.disconnect();

    OAuth 2.0 Endpoints

    Para revogar programaticamente um token, 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}

    The token can be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token will also be revoked.

    If the revocation is successfully processed, then the HTTP status code of the response is 200 . For error conditions, an HTTP status code 400 is returned along with an error code.

    The following JavaScript snippet shows how to revoke a token in JavaScript without using the Google APIs Client Library for JavaScript. Since the Google's OAuth 2.0 endpoint for revoking tokens does not support Cross-origin Resource Sharing (CORS), the code creates a form and submits the form to the endpoint rather than using the XMLHttpRequest() method to post the request.

    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();
    }