Como usar o OAuth 2.0 para aplicativos de servidor da Web

Neste documento, explicamos como os aplicativos de servidor da Web usam as bibliotecas de cliente da API do Google ou os endpoints do OAuth 2.0 do Google para implementar a autorização do OAuth 2.0 e acessar as APIs do Google.

O OAuth 2.0 permite que os usuários compartilhem dados específicos com um aplicativo, mantendo a privacidade dos nomes de usuários, senhas e outras informações. Por exemplo, um aplicativo pode usar o OAuth 2.0 para receber permissão dos usuários para armazenar arquivos nos drives do Google.

Esse fluxo do OAuth 2.0 é destinado especificamente à autorização do usuário. Ela foi projetada para aplicativos que podem armazenar informações confidenciais e manter o estado. Um aplicativo de servidor da Web devidamente autorizado pode acessar uma API enquanto o usuário interage com o aplicativo ou depois de sair dele.

Os aplicativos de servidor da Web também costumam usar contas de serviço para autorizar solicitações de API, especialmente ao chamar APIs do Cloud para acessar dados baseados em projetos, em vez de dados específicos do usuário. Os aplicativos de servidor da Web podem usar contas de serviço em conjunto com a autorização do usuário.

Observação:devido às implicações de segurança na implementação correta, recomendamos que você use as bibliotecas do OAuth 2.0 ao interagir com os endpoints do OAuth 2.0 do Google. É uma prática recomendada usar um código bem depurado fornecido por outras pessoas e ajudar a proteger você e seus usuários. Para mais informações, consulte Bibliotecas de cliente.

Bibliotecas de cliente

Os exemplos específicos de linguagem nesta página usam bibliotecas de cliente da API do Google para implementar a autorização do OAuth 2.0. Para executar as amostras de código, instale a biblioteca de cliente para sua linguagem.

Quando você usa uma biblioteca de cliente da API do Google para processar o fluxo do OAuth 2.0 do seu aplicativo, essa biblioteca realiza muitas ações que o aplicativo precisaria gerenciar por conta própria. Por exemplo, determina quando o aplicativo pode usar ou atualizar tokens de acesso armazenados e quando precisa solicitar o consentimento novamente. A biblioteca de cliente também gera URLs de redirecionamento corretos e ajuda a implementar gerenciadores de redirecionamento que trocam códigos de autorização por tokens de acesso.

As bibliotecas de cliente da API do Google para aplicativos do lado do servidor estão disponíveis para as seguintes linguagens:

• Go
• Java
• .NET
• Node.js
• PHP
• Python
• Ruby

Importante:a biblioteca de cliente da API do Google para JavaScript e o Fazer login com o Google têm a finalidade apenas de gerenciar o OAuth 2.0 no navegador do usuário. Se você quiser usar o JavaScript no lado do servidor para gerenciar as interações do OAuth 2.0 com o Google, considere usar a biblioteca Node.js na plataforma de back-end.

Pré-requisitos

Ativar as APIs do projeto

Qualquer aplicativo que chame APIs do Google precisa ativar essas APIs no API Console.

Para ativar uma API para um projeto, faça o seguinte:

1. Open the API Library no Google API Console.
2. If prompted, select a project, or create a new one.
3. A API Library lista todas as APIs disponíveis agrupadas por família de produtos e popularidade. Se a API que você quer ativar não estiver visível na lista, use a pesquisa para encontrá-la ou clique em Ver tudo na família de produtos à qual ela pertence.
4. Selecione aquela que você quer habilitar e clique no botão Ativar.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Criar credenciais de autorização

Qualquer aplicativo que usa o OAuth 2.0 para acessar as APIs do Google precisa ter credenciais de autorização que identifiquem o aplicativo para o servidor OAuth 2.0 do Google. As etapas a seguir explicam como criar credenciais para o projeto. Seus aplicativos podem usar as credenciais para acessar as APIs que você ativou nesse projeto.

1. Go to the Credentials page.
2. Clique em Criar credenciais > ID do cliente OAuth.
3. Selecione o tipo de aplicativo Aplicativo da Web.
4. Preencha o formulário e clique em Criar. Os aplicativos que usam linguagens e frameworks como PHP, Java, Python, Ruby e .NET precisam especificar URIs de redirecionamento autorizados. Os URIs de redirecionamento são os endpoints para os quais o servidor do OAuth 2.0 pode enviar respostas. Esses endpoints precisam aderir às regras de validação do Google.

   Para testes, especifique URIs que se referem à máquina local, como http://localhost:8080. Com isso em mente, todos os exemplos neste documento usam http://localhost:8080 como o URI de redirecionamento.

   Recomendamos que você projete endpoints de autenticação para que o app não exponha códigos de autorização a outros recursos na página.

Depois de criar suas credenciais, faça o download do arquivo client_secret.json em API Console. Armazene o arquivo com segurança em um local que só o aplicativo possa acessar.

Importante:não armazene o arquivo client_secret.json em um local acessível publicamente. Além disso, se você compartilhar o código-fonte para seu aplicativo, como no GitHub, armazene o arquivo client_secret.json fora da árvore de origem para evitar o compartilhamento acidental das credenciais do cliente.

Identificar escopos de acesso

Os escopos permitem que o aplicativo solicite apenas acesso aos recursos necessários, além de permitir que os usuários controlem o nível de acesso que concedem ao aplicativo. Assim, pode haver uma relação inversa entre o número de escopos solicitados e a probabilidade de consentimento do usuário.

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

Também recomendamos que seu aplicativo solicite acesso a escopos de autorização por um processo de autorização incremental, em que o aplicativo solicita acesso aos dados do usuário no contexto. Essa prática recomendada ajuda os usuários a entender mais facilmente por que seu app precisa do acesso que ele está solicitando.

O documento Escopos da API OAuth 2.0 contém uma lista completa de escopos que você pode usar para acessar as APIs do Google.

Se o aplicativo público usa escopos que permitem o acesso a determinados dados do usuário, ele precisa concluir um processo de verificação. Se aparecer app não verificado na tela ao testar o aplicativo, envie uma solicitação de verificação para removê-lo. Saiba mais sobre apps não verificados e veja respostas para perguntas frequentes sobre a verificação de apps na Central de Ajuda.

Requisitos específicos do idioma

Para executar as amostras de código neste documento, você precisará de uma Conta do Google, acesso à Internet e um navegador da Web. Se você estiver usando uma das bibliotecas de cliente da API, consulte também os requisitos específicos da linguagem abaixo.

PHP

Para executar as amostras de código PHP neste documento, você precisará do seguinte:

• PHP 5.6 ou superior com a interface de linha de comando (CLI) e a extensão JSON instaladas.
• A ferramenta de gerenciamento de dependências do Composer.

• A biblioteca de cliente das APIs do Google para PHP:

  composer require google/apiclient:^2.10

Python

Para executar as amostras de código Python neste documento, você precisará de:

• Python 2.6 ou superior
• A ferramenta de gerenciamento de pacotes pip.
• A biblioteca de cliente das APIs do Google para Python:

  pip install --upgrade google-api-python-client

• google-auth, google-auth-oauthlib e google-auth-httplib2 para autorização do usuário.

  pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2

• O framework de aplicativo da Web Flask Python.

  pip install --upgrade flask

• A biblioteca HTTP requests.

  pip install --upgrade requests

Ruby

Para executar as amostras de código do Ruby neste documento, você precisará do seguinte:

• Ruby 2.2.2 ou superior

• Biblioteca de cliente de APIs do Google para Ruby:

  gem install google-api-client

• O framework de aplicativo da Web Sinatra Ruby.

  gem install sinatra

Node.js

Para executar as amostras de código Node.js neste documento, você precisará do seguinte:

• O LTS de manutenção, o LTS ativo ou a versão atual do Node.js.

• O cliente Node.js das APIs do Google:

  npm install googleapis

HTTP/REST

Não é necessário instalar nenhuma biblioteca para poder chamar diretamente os endpoints do OAuth 2.0.

Como conseguir tokens de acesso do OAuth 2.0

As etapas a seguir mostram como seu aplicativo interage com o servidor OAuth 2.0 do Google para receber o consentimento de um usuário para executar uma solicitação de API em nome do usuário. O aplicativo precisa ter esse consentimento para que possa executar uma solicitação da API do Google que exija autorização do usuário.

A lista abaixo resume rapidamente essas etapas:

1. O aplicativo identifica as permissões necessárias.
2. O aplicativo redireciona o usuário para o Google com a lista de permissões solicitadas.
3. O usuário decide se quer conceder as permissões para o aplicativo.
4. O aplicativo descobre o que o usuário decidiu.
5. Se o usuário concedeu as permissões solicitadas, o aplicativo recupera tokens necessários para fazer solicitações de API em nome do usuário.

Etapa 1: definir os parâmetros de autorização

A primeira etapa é criar a solicitação de autorização. Essa solicitação define parâmetros que identificam seu aplicativo e define as permissões que serão solicitadas ao usuário.

• Se você usa uma biblioteca de cliente do Google para autenticação e autorização do OAuth 2.0, crie e configure um objeto que defina esses parâmetros.
• Se chamar o endpoint do OAuth 2.0 do Google diretamente, você gerará um URL e definirá os parâmetros dele.

As guias abaixo definem os parâmetros de autorização suportados para aplicativos de servidor da web. Os exemplos específicos de linguagem também mostram como usar uma biblioteca de cliente ou de autorização para configurar um objeto que define esses parâmetros.

PHP

O snippet de código abaixo cria um objeto Google\Client(), que define os parâmetros na solicitação de autorização.

Esse objeto usa informações do arquivo client_secret.json para identificar o aplicativo. Consulte Como criar credenciais de autorização para saber mais sobre esse arquivo. O objeto também identifica os escopos que seu aplicativo está solicitando permissão para acessar e o URL do endpoint de autenticação do aplicativo, que lidará com a resposta do servidor OAuth 2.0 do Google. Por fim, o código define os parâmetros opcionais access_type e include_granted_scopes.

Por exemplo, este código solicita acesso off-line somente leitura ao Google Drive de um usuário:

$client = new Google\Client();
$client->setAuthConfig('client_secret.json');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');
// offline access will give you both an access and refresh token so that
// your app can refresh the access token without user interaction.
$client->setAccessType('offline');
// Using "consent" ensures that your application always receives a refresh token.
// If you are not using offline access, you can omit this.
$client->setApprovalPrompt('consent');
$client->setIncludeGrantedScopes(true);   // incremental auth

A solicitação especifica as seguintes informações:

Parâmetros
client_id	Obrigatório O ID do cliente do aplicativo. Esse valor pode ser encontrado no API Console Credentials page. Em PHP, chame a função setAuthConfig para carregar credenciais de autorização de um arquivo client_secret.json. $client = new Google\Client(); $client->setAuthConfig('client_secret.json');
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 precisa corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou no Credentials pagedo API Console. Se esse valor não corresponder a um URI de redirecionamento autorizado para o client_id fornecido, você vai receber um erro redirect_uri_mismatch. O esquema, o caso e a barra à direita ("/") ou http precisam corresponder. Para definir esse valor em PHP, chame a função setRedirectUri. É necessário especificar um URI de redirecionamento válido para a client_id fornecida. $client->setRedirectUri('https://oauth2.example.com/code');
scope	Obrigatório Uma lista de escopos delimitada por espaços que identificam os recursos que seu aplicativo pode acessar em nome do usuário. Esses valores informam a tela de consentimento que o Google exibe ao usuário. Os escopos permitem que o aplicativo solicite apenas acesso aos recursos necessários, além de permitir que os usuários controlem o nível de acesso que concedem ao aplicativo. Portanto, há uma relação inversa entre o número de escopos solicitados e a probabilidade de receber o consentimento do usuário. Para definir esse valor em PHP, chame a função addScope: $client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY); Recomendamos que seu aplicativo solicite acesso a escopos de autorização sempre que possível. Ao solicitar acesso aos dados do usuário no contexto, usando a autorização incremental, você ajuda os usuários a entender mais facilmente por que seu app precisa do acesso que ele está solicitando.
access_type	Recomendável Indica se o aplicativo pode atualizar os tokens de acesso quando o usuário não está presente no navegador. Os valores de parâmetro válidos são online, que é o valor padrão, e offline. Defina o valor como offline se o aplicativo precisar atualizar os tokens de acesso quando o usuário não estiver presente no navegador. Esse é o método de atualização de tokens de acesso descritos mais adiante neste documento. Esse valor instrui o servidor de autorização do Google a retornar um token de atualização e um token de acesso na primeira vez que o aplicativo trocar um código de autorização por tokens. Para definir esse valor em PHP, chame a função setAccessType: $client->setAccessType('offline');
state	Recomendável Especifica qualquer valor de string que seu aplicativo usa para manter o estado entre a solicitação de autorização e a resposta do servidor de autorização. O servidor retorna o valor exato que você envia como um par name=value no componente de consulta de URL (?) do redirect_uri depois que o usuário consente ou nega a solicitação de acesso do aplicativo. Esse parâmetro pode ser usado para várias finalidades, como direcionar o usuário ao recurso correto no aplicativo, enviar valores de uso único e atenuar a falsificação de solicitações entre sites. Como o redirect_uri pode ser suposto, o uso de um valor state pode aumentar a 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 captura o estado do cliente, será possível validar a resposta para garantir também que a solicitação e a resposta sejam originadas no mesmo navegador, fornecendo proteção contra ataques, como falsificação de solicitação entre sites. Consulte a documentação do OpenID Connect para ver um exemplo de como criar e confirmar um token state. Para definir esse valor em PHP, chame a função setState: $client->setState($sample_passthrough_value);
include_granted_scopes	Opcional Permite que os aplicativos usem autorização incremental para solicitar acesso a mais escopos no contexto. Se você definir o valor desse parâmetro como true e a solicitação de autorização for concedida, o novo token de acesso também cobrirá todos os escopos aos quais o usuário concedeu o acesso do aplicativo anteriormente. Consulte a seção autorização incremental para ver exemplos. Para definir esse valor em PHP, chame a função setIncludeGrantedScopes: $client->setIncludeGrantedScopes(true);
login_hint	Opcional Se o aplicativo souber qual usuário está tentando autenticar, ele poderá usar esse parâmetro para fornecer uma dica para o servidor de autenticação do Google. O servidor usa a dica para simplificar o fluxo de login preenchendo o campo de e-mail no formulário de login ou selecionando a sessão de login múltiplo adequada. Defina o valor do parâmetro como um endereço de e-mail ou identificador sub, que é equivalente ao ID do Google do usuário. Para definir esse valor em PHP, chame a função setLoginHint: $client->setLoginHint('None');
prompt	Opcional Uma lista de solicitações delimitadas por espaços e com diferenciação entre maiúsculas e minúsculas para apresentar ao usuário. Se você não especificar esse parâmetro, o usuário só receberá uma solicitação na primeira vez que o projeto solicitar acesso. Consulte Solicitar nova autorização para mais informações. Para definir esse valor em PHP, chame a função setApprovalPrompt: $client->setApprovalPrompt('consent'); Os valores possíveis são: none Não exiba telas de autenticação ou consentimento. Não pode ser especificado com outros valores. consent Solicite o consentimento do usuário. select_account Solicitar que o usuário selecione uma conta

Python

O snippet de código a seguir usa o módulo google-auth-oauthlib.flow para construir a solicitação de autorização.

O código cria um objeto Flow, que identifica seu aplicativo usando informações do arquivo client_secret.json que você transferiu por download depois de criar credenciais de autorização. Esse objeto também identifica os escopos que seu aplicativo está solicitando permissão de acesso e o URL para o endpoint de autenticação do aplicativo, que lidará com a resposta do servidor OAuth 2.0 do Google. Por fim, o código define os parâmetros opcionais access_type e include_granted_scopes.

Por exemplo, este código solicita acesso off-line somente leitura ao Google Drive de um usuário:

import google.oauth2.credentials
import google_auth_oauthlib.flow

# Use the client_secret.json file to identify the application requesting
# authorization. The client ID (from that file) and access scopes are required.
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])

# Indicate where the API server will redirect the user after the user completes
# the authorization flow. The redirect URI is required. The value must exactly
# match one of the authorized redirect URIs for the OAuth 2.0 client, which you
# configured in the API Console. If this value doesn't match an authorized URI,
# you will get a 'redirect_uri_mismatch' error.
flow.redirect_uri = 'https://www.example.com/oauth2callback'

# Generate URL for request to Google's OAuth 2.0 server.
# Use kwargs to set optional request parameters.
authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

A solicitação especifica as seguintes informações:

Parâmetros
client_id	Obrigatório O ID do cliente do aplicativo. Esse valor pode ser encontrado no API Console Credentials page. Em Python, chame o método from_client_secrets_file para recuperar o ID do cliente de um arquivo client_secret.json. Também é possível usar o método from_client_config, que transmite a configuração do cliente da forma como aparecia originalmente em um arquivo de chaves secretas do cliente, mas não acessa o próprio arquivo. flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( 'client_secret.json', scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])
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 precisa corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou no Credentials pagedo API Console. Se esse valor não corresponder a um URI de redirecionamento autorizado para o client_id fornecido, você vai receber um erro redirect_uri_mismatch. O esquema, o caso e a barra à direita ("/") ou http precisam corresponder. Para definir esse valor em Python, defina a propriedade redirect_uri do objeto flow: flow.redirect_uri = 'https://oauth2.example.com/code'
scope	Obrigatório Uma lista de escopos 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 ao usuário. Os escopos permitem que o aplicativo solicite apenas acesso aos recursos necessários, além de permitir que os usuários controlem o nível de acesso que concedem ao aplicativo. Portanto, há uma relação inversa entre o número de escopos solicitados e a probabilidade de receber o consentimento do usuário. Em Python, use o mesmo método usado para definir a classe client_id e especificar a lista de escopos. flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( 'client_secret.json', scopes=['https://www.googleapis.com/auth/drive.metadata.readonly']) Recomendamos que seu aplicativo solicite acesso a escopos de autorização sempre que possível. Ao solicitar acesso aos dados do usuário no contexto, usando a autorização incremental, você ajuda os usuários a entender mais facilmente por que seu app precisa do acesso que ele está solicitando.
access_type	Recomendável Indica se o aplicativo pode atualizar os tokens de acesso quando o usuário não está presente no navegador. Os valores de parâmetro válidos são online, que é o valor padrão, e offline. Defina o valor como offline se o aplicativo precisar atualizar os tokens de acesso quando o usuário não estiver presente no navegador. Esse é o método de atualização de tokens de acesso descritos mais adiante neste documento. Esse valor instrui o servidor de autorização do Google a retornar um token de atualização e um token de acesso na primeira vez que o aplicativo trocar um código de autorização por tokens. No Python, defina o parâmetro access_type especificando access_type como um argumento de palavra-chave ao chamar o método flow.authorization_url: authorization_url, state = flow.authorization_url( access_type='offline', include_granted_scopes='true')
state	Recomendável Especifica qualquer valor de string que seu aplicativo usa para manter o estado entre a solicitação de autorização e a resposta do servidor de autorização. O servidor retorna o valor exato que você envia como um par name=value no componente de consulta de URL (?) do redirect_uri depois que o usuário consente ou nega a solicitação de acesso do aplicativo. Esse parâmetro pode ser usado para várias finalidades, como direcionar o usuário ao recurso correto no aplicativo, enviar valores de uso único e atenuar a falsificação de solicitações entre sites. Como o redirect_uri pode ser suposto, o uso de um valor state pode aumentar a 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 captura o estado do cliente, será possível validar a resposta para garantir também que a solicitação e a resposta sejam originadas no mesmo navegador, fornecendo proteção contra ataques, como falsificação de solicitação entre sites. Consulte a documentação do OpenID Connect para ver um exemplo de como criar e confirmar um token state. Em Python, defina state o parâmetro especificando state como um argumento de palavra-chave ao chamar o método flow.authorization_url: authorization_url, state = flow.authorization_url( access_type='offline', state=sample_passthrough_value, include_granted_scopes='true')
include_granted_scopes	Opcional Permite que os aplicativos usem autorização incremental para solicitar acesso a mais escopos no contexto. Se você definir o valor desse parâmetro como true e a solicitação de autorização for concedida, o novo token de acesso também cobrirá todos os escopos aos quais o usuário concedeu o acesso do aplicativo anteriormente. Consulte a seção autorização incremental para ver exemplos. No Python, defina o parâmetro include_granted_scopes especificando include_granted_scopes como um argumento de palavra-chave ao chamar o método flow.authorization_url: authorization_url, state = flow.authorization_url( access_type='offline', include_granted_scopes='true')
login_hint	Opcional Se o aplicativo souber qual usuário está tentando autenticar, ele poderá usar esse parâmetro para fornecer uma dica para o servidor de autenticação do Google. O servidor usa a dica para simplificar o fluxo de login preenchendo o campo de e-mail no formulário de login ou selecionando a sessão de login múltiplo adequada. Defina o valor do parâmetro como um endereço de e-mail ou identificador sub, que é equivalente ao ID do Google do usuário. No Python, defina o parâmetro login_hint especificando login_hint como um argumento de palavra-chave ao chamar o método flow.authorization_url: authorization_url, state = flow.authorization_url( access_type='offline', login_hint='None', include_granted_scopes='true')
prompt	Opcional Uma lista de solicitações delimitadas por espaços e com diferenciação entre maiúsculas e minúsculas para apresentar ao usuário. Se você não especificar esse parâmetro, o usuário só receberá uma solicitação na primeira vez que o projeto solicitar acesso. Consulte Solicitar nova autorização para mais informações. Em Python, defina prompt o parâmetro especificando prompt como um argumento de palavra-chave ao chamar o método flow.authorization_url: authorization_url, state = flow.authorization_url( access_type='offline', prompt='consent', include_granted_scopes='true') Os valores possíveis são: none Não exiba telas de autenticação ou consentimento. Não pode ser especificado com outros valores. consent Solicite o consentimento do usuário. select_account Solicitar que o usuário selecione uma conta

Ruby

Use o arquivo client_secrets.json que você criou para configurar um objeto cliente no seu aplicativo. Ao configurar um objeto cliente, você especifica os escopos que seu aplicativo precisa acessar, além do URL do endpoint de autenticação do aplicativo, que lidará com a resposta do servidor OAuth 2.0.

Por exemplo, este código solicita acesso off-line somente leitura ao Google Drive de um usuário:

require 'google/apis/drive_v2'
require 'google/api_client/client_secrets'

client_secrets = Google::APIClient::ClientSecrets.load
auth_client = client_secrets.to_authorization
auth_client.update!(
  :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly',
  :redirect_uri => 'http://www.example.com/oauth2callback',
  :additional_parameters => {
    "access_type" => "offline",         # offline access
    "include_granted_scopes" => "true"  # incremental auth
  }
)

O aplicativo usa o objeto cliente para realizar operações OAuth 2.0, como gerar URLs de solicitação de autorização e aplicar tokens de acesso a solicitações HTTP.

Node.js

O snippet de código abaixo cria um objeto google.auth.OAuth2, que define os parâmetros na solicitação de autorização.

Esse objeto usa informações do arquivo client_secret.json para identificar seu aplicativo. Para solicitar permissões de um usuário para recuperar um token de acesso, é necessário redirecionar o usuário para uma página de consentimento. Para criar um URL da página de consentimento, faça o seguinte:

const {google} = require('googleapis');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI
 * from the client_secret.json file. To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for read-only Drive activity.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

// Generate a url that asks permissions for the Drive activity scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

Observação importante: o refresh_token é retornado apenas na primeira autorização. Veja mais detalhes aqui.

HTTP/REST

O endpoint do OAuth 2.0 do Google está em https://accounts.google.com/o/oauth2/v2/auth. Esse endpoint só pode ser acessado por HTTPS. Conexões HTTP simples são recusadas.

O servidor de autorização do Google é compatível com os seguintes parâmetros de string de consulta para aplicativos do servidor da Web:

Parâmetros
client_id	Obrigatório O ID do cliente do aplicativo. Esse valor pode ser encontrado no API Console Credentials 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 precisa corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou no Credentials pagedo API Console. Se esse valor não corresponder a um URI de redirecionamento autorizado para o client_id fornecido, você vai receber um erro redirect_uri_mismatch. O esquema, o caso e a barra à direita ("/") ou http precisam corresponder.
response_type	Obrigatório Determina se o endpoint do OAuth 2.0 do Google retorna um código de autorização. Defina o valor do parâmetro como code para aplicativos de servidor da Web.
scope	Obrigatório Uma lista de escopos delimitada por espaços que identificam os recursos que seu aplicativo pode acessar em nome do usuário. Esses valores informam a tela de consentimento que o Google exibe ao usuário. Os escopos permitem que o aplicativo solicite apenas acesso aos recursos necessários, além de permitir que os usuários controlem o nível de acesso que concedem ao aplicativo. Portanto, há uma relação inversa entre o número de escopos solicitados e a probabilidade de receber o consentimento do usuário. Recomendamos que seu aplicativo solicite acesso a escopos de autorização sempre que possível. Ao solicitar acesso aos dados do usuário no contexto, usando a autorização incremental, você ajuda os usuários a entender mais facilmente por que seu app precisa do acesso que ele está solicitando.
access_type	Recomendável Indica se o aplicativo pode atualizar os tokens de acesso quando o usuário não está presente no navegador. Os valores de parâmetro válidos são online, que é o valor padrão, e offline. Defina o valor como offline se o aplicativo precisar atualizar os tokens de acesso quando o usuário não estiver presente no navegador. Esse é o método de atualização de tokens de acesso descritos mais adiante neste documento. Esse valor instrui o servidor de autorização do Google a retornar um token de atualização e um token de acesso na primeira vez que o aplicativo trocar um código de autorização por tokens.
state	Recomendável Especifica qualquer valor de string que seu aplicativo usa para manter o estado entre a solicitação de autorização e a resposta do servidor de autorização. O servidor retorna o valor exato que você envia como um par name=value no componente de consulta de URL (?) do redirect_uri depois que o usuário consente ou nega a solicitação de acesso do aplicativo. Esse parâmetro pode ser usado para várias finalidades, como direcionar o usuário ao recurso correto no aplicativo, enviar valores de uso único e atenuar a falsificação de solicitações entre sites. Como o redirect_uri pode ser suposto, o uso de um valor state pode aumentar a 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 captura o estado do cliente, será possível validar a resposta para garantir também que a solicitação e a resposta sejam originadas no mesmo navegador, fornecendo proteção contra ataques, como falsificação de solicitação entre sites. Consulte a documentação do OpenID Connect para ver um exemplo de como criar e confirmar um token state.
include_granted_scopes	Opcional Permite que os aplicativos usem autorização incremental para solicitar acesso a mais escopos no contexto. Se você definir o valor desse parâmetro como true e a solicitação de autorização for concedida, o novo token de acesso também cobrirá todos os escopos aos quais o usuário concedeu o acesso do aplicativo anteriormente. Consulte a seção autorização incremental para ver exemplos.
login_hint	Opcional Se o aplicativo souber qual usuário está tentando autenticar, ele poderá usar esse parâmetro para fornecer uma dica para o servidor de autenticação do Google. O servidor usa a dica para simplificar o fluxo de login preenchendo o campo de e-mail no formulário de login ou selecionando a sessão de login múltiplo adequada. Defina o valor do parâmetro como um endereço de e-mail ou identificador sub, que é equivalente ao ID do Google do usuário.
prompt	Opcional Uma lista de solicitações delimitadas por espaços e com diferenciação entre maiúsculas e minúsculas para apresentar ao usuário. Se você não especificar esse parâmetro, o usuário só receberá uma solicitação na primeira vez que o projeto solicitar acesso. Consulte Solicitar nova autorização para mais informações. Os valores possíveis são: none Não exiba telas de autenticação ou consentimento. Não pode ser especificado com outros valores. consent Solicite o consentimento do usuário. select_account Solicitar que o usuário selecione uma conta

Etapa 2: redirecionar para o servidor OAuth 2.0 do Google

Redirecione o usuário ao servidor OAuth 2.0 do Google para iniciar o processo de autenticação e autorização. Normalmente, isso ocorre quando seu aplicativo precisa acessar os dados do usuário pela primeira vez. No caso de autorização incremental, essa etapa também ocorre quando o aplicativo precisa acessar recursos adicionais que ele ainda não tem permissão para acessar.

PHP

1. Gere um URL para solicitar acesso ao servidor OAuth 2.0 do Google:

   $auth_url = $client->createAuthUrl();

2. Redirecionar o usuário para $auth_url:

   header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));

Python

Neste exemplo, mostramos como redirecionar o usuário para o URL de autorização usando o framework do aplicativo da Web Flask:

return flask.redirect(authorization_url)

Ruby

1. Gere um URL para solicitar acesso ao servidor OAuth 2.0 do Google:

   auth_uri = auth_client.authorization_uri.to_s

2. Redirecionar o usuário para auth_uri.

Node.js

1. Use o URL gerado authorizationUrl da Etapa 1 generateAuthUrl para solicitar acesso ao servidor OAuth 2.0 do Google.
2. Redirecionar o usuário para authorizationUrl.

   res.writeHead(301, { "Location": authorizationUrl });

HTTP/REST

Sample redirect to Google's authorization server

An example URL is shown below, with line breaks and spaces for readability.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 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.

O servidor OAuth 2.0 do Google autentica o usuário e recebe o consentimento dele para que seu aplicativo acesse os escopos solicitados. A resposta é enviada ao aplicativo usando o URL de redirecionamento especificado.

Etapa 3: o Google solicita o consentimento do usuário

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

O aplicativo não precisa fazer nada enquanto aguarda a resposta do servidor OAuth 2.0 do Google, indicando se algum acesso foi concedido. Essa resposta é explicada na etapa a seguir.

Erros

As solicitações para o endpoint de autorização do OAuth 2.0 do Google podem exibir mensagens de erro para o usuário, em vez dos fluxos de autenticação e autorização esperados. Veja abaixo os códigos de erro comuns e as sugestões de resolução.

admin_policy_enforced

A Conta do Google não autoriza um ou mais escopos solicitados devido às políticas do administrador do Google Workspace. Consulte o artigo de ajuda do administrador do Google Workspace Controlar quais apps internos e de terceiros acessam os dados do Google Workspace para mais informações sobre como um administrador pode restringir o acesso a todos os escopos ou aos escopos confidenciais e restritos até que o acesso seja explicitamente concedido ao ID do cliente OAuth.

disallowed_useragent

O endpoint de autorização é exibido em um user agent incorporado não permitido pelas políticas do OAuth 2.0 do Google.

Android

Os desenvolvedores Android podem encontrar essa mensagem de erro ao abrir solicitações de autorização em android.webkit.WebView. Em vez disso, os desenvolvedores precisam usar bibliotecas do Android, como o Login do Google para Android ou o AppAuth para Android da OpenID Foundation.

Os desenvolvedores da Web podem encontrar esse erro quando um app Android abre um link da Web geral em um user agent incorporado e um usuário navega para o endpoint de autorização do OAuth 2.0 do Google no seu site. Os desenvolvedores precisam permitir que links gerais sejam abertos no gerenciador de links padrão do sistema operacional, que inclui gerenciadores de Links do app Android ou o app de navegação padrão. A biblioteca Guias personalizadas do Android também é uma opção compatível.

iOS

Os desenvolvedores do iOS e do macOS podem encontrar esse erro ao abrir solicitações de autorização em WKWebView. Em vez disso, os desenvolvedores precisam usar bibliotecas do iOS, como o Login do Google para iOS ou o AppAuth para iOS da OpenID Foundation.

Os desenvolvedores da Web podem encontrar esse erro quando um app iOS ou macOS abre um link da Web geral em um user agent incorporado e um usuário navega para o endpoint de autorização do OAuth 2.0 do Google no seu site. Os desenvolvedores precisam permitir que links gerais sejam abertos no gerenciador de links padrão do sistema operacional, que inclui gerenciadores de links universais ou o app de navegação padrão. A biblioteca SFSafariViewController também é uma opção compatível.

org_internal

O ID do cliente OAuth na solicitação faz parte de um projeto que limita o acesso a Contas do Google em uma organização específica do Google Cloud. Para mais informações sobre essa opção de configuração, consulte a seção Tipo de usuário no artigo de ajuda sobre como configurar a tela de permissão OAuth.

invalid_client

A chave secreta do cliente OAuth está incorreta. Revise a configuração do cliente OAuth, incluindo o ID do cliente e a chave secreta usados para essa solicitação.

invalid_grant

Ao atualizar um token de acesso ou usar a autorização incremental, o token pode ter expirado ou foi invalidado. Autentique o usuário novamente e peça o consentimento dele para receber novos tokens. Se você continuar a ver esse erro, verifique se o aplicativo foi configurado corretamente e se está usando os tokens e parâmetros corretos na solicitação. Caso contrário, a conta de usuário pode ter sido excluída ou desativada.

redirect_uri_mismatch

O redirect_uri transmitido na solicitação de autorização não corresponde a um URI de redirecionamento autorizado para o ID do cliente OAuth. Revise os URIs de redirecionamento autorizados em Google API Console Credentials page.

O parâmetro redirect_uri pode se referir ao fluxo OAuth fora de banda (OOB, na sigla em inglês) que foi descontinuado e não tem mais suporte. Consulte o guia de migração para atualizar sua integração.

Etapa 4: lidar com a resposta do servidor OAuth 2.0

O servidor OAuth 2.0 responde à solicitação de acesso do seu aplicativo usando o URL especificado na solicitação.

Se o usuário aprovar a solicitação de acesso, a resposta vai conter um código de autorização. Se o usuário não aprovar a solicitação, a resposta vai conter uma mensagem de erro. O código de autorização ou mensagem de erro que é retornado ao servidor da Web aparece na string de consulta, conforme mostrado abaixo:

Uma resposta de erro:

https://oauth2.example.com/auth?error=access_denied

Uma resposta de código de autorização:

https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

Importante: se o endpoint de resposta renderizar uma página HTML, todos os recursos dessa página poderão ver o código de autorização no URL. Os scripts podem ler o URL diretamente, e o URL no cabeçalho HTTP Referer pode ser enviado para qualquer ou todos os recursos na página.

Analise com cuidado se você quer enviar credenciais de autorização para todos os recursos da página, principalmente scripts de terceiros, como plug-ins de redes sociais e análises. Para evitar esse problema, recomendamos que o servidor processe a solicitação primeiro e depois redirecione para outro URL que não inclua os parâmetros de resposta.

Exemplo de resposta do servidor OAuth 2.0

Para testar esse fluxo, clique no URL de amostra a seguir, 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//www.googleapis.com/auth/drive.metadata.readonly&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 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, que provavelmente gerará um erro 404 NOT FOUND, a menos que sua máquina local exiba um arquivo nesse endereço. A etapa seguinte fornece mais detalhes sobre as informações retornadas no URI quando o usuário é redirecionado de volta para o aplicativo.

Etapa 5: trocar o código de autorização dos tokens de atualização e acesso

Depois que o servidor da Web receber o código de autorização, ele poderá trocá-lo por um token de acesso.

PHP

Para trocar um código de autorização por um token de acesso, use o método authenticate:

$client->authenticate($_GET['code']);

É possível recuperar o token de acesso com o método getAccessToken:

$access_token = $client->getAccessToken();

Python

Na página de callback, use a biblioteca google-auth para verificar a resposta do servidor de autorização. Em seguida, use o método flow.fetch_token para trocar o código de autorização nessa resposta por um token de acesso:

state = flask.session['state']
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'],
    state=state)
flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

authorization_response = flask.request.url
flow.fetch_token(authorization_response=authorization_response)

# Store the credentials in the session.
# ACTION ITEM for developers:
#     Store user's access and refresh tokens in your data store if
#     incorporating this code into your real app.
credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'token_uri': credentials.token_uri,
    'client_id': credentials.client_id,
    'client_secret': credentials.client_secret,
    'scopes': credentials.scopes}

Ruby

Para trocar um código de autorização por um token de acesso, use o método fetch_access_token!:

auth_client.code = auth_code
auth_client.fetch_access_token!

Node.js

Para trocar um código de autorização por um token de acesso, use o método getToken:

const url = require('url');

// Receive the callback from Google's OAuth 2.0 server.
if (req.url.startsWith('/oauth2callback')) {
  // Handle the OAuth 2.0 server response
  let q = url.parse(req.url, true).query;

  // Get access and refresh tokens (if access_type is offline)
  let { tokens } = await oauth2Client.getToken(q.code);
  oauth2Client.setCredentials(tokens);
}

HTTP/REST

Para trocar um código de autorização por um token de acesso, chame o endpoint https://oauth2.googleapis.com/token e defina os seguintes parâmetros:

Campos
client_id	O ID do cliente recebido do API Console Credentials page.
client_secret	A chave secreta do cliente recebida do API Console Credentials page.
code	O código de autorização retornado da solicitação inicial.
grant_type	Conforme definido na especificação do OAuth 2.0, o valor desse campo precisa ser definido como authorization_code.
redirect_uri	Um dos URIs de redirecionamento listados para seu projeto no API Console Credentials page do client_id fornecido.

O snippet a seguir mostra um exemplo de solicitação:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

O Google responde a essa solicitação retornando um objeto JSON com um token de acesso de curta duração e um token de atualização. O token de atualização só será retornado se seu aplicativo definir o parâmetro access_type como offline na solicitação inicial para o servidor de autorização do Google.

A resposta contém os seguintes campos:

Campos
access_token	O token que seu aplicativo envia para autorizar uma solicitação de API do Google.
expires_in	O ciclo de vida restante do token de acesso em segundos.
refresh_token	Um token que pode ser usado para receber um novo token de acesso. Os tokens de atualização são válidos até que o usuário revogue o acesso. Novamente, esse campo só estará presente nessa resposta se você definir o parâmetro access_type como offline na solicitação inicial para o servidor de autorização do Google.
scope	Os escopos de acesso concedidos pelo access_token expressos como uma lista de strings delimitadas por espaços, que diferenciam maiúsculas de minúsculas.
token_type	O tipo de token retornado. No momento, o valor desse campo está sempre definido como Bearer.

Importante:o aplicativo precisa armazenar os dois tokens em um local seguro e de longa duração, que possa ser acessado entre diferentes invocações. Com o token de atualização, o aplicativo poderá receber um novo token de acesso se o token expirar. Assim, se o aplicativo perder o token de atualização, o usuário precisará repetir o fluxo de consentimento do OAuth 2.0 para que ele possa receber um novo token de atualização.

O snippet a seguir mostra um exemplo de resposta:

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

Observação:o aplicativo deve ignorar os campos não reconhecidos incluídos na resposta.

Erros

Ao trocar o código de autorização por um token de acesso, você pode encontrar o erro a seguir, em vez da resposta esperada. Veja abaixo códigos de erros comuns e resoluções sugeridas.

invalid_grant

O código de autorização fornecido é inválido ou está no formato errado. Solicite um novo código reiniciando o processo de OAuth para solicitar o consentimento do usuário novamente.

Como chamar APIs do Google

PHP

Use o token de acesso para chamar as APIs do Google seguindo estas etapas:

1. Se você precisar aplicar um token de acesso a um novo objeto Google\Client, por exemplo, se armazenou o token de acesso em uma sessão de usuário, use o método setAccessToken:

   $client->setAccessToken($access_token);

2. Crie um objeto de serviço para a API que você quer chamar. Crie um objeto de serviço fornecendo um objeto Google\Client autorizado ao construtor da API que você quer chamar. Por exemplo, para chamar a API Drive:

   $drive = new Google\Service\Drive($client);

3. Faça solicitações ao serviço da API usando a interface fornecida pelo objeto de serviço. Por exemplo, para listar os arquivos no Google Drive do usuário autenticado:

   $files = $drive->files->listFiles(array())->getItems();

Python

Depois de receber um token de acesso, o aplicativo pode usá-lo para autorizar solicitações de API em nome de uma determinada conta de usuário ou conta de serviço. Use as credenciais de autorização específicas do usuário para criar um objeto de serviço para a API que você quer chamar e use esse objeto para fazer solicitações de API autorizadas.

1. Crie um objeto de serviço para a API que você quer chamar. Crie um objeto de serviço chamando o método build da biblioteca googleapiclient.discovery com o nome e a versão da API e as credenciais do usuário: Por exemplo, para chamar a versão 2 da API Drive:

   from googleapiclient.discovery import build
   
   drive = build('drive', 'v2', credentials=credentials)

2. Faça solicitações ao serviço da API usando a interface fornecida pelo objeto de serviço. Por exemplo, para listar os arquivos no Google Drive do usuário autenticado:

   files = drive.files().list().execute()

Ruby

Use o objeto auth_client para chamar as APIs do Google, concluindo as seguintes etapas:

1. Crie um objeto de serviço para a API que você quer chamar. Por exemplo, para chamar a versão 2 da API Drive:

   drive = Google::Apis::DriveV2::DriveService.new

2. Defina as credenciais no serviço:

   drive.authorization = auth_client

3. Faça solicitações ao serviço da API usando a interface fornecida pelo objeto de serviço. Por exemplo, para listar os arquivos no Google Drive do usuário autenticado:

   files = drive.list_files

Como alternativa, a autorização pode ser fornecida por método, fornecendo o parâmetro options a um método:

files = drive.list_files(options: { authorization: auth_client })

Node.js

Depois de receber um token de acesso e defini-lo como o objeto OAuth2, use o objeto para chamar as APIs do Google. Seu aplicativo pode usar esse token para autorizar solicitações de API em nome de uma determinada conta de usuário ou conta de serviço. Crie um objeto de serviço para a API que você quer chamar.

const { google } = require('googleapis');

// Example of using Google Drive API to list filenames in user's Drive.
const drive = google.drive('v3');
drive.files.list({
  auth: oauth2Client,
  pageSize: 10,
  fields: 'nextPageToken, files(id, name)',
}, (err1, res1) => {
  if (err1) return console.log('The API returned an error: ' + err1);
  const files = res1.data.files;
  if (files.length) {
    console.log('Files:');
    files.map((file) => {
      console.log(`${file.name} (${file.id})`);
    });
  } else {
    console.log('No files found.');
  }
});

HTTP/REST

Depois que seu aplicativo recebe um token de acesso, é possível 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 ser visíveis nos registros do servidor. Na maioria dos casos, você pode usar uma biblioteca de cliente para configurar as chamadas para APIs do Google, por exemplo, ao chamar a API Drive Files.

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

Exemplos de HTTP GET

Uma chamada para o endpoint drive.files (a API Drive Files) usando o cabeçalho HTTP Authorization: Bearer pode ser semelhante a esta. Você precisa 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 usando o parâmetro de string de consulta access_token:

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

Exemplos de curl

É possível testar esses comandos com o aplicativo de linha de comando curl. Veja 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 da string de consulta:

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

Exemplo completo

O exemplo a seguir imprime uma lista de arquivos formatada em JSON no Google Drive depois que o usuário faz a autenticação e dá consentimento para que o aplicativo acesse os metadados do Drive.

PHP

Para executar esse exemplo:

1. No API Console, adicione o URL da máquina local à lista de URLs de redirecionamento. Por exemplo, adicione http://localhost:8080.
2. Crie um novo diretório e mude para ele. Por exemplo:

   mkdir ~/php-oauth2-example
   cd ~/php-oauth2-example

3. Instale a biblioteca de cliente da API do Google para PHP usando o Composer:

   composer require google/apiclient:^2.10

4. Crie os arquivos index.php e oauth2callback.php com o conteúdo abaixo.
5. Execute o exemplo com um servidor da Web configurado para veicular PHP. Caso você use o PHP 5.6 ou uma versão mais recente, será possível usar o servidor da Web de teste integrado do PHP:

   php -S localhost:8080 ~/php-oauth2-example

index.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();
$client->setAuthConfig('client_secrets.json');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

if (isset($_SESSION['access_token']) && $_SESSION['access_token']) {
  $client->setAccessToken($_SESSION['access_token']);
  $drive = new Google\Service\Drive($client);
  $files = $drive->files->listFiles(array())->getItems();
  echo json_encode($files);
} else {
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

oauth2callback.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();
$client->setAuthConfigFile('client_secrets.json');
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

if (! isset($_GET['code'])) {
  $auth_url = $client->createAuthUrl();
  header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
} else {
  $client->authenticate($_GET['code']);
  $_SESSION['access_token'] = $client->getAccessToken();
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

Python

Este exemplo usa o framework Flask. Ele executa um aplicativo da Web em http://localhost:8080 que permite testar o fluxo do OAuth 2.0. Se você acessar esse URL, verá quatro links:

• Teste uma solicitação de API: esse link aponta para uma página que tenta executar uma solicitação de API de amostra. Se necessário, ele inicia o fluxo de autorização. Se for bem-sucedida, a página exibirá a resposta da API.
• Teste o fluxo de autenticação diretamente: esse link aponta para uma página que tenta enviar o usuário pelo fluxo de autorização. O app solicita permissão para enviar solicitações de API autorizadas em nome do usuário.
• Revogar credenciais atuais:esse link aponta para uma página que revoga permissões que o usuário já concedeu ao aplicativo.
• Limpar credenciais da sessão do Flask: esse link limpa as credenciais de autorização armazenadas na sessão do Flask. Isso permite que você veja o que aconteceria se um usuário que já tiver concedido permissão ao seu app tentar executar uma solicitação de API em uma nova sessão. Ela também permite que você veja a resposta da API que o app receberia se um usuário tivesse revogado as permissões concedidas, e o app ainda tentaria autorizar uma solicitação com um token de acesso revogado.

Observação:para executar esse código localmente, você precisa ter seguido as instruções na seção pré-requisitos, incluindo a definição de http://localhost:8080 como um URI de redirecionamento válido para suas credenciais e o download do arquivo client_secret.json para essas credenciais no diretório de trabalho.

# -*- coding: utf-8 -*-

import os
import flask
import requests

import google.oauth2.credentials
import google_auth_oauthlib.flow
import googleapiclient.discovery

# This variable specifies the name of a file that contains the OAuth 2.0
# information for this application, including its client_id and client_secret.
CLIENT_SECRETS_FILE = "client_secret.json"

# This OAuth 2.0 access scope allows for full read/write access to the
# authenticated user's account and requires requests to use an SSL connection.
SCOPES = ['https://www.googleapis.com/auth/drive.metadata.readonly']
API_SERVICE_NAME = 'drive'
API_VERSION = 'v2'

app = flask.Flask(__name__)
# Note: A secret key is included in the sample so that it works.
# If you use this code in your application, replace this with a truly secret
# key. See https://flask.palletsprojects.com/quickstart/#sessions.
app.secret_key = 'REPLACE ME - this value is here as a placeholder.'


@app.route('/')
def index():
  return print_index_table()


@app.route('/test')
def test_api_request():
  if 'credentials' not in flask.session:
    return flask.redirect('authorize')

  # Load credentials from the session.
  credentials = google.oauth2.credentials.Credentials(
      **flask.session['credentials'])

  drive = googleapiclient.discovery.build(
      API_SERVICE_NAME, API_VERSION, credentials=credentials)

  files = drive.files().list().execute()

  # Save credentials back to session in case access token was refreshed.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.jsonify(**files)


@app.route('/authorize')
def authorize():
  # Create flow instance to manage the OAuth 2.0 Authorization Grant Flow steps.
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES)

  # The URI created here must exactly match one of the authorized redirect URIs
  # for the OAuth 2.0 client, which you configured in the API Console. If this
  # value doesn't match an authorized URI, you will get a 'redirect_uri_mismatch'
  # error.
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  authorization_url, state = flow.authorization_url(
      # Enable offline access so that you can refresh an access token without
      # re-prompting the user for permission. Recommended for web server apps.
      access_type='offline',
      # Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes='true')

  # Store the state so the callback can verify the auth server response.
  flask.session['state'] = state

  return flask.redirect(authorization_url)


@app.route('/oauth2callback')
def oauth2callback():
  # Specify the state when creating the flow in the callback so that it can
  # verified in the authorization server response.
  state = flask.session['state']

  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES, state=state)
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  # Use the authorization server's response to fetch the OAuth 2.0 tokens.
  authorization_response = flask.request.url
  flow.fetch_token(authorization_response=authorization_response)

  # Store credentials in the session.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  credentials = flow.credentials
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.redirect(flask.url_for('test_api_request'))


@app.route('/revoke')
def revoke():
  if 'credentials' not in flask.session:
    return ('You need to <a href="/authorize">authorize</a> before ' +
            'testing the code to revoke credentials.')

  credentials = google.oauth2.credentials.Credentials(
    **flask.session['credentials'])

  revoke = requests.post('https://oauth2.googleapis.com/revoke',
      params={'token': credentials.token},
      headers = {'content-type': 'application/x-www-form-urlencoded'})

  status_code = getattr(revoke, 'status_code')
  if status_code == 200:
    return('Credentials successfully revoked.' + print_index_table())
  else:
    return('An error occurred.' + print_index_table())


@app.route('/clear')
def clear_credentials():
  if 'credentials' in flask.session:
    del flask.session['credentials']
  return ('Credentials have been cleared.<br><br>' +
          print_index_table())


def credentials_to_dict(credentials):
  return {'token': credentials.token,
          'refresh_token': credentials.refresh_token,
          'token_uri': credentials.token_uri,
          'client_id': credentials.client_id,
          'client_secret': credentials.client_secret,
          'scopes': credentials.scopes}

def print_index_table():
  return ('<table>' +
          '<tr><td><a href="/test">Test an API request</a></td>' +
          '<td>Submit an API request and see a formatted JSON response. ' +
          '    Go through the authorization flow if there are no stored ' +
          '    credentials for the user.</td></tr>' +
          '<tr><td><a href="/authorize">Test the auth flow directly</a></td>' +
          '<td>Go directly to the authorization flow. If there are stored ' +
          '    credentials, you still might not be prompted to reauthorize ' +
          '    the application.</td></tr>' +
          '<tr><td><a href="/revoke">Revoke current credentials</a></td>' +
          '<td>Revoke the access token associated with the current user ' +
          '    session. After revoking credentials, if you go to the test ' +
          '    page, you should see an <code>invalid_grant</code> error.' +
          '</td></tr>' +
          '<tr><td><a href="/clear">Clear Flask session credentials</a></td>' +
          '<td>Clear the access token currently stored in the user session. ' +
          '    After clearing the token, if you <a href="/test">test the ' +
          '    API request</a> again, you should go back to the auth flow.' +
          '</td></tr></table>')


if __name__ == '__main__':
  # When running locally, disable OAuthlib's HTTPs verification.
  # ACTION ITEM for developers:
  #     When running in production *do not* leave this option enabled.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  # Specify a hostname and port that are set as a valid redirect URI
  # for your API project in the Google API Console.
  app.run('localhost', 8080, debug=True)

Ruby

Este exemplo usa o framework Sinatra.

require 'google/apis/drive_v2'
require 'google/api_client/client_secrets'
require 'json'
require 'sinatra'

enable :sessions
set :session_secret, 'setme'

get '/' do
  unless session.has_key?(:credentials)
    redirect to('/oauth2callback')
  end
  client_opts = JSON.parse(session[:credentials])
  auth_client = Signet::OAuth2::Client.new(client_opts)
  drive = Google::Apis::DriveV2::DriveService.new
  files = drive.list_files(options: { authorization: auth_client })
  "<pre>#{JSON.pretty_generate(files.to_h)}</pre>"
end

get '/oauth2callback' do
  client_secrets = Google::APIClient::ClientSecrets.load
  auth_client = client_secrets.to_authorization
  auth_client.update!(
    :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly',
    :redirect_uri => url('/oauth2callback'))
  if request['code'] == nil
    auth_uri = auth_client.authorization_uri.to_s
    redirect to(auth_uri)
  else
    auth_client.code = request['code']
    auth_client.fetch_access_token!
    auth_client.client_secret = nil
    session[:credentials] = auth_client.to_json
    redirect to('/')
  end
end

Node.js

Para executar esse exemplo:

1. No API Console, adicione o URL da máquina local à lista de URLs de redirecionamento. Por exemplo, adicione http://localhost.
2. Verifique se você tem o LTS de manutenção, o LTS ativo ou a versão atual do Node.js instalada.
3. Crie um novo diretório e mude para ele. Por exemplo:

   mkdir ~/nodejs-oauth2-example
   cd ~/nodejs-oauth2-example

4. Install the Google API Client Library for Node.js using npm:

   npm install googleapis

5. Crie os arquivos main.js com o conteúdo abaixo.
6. Execute o exemplo:

   node .\main.js

main.js

const http = require('http');
const https = require('https');
const url = require('url');
const { google } = require('googleapis');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI.
 * To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for read-only Drive activity.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

// Generate a url that asks permissions for the Drive activity scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

/* Global variable that stores user credential in this code example.
 * ACTION ITEM for developers:
 *   Store user's refresh token in your data store if
 *   incorporating this code into your real app.
 *   For more information on handling refresh tokens,
 *   see https://github.com/googleapis/google-api-nodejs-client#handling-refresh-tokens
 */
let userCredential = null;

async function main() {
  const server = http.createServer(async function (req, res) {
    // Example on redirecting user to Google's OAuth 2.0 server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }

    // Receive the callback from Google's OAuth 2.0 server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the OAuth 2.0 server response
      let q = url.parse(req.url, true).query;

      if (q.error) { // An error response e.g. error=access_denied
        console.log('Error:' + q.error);
      } else { // Get access and refresh tokens (if access_type is offline)
        let { tokens } = await oauth2Client.getToken(q.code);
        oauth2Client.setCredentials(tokens);

        /** Save credential to the global variable in case access token was refreshed.
          * ACTION ITEM: In a production app, you likely want to save the refresh token
          *              in a secure persistent database instead. */
        userCredential = tokens;

        // Example of using Google Drive API to list filenames in user's Drive.
        const drive = google.drive('v3');
        drive.files.list({
          auth: oauth2Client,
          pageSize: 10,
          fields: 'nextPageToken, files(id, name)',
        }, (err1, res1) => {
          if (err1) return console.log('The API returned an error: ' + err1);
          const files = res1.data.files;
          if (files.length) {
            console.log('Files:');
            files.map((file) => {
              console.log(`${file.name} (${file.id})`);
            });
          } else {
            console.log('No files found.');
          }
        });
      }
    }

    // Example on revoking a token
    if (req.url == '/revoke') {
      // Build the string for the POST request
      let postData = "token=" + userCredential.access_token;

      // Options for POST request to Google's OAuth 2.0 server to revoke a token
      let postOptions = {
        host: 'oauth2.googleapis.com',
        port: '443',
        path: '/revoke',
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          'Content-Length': Buffer.byteLength(postData)
        }
      };

      // Set up the request
      const postReq = https.request(postOptions, function (res) {
        res.setEncoding('utf8');
        res.on('data', d => {
          console.log('Response: ' + d);
        });
      });

      postReq.on('error', error => {
        console.log(error)
      });

      // Post the request with data
      postReq.write(postData);
      postReq.end();
    }
    res.end();
  }).listen(80);
}
main().catch(console.error);

HTTP/REST

Este exemplo em Python usa o framework Flask e a biblioteca Requests para demonstrar o fluxo da Web do OAuth 2.0. Recomendamos usar a biblioteca de cliente da API do Google para Python nesse fluxo. O exemplo na guia do Python usa a biblioteca de cliente.

import json

import flask
import requests


app = flask.Flask(__name__)

CLIENT_ID = '123456789.apps.googleusercontent.com'
CLIENT_SECRET = 'abc123'  # Read from a file or environmental variable in a real app
SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly'
REDIRECT_URI = 'http://example.com/oauth2callback'


@app.route('/')
def index():
  if 'credentials' not in flask.session:
    return flask.redirect(flask.url_for('oauth2callback'))
  credentials = json.loads(flask.session['credentials'])
  if credentials['expires_in'] <= 0:
    return flask.redirect(flask.url_for('oauth2callback'))
  else:
    headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])}
    req_uri = 'https://www.googleapis.com/drive/v2/files'
    r = requests.get(req_uri, headers=headers)
    return r.text


@app.route('/oauth2callback')
def oauth2callback():
  if 'code' not in flask.request.args:
    auth_uri = ('https://accounts.google.com/o/oauth2/v2/auth?response_type=code'
                '&client_id={}&redirect_uri={}&scope={}').format(CLIENT_ID, REDIRECT_URI, SCOPE)
    return flask.redirect(auth_uri)
  else:
    auth_code = flask.request.args.get('code')
    data = {'code': auth_code,
            'client_id': CLIENT_ID,
            'client_secret': CLIENT_SECRET,
            'redirect_uri': REDIRECT_URI,
            'grant_type': 'authorization_code'}
    r = requests.post('https://oauth2.googleapis.com/token', data=data)
    flask.session['credentials'] = r.text
    return flask.redirect(flask.url_for('index'))


if __name__ == '__main__':
  import uuid
  app.secret_key = str(uuid.uuid4())
  app.debug = False
  app.run()

Regras de validação do URI de redirecionamento

O Google aplica as regras de validação abaixo para redirecionar URIs a fim de ajudar os desenvolvedores a manter os aplicativos seguros. Os URIs de redirecionamento precisam aderir a essas regras. Consulte a seção 3 do RFC 3986 para ver as definições de domínio, host, caminho, consulta, esquema e userinfo mencionadas abaixo.

Regras de validação
Esquema	Os URIs de redirecionamento precisam usar o esquema HTTPS, e não HTTP simples. Os URIs do host local (incluindo URIs de endereço IP do host local) estão isentos dessa regra.
Host	Os hosts não podem ser endereços IP brutos. Os endereços IP do host local estão isentos dessa regra.
Domínio	Os TLDs do host (domínios de nível superior) precisam pertencer à lista pública de sufixos. Os domínios de host não podem ser “googleusercontent.com”. Os URIs de redirecionamento não podem conter domínios de encurtador de URL (por exemplo, goo.gl), a menos que o aplicativo seja proprietário do domínio. Além disso, se um app que tem um domínio mais curto escolher redirecionar para esse domínio, esse URI de redirecionamento vai precisar conter “/google-callback/” no caminho ou terminar com “/google-callback”.
Informações do usuário	Os URIs de redirecionamento não podem conter o subcomponente de informações do usuário.
Caminho	Os URIs de redirecionamento não podem conter uma travessia de caminho (também chamada de rastreamento de diretório), representado por “/..” ou “\..” ou pela codificação de URL deles.
Consulta	Os URIs de redirecionamento não podem conter redirecionamentos abertos.
Fragmentos	Os URIs de redirecionamento não podem conter o componente do fragmento.
Personagens	Os URIs de redirecionamento não podem conter determinados caracteres, incluindo os seguintes: Caracteres curinga ('*') Caracteres ASCII não imprimíveis Codificações de porcentagem inválidas (qualquer codificação de porcentagem que não segue a forma de codificação de URL de um sinal de porcentagem seguida por dois dígitos hexadecimais) Caracteres nulos (um caractere NULL codificado, por exemplo, %00, %C0%80)

Autorização incremental

No protocolo OAuth 2.0, seu app solicita autorização para acessar recursos, que são identificados por escopos. Considerar uma prática recomendada de experiência do usuário solicitar autorização de recursos sempre que você precisar. Para ativar essa prática, o servidor de autorização do Google oferece suporte à autorização incremental. Esse 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 concedidos ao usuário no projeto.

Por exemplo, um app que permite que as pessoas criem mixes de música e criem mixes pode precisar de poucos recursos no momento do login, talvez nada mais do que o nome da pessoa que faz login. No entanto, para salvar um mix concluído, é preciso ter acesso ao Google Drive. A maioria das pessoas acharia natural se só tivessem acesso ao Google Drive no momento em que o app realmente precisasse disso.

Nesse caso, no momento do login, o app pode solicitar os escopos openid e profile para fazer login básico e, depois, solicitar o escopo https://www.googleapis.com/auth/drive.file no momento da primeira solicitação para salvar uma combinação.

Para implementar a autorização incremental, conclua o fluxo normal para solicitar um token de acesso, mas verifique se a solicitação de autorização inclui escopos concedidos anteriormente. Essa abordagem permite que o app evite ter que gerenciar vários tokens de acesso.

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

• O token pode ser usado para acessar recursos correspondentes a qualquer um dos escopos incorporados na nova autorização combinada.
• Quando você usa o token de atualização para a autorização combinada a fim de conseguir um token de acesso, esse token representa a autorização combinada e pode ser usado para qualquer um dos valores scope incluídos na resposta.
• A autorização combinada inclui todos os escopos que o usuário concedeu ao projeto da API, mesmo que os benefícios tenham sido solicitados de clientes diferentes. Por exemplo, se um usuário concedeu acesso a um escopo usando o cliente de computador de um aplicativo e, em seguida, concedeu outro escopo para o mesmo aplicativo usando um cliente de dispositivos móveis, a autorização combinada incluirá os dois escopos.
• Se você revogar um token que representa uma autorização combinada, o acesso a todos os escopos da autorização em nome do usuário associado será revogado simultaneamente.

Atenção:a inclusão de escopos concedidos adicionará automaticamente os escopos concedidos anteriormente pelo usuário à solicitação de autorização. Uma página de aviso ou erro será exibida se o app não estiver aprovado para solicitar todos os escopos que podem ser retornados na resposta. Consulte Apps não verificados para mais informações.

As amostras de código específicas da linguagem na Etapa 1: definir parâmetros de autorização e o URL de redirecionamento HTTP/REST de exemplo na Etapa 2: redirecionar para o servidor OAuth 2.0 do Google usam autorização incremental. As amostras de código abaixo também mostram o código que você precisa adicionar para usar a autorização incremental.

PHP

$client->setIncludeGrantedScopes(true);

Python

Em Python, defina o argumento de palavra-chave include_granted_scopes como true para garantir que uma solicitação de autorização inclua escopos concedidos anteriormente. É muito possível que include_granted_scopes não seja o único argumento de palavra-chave que você definir, como mostrado no exemplo abaixo.

authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

Ruby

auth_client.update!(
  :additional_parameters => {"include_granted_scopes" => "true"}
)

Node.js

const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

HTTP/REST

GET https://accounts.google.com/o/oauth2/v2/auth?
  client_id=your_client_id&
  response_type=code&
  state=state_parameter_passthrough_value&
  scope=https%3A//www.googleapis.com/auth/drive.file&
  redirect_uri=https%3A//oauth2.example.com/code&
  prompt=consent&
  include_granted_scopes=true

Como atualizar um token de acesso (acesso off-line)

Os tokens de acesso expiram periodicamente e se tornam credenciais inválidas para uma solicitação de API relacionada. É possível atualizar um token de acesso sem solicitar permissão ao usuário (inclusive quando ele não está presente) se você solicitou acesso off-line aos escopos associados ao token.

• Se você usar uma biblioteca de cliente da API do Google, o objeto do cliente atualizará o token de acesso conforme necessário, desde que você configure esse objeto para acesso off-line.
• Se você não estiver usando uma biblioteca de cliente, defina o parâmetro de consulta HTTP access_type como offline ao redirecionar o usuário para o servidor OAuth 2.0 do Google. Nesse caso, o servidor de autorização do Google retorna um token de atualização quando você troca um código de autorização por um token de acesso. Então, se o token de acesso expirar (ou a qualquer momento), você poderá usar um token de atualização para receber um novo.

A solicitação de acesso off-line é um requisito para qualquer aplicativo que precise acessar uma API do Google quando o usuário não estiver presente. Por exemplo, um app que realiza serviços de backup ou executa ações em horários predeterminados precisa atualizar o token de acesso quando o usuário não está presente. O estilo de acesso padrão é chamado de online.

Aplicativos da Web do lado do servidor, aplicativos instalados e dispositivos recebem tokens de atualização durante o processo de autorização. Os tokens de atualização normalmente não são usados em aplicativos da Web do lado do cliente (JavaScript).

PHP

Se o aplicativo precisar de acesso off-line a uma API do Google, defina o tipo de acesso do cliente da API como offline:

$client->setAccessType("offline");

Depois que um usuário conceder acesso off-line aos escopos solicitados, será possível continuar a usar o cliente de API para acessar as APIs do Google em nome dele quando estiver off-line. O objeto cliente atualizará o token de acesso conforme necessário.

Python

Em Python, defina o argumento de palavra-chave access_type como offline para garantir que você possa atualizar o token de acesso sem precisar solicitar novamente a permissão do usuário. É muito possível que access_type não seja o único argumento de palavra-chave que você definir, como mostrado no exemplo abaixo.

authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

Depois que um usuário conceder acesso off-line aos escopos solicitados, será possível continuar a usar o cliente de API para acessar as APIs do Google em nome dele quando estiver off-line. O objeto cliente atualizará o token de acesso conforme necessário.

Ruby

Se o aplicativo precisar de acesso off-line a uma API do Google, defina o tipo de acesso do cliente da API como offline:

auth_client.update!(
  :additional_parameters => {"access_type" => "offline"}
)

Depois que um usuário conceder acesso off-line aos escopos solicitados, será possível continuar a usar o cliente de API para acessar as APIs do Google em nome dele quando estiver off-line. O objeto cliente atualizará o token de acesso conforme necessário.

Node.js

Se o aplicativo precisar de acesso off-line a uma API do Google, defina o tipo de acesso do cliente da API como offline:

const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

Depois que um usuário conceder acesso off-line aos escopos solicitados, será possível continuar a usar o cliente de API para acessar as APIs do Google em nome dele quando estiver off-line. O objeto cliente atualizará o token de acesso conforme necessário.

Os tokens de acesso expiram. Essa biblioteca usará automaticamente um token de atualização para receber um novo token de acesso se ele estiver prestes a expirar. Uma maneira fácil de garantir que você sempre armazene os tokens mais recentes é usar o evento de tokens:

oauth2Client.on('tokens', (tokens) => {
  if (tokens.refresh_token) {
    // store the refresh_token in your secure persistent database
    console.log(tokens.refresh_token);
  }
  console.log(tokens.access_token);
});

Esse evento de tokens ocorre apenas na primeira autorização. É necessário definir o access_type como offline ao chamar o método generateAuthUrl para receber o token de atualização. Se você já concedeu ao app as permissões necessárias sem definir as restrições apropriadas para receber um token de atualização, será necessário autorizá-lo novamente a receber um novo token de atualização.

Para definir o refresh_token mais tarde, use o método setCredentials:

oauth2Client.setCredentials({
  refresh_token: `STORED_REFRESH_TOKEN`
});

Assim que o cliente tiver um token de atualização, os tokens de acesso serão adquiridos e atualizados automaticamente na próxima chamada para a API.

HTTP/REST

Para atualizar um token de acesso, o aplicativo envia uma solicitação POST HTTPS para o servidor de autorização do Google (https://oauth2.googleapis.com/token) que inclui os seguintes parâmetros:

Campos
client_id	O ID do cliente recebido do API Console.
client_secret	A chave secreta do cliente recebida do API Console.
grant_type	Conforme definido na especificação do OAuth 2.0, o valor desse campo precisa ser definido como refresh_token.
refresh_token	O token de atualização retornado da troca de código de autorização.

O snippet a seguir mostra um exemplo de solicitação:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Se o usuário não tiver revogado o acesso concedido ao aplicativo, o servidor do token retornará um objeto JSON que contém um novo token de acesso. O snippet a seguir mostra um exemplo de resposta:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Há limites para o número de tokens de atualização que serão emitidos. Um limite por combinação de cliente/usuário e outro por usuário em todos os clientes. Salve tokens de atualização no armazenamento de longo prazo e continue usando-os, desde que permaneçam válidos. Se o aplicativo solicitar muitos tokens de atualização, ele poderá atingir esses limites. Nesse caso, os tokens de atualização mais antigos vão parar de funcionar.

Como revogar um token

Em alguns casos, o usuário pode querer revogar o acesso dado a um aplicativo. Um usuário pode revogar o acesso acessando as Configurações da conta. Consulte a seção Remover o acesso do site ou app dos sites e apps de terceiros com acesso à sua conta para mais informações.

Também é possível que um aplicativo revogue de forma programática o acesso concedido a ele. A revogação programática é importante nos casos em que um usuário cancela a inscrição, remove um aplicativo ou os recursos da 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.

PHP

Para revogar um token programaticamente, chame revokeToken():

$client->revokeToken();

Python

Para revogar programaticamente um token, faça uma solicitação para https://oauth2.googleapis.com/revoke, que inclui o token como parâmetro e define o cabeçalho Content-Type:

requests.post('https://oauth2.googleapis.com/revoke',
    params={'token': credentials.token},
    headers = {'content-type': 'application/x-www-form-urlencoded'})

Ruby

Para revogar programaticamente um token, faça uma solicitação HTTP para o endpoint oauth2.revoke:

uri = URI('https://oauth2.googleapis.com/revoke')
response = Net::HTTP.post_form(uri, 'token' => auth_client.access_token)

O token pode ser de acesso ou de atualização. Se for um token 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, o código de status da resposta será 200. Para condições de erro, um código de status 400 é retornado junto com um código de erro.

Node.js

Para revogar programaticamente um token, faça uma solicitação HTTPS POST ao endpoint /revoke:

const https = require('https');

// Build the string for the POST request
let postData = "token=" + userCredential.access_token;

// Options for POST request to Google's OAuth 2.0 server to revoke a token
let postOptions = {
  host: 'oauth2.googleapis.com',
  port: '443',
  path: '/revoke',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': Buffer.byteLength(postData)
  }
};

// Set up the request
const postReq = https.request(postOptions, function (res) {
  res.setEncoding('utf8');
  res.on('data', d => {
    console.log('Response: ' + d);
  });
});

postReq.on('error', error => {
  console.log(error)
});

// Post the request with data
postReq.write(postData);
postReq.end();

O parâmetro do token pode ser de acesso ou de atualização. Se for um token 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, o código de status da resposta será 200. Para condições de erro, um código de status 400 é retornado junto com um código de erro.

HTTP/REST

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}

O token pode ser de acesso ou de atualização. Se for um token 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, 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.

Observação:após uma resposta de revogação, pode levar algum tempo até que a revogação tenha efeito total.