Como usar o OAuth 2.0 para acessar as APIs do Google

As APIs do Google usam o protocolo OAuth 2.0 para autenticação e autorização. O Google oferece suporte a cenários comuns do OAuth 2.0, como os de servidores da Web, lado do cliente, instalados e aplicativos de dispositivos de entrada limitada.

Para começar, consiga as credenciais do cliente OAuth 2.0 do Google API Console. Em seguida, o aplicativo cliente solicita um token de acesso do servidor de autorização do Google, extrai um token da resposta e o envia para a API do Google que você quer acessar. Para uma demonstração interativa do uso do OAuth 2.0 com o Google (incluindo a opção de usar suas próprias credenciais de cliente), teste o OAuth 2.0 Playground.

Nesta página, você encontrará uma visão geral dos cenários de autorização do OAuth 2.0 compatíveis com o Google e links para conteúdos mais detalhados. Para saber mais sobre como usar o OAuth 2.0 para autenticação, consulte OpenID Connect.

Etapas básicas

Todos os aplicativos seguem um padrão básico ao acessar uma API do Google usando o OAuth 2.0. Em um nível superior, siga cinco etapas:

1. Consiga as credenciais do OAuth 2.0 do Google API Console.

Acesse Google API Console para receber as credenciais do OAuth 2.0, como o ID e a chave secreta do cliente, conhecidas pelo Google e pelo seu aplicativo. O conjunto de valores varia de acordo com o tipo de aplicativo que você está criando. Por exemplo, um aplicativo JavaScript não exige um secret, mas um aplicativo de servidor da Web.

2. Receber um token de acesso do Google Authorization Server.

Antes que seu aplicativo possa acessar dados particulares usando uma API do Google, ele precisa de um token de acesso que conceda acesso a essa API. Um único token de acesso pode conceder diferentes graus de acesso a várias APIs. Um parâmetro variável chamado scope controla o conjunto de recursos e operações permitidos por um token de acesso. Durante a solicitação de token de acesso, seu aplicativo envia um ou mais valores no parâmetro scope.

Há várias maneiras de fazer essa solicitação, e elas variam de acordo com o tipo de aplicativo que você está criando. Por exemplo, um aplicativo JavaScript pode solicitar um token de acesso usando um redirecionamento de navegador para o Google, enquanto um aplicativo instalado em um dispositivo que não tem um navegador usa solicitações de serviço da Web.

Algumas solicitações exigem uma etapa de autenticação em que o usuário faça login com a Conta do Google. Após fazer login, o usuário pergunta se quer conceder uma ou mais permissões solicitadas pelo aplicativo. Esse processo é chamado de consentimento do usuário.

Se o usuário conceder pelo menos uma permissão, o servidor de autorização do Google enviará ao seu aplicativo um token de acesso (ou um código de autorização que o aplicativo pode usar para receber um token de acesso) e uma lista de escopos de acesso concedidos por esse token. Se o usuário não conceder a permissão, o servidor retornará um erro.

Geralmente, é uma prática recomendada solicitar escopos incrementalmente, no momento em que o acesso é necessário, e não antecipado. Por exemplo, um app que queira salvar um evento em uma agenda não deve solicitar acesso ao Google Agenda até que o usuário pressione o botão "quo: Adicionar à agenda". Consulte Autorização incremental.

3. Examinar escopos de acesso concedidos pelo usuário.

Compare os escopos incluídos na resposta do token de acesso aos escopos necessários para acessar recursos e funcionalidades do aplicativo de acordo com o acesso a uma API do Google relacionada. Desative todos os recursos do app que não funcionam sem acesso à API relacionada.

O escopo incluído na sua solicitação pode não corresponder ao escopo incluído na sua resposta, mesmo que o usuário tenha concedido todos os escopos solicitados. Consulte a documentação de cada API do Google para ver os escopos necessários. Uma API pode mapear diversos valores de string de escopo para um único escopo de acesso, retornando a mesma string de escopo para todos os valores permitidos na solicitação. Exemplo: a API Google People pode retornar um escopo de https://www.googleapis.com/auth/contacts quando um app solicita que um usuário autorize um escopo de https://www.google.com/m8/feeds/. O método da API Google People people.updateContact requer um escopo concedido de https://www.googleapis.com/auth/contacts.

4. Envie o token de acesso para uma API.

Depois que um aplicativo recebe um token de acesso, ele o envia para uma API do Google em um cabeçalho de solicitação de autorização HTTP. É possível enviar tokens como parâmetros de string de consulta de URI, mas não é recomendado, porque os parâmetros de URI podem acabar em arquivos de registros que não são completamente seguros. Além disso, é uma prática recomendada do REST evitar evitar a criação de nomes de parâmetro de URI desnecessários.

Os tokens de acesso são válidos apenas para o conjunto de operações e recursos descrito no scope da solicitação de token. Por exemplo, se um token de acesso é emitido para a API Google Calendar, ele não concede acesso à API Google Contacts. No entanto, você pode enviar esse token de acesso para a API Google Calendar várias vezes para operações semelhantes.

5. Atualize o token de acesso, se necessário.

Os tokens de acesso têm duração limitada. Se o aplicativo precisar acessar uma API do Google além do ciclo de vida de um único token de acesso, ele receberá um token de atualização. Um token de atualização permite que seu aplicativo receba novos tokens de acesso.

Cenários

Aplicativos do servidor da Web

O endpoint do Google OAuth 2.0 é compatível com aplicativos de servidor da Web que usam linguagens e frameworks, como PHP, Java, Python, Ruby e ASP.NET.

A sequência de autorização começa quando seu aplicativo redireciona um navegador para um URL do Google. O URL inclui parâmetros de consulta que indicam o tipo de acesso solicitado. O Google lida com a autenticação, a seleção da sessão e o consentimento do usuário. O resultado é um código de autorização, que o aplicativo pode trocar por um token de acesso e um token de atualização.

O aplicativo deve armazenar o token de atualização para uso futuro e usar o token de acesso para acessar uma API do Google. Quando o token de acesso expira, o aplicativo usa o token de atualização para receber um novo.

Seu aplicativo envia uma solicitação de token ao servidor de autorização do Google,
 recebe um código de autorização, troca o código por um token e usa o token
 para chamar um endpoint da API do Google.

Para mais detalhes, consulte Usar o OAuth 2.0 para aplicativos de servidor da Web.

Apps instalados

O endpoint do Google OAuth 2.0 é compatível com aplicativos instalados em dispositivos como computadores, smartphones e tablets. Ao criar um ID do cliente pelo Google API Console, especifique que este é um aplicativo instalado e selecione o app para Android, Chrome, iOS, Universal Windows Platform (UWP) ou app para computador como o tipo de aplicativo.

O processo resulta em um ID do cliente e, em alguns casos, em uma chave secreta do cliente, que você incorpora no código-fonte do app. Nesse contexto, é claro que a chave secreta do cliente não é tratada como chave secreta.

A sequência de autorização começa quando seu aplicativo redireciona um navegador para um URL do Google. O URL inclui parâmetros de consulta que indicam o tipo de acesso solicitado. O Google lida com a autenticação, a seleção da sessão e o consentimento do usuário. O resultado é um código de autorização, que o aplicativo pode trocar por um token de acesso e um token de atualização.

O aplicativo deve armazenar o token de atualização para uso futuro e usar o token de acesso para acessar uma API do Google. Quando o token de acesso expira, o aplicativo usa o token de atualização para receber um novo.

Seu aplicativo envia uma solicitação de token ao servidor de autorização do Google,
 recebe um código de autorização, troca o código por um token e usa o token
 para chamar um endpoint da API do Google.

Para ver detalhes, consulte Usar o OAuth 2.0 para aplicativos instalados.

Aplicativos do lado do cliente (JavaScript)

O endpoint do Google OAuth 2.0 é compatível com aplicativos JavaScript executados em um navegador.

A sequência de autorização começa quando seu aplicativo redireciona um navegador para um URL do Google. O URL inclui parâmetros de consulta que indicam o tipo de acesso solicitado. O Google lida com a autenticação, a seleção da sessão e o consentimento do usuário.

O resultado é um token de acesso, que o cliente precisa validar antes de incluí-lo em uma solicitação de API do Google. Quando o token expira, o aplicativo repete o processo.

Seu aplicativo JS envia uma solicitação de token para o servidor de autorização do Google,
 recebe um token, valida o token e o usa para chamar um endpoint da API do
 Google.

Para mais detalhes, consulte Usar o OAuth 2.0 para aplicativos do lado do cliente.

Aplicativos em dispositivos de entrada limitada

O endpoint do Google OAuth 2.0 é compatível com aplicativos executados em dispositivos de entrada limitada, como consoles de jogos, câmeras de vídeo e impressoras.

A sequência de autorização começa com o aplicativo fazendo uma solicitação de serviço da Web a um URL do Google para um código de autorização. A resposta contém vários parâmetros, incluindo um URL e um código que o aplicativo mostra ao usuário.

O usuário recebe o URL e o código do dispositivo e, em seguida, muda para um dispositivo ou computador separado com recursos de entrada mais avançados. O usuário inicia um navegador, navega até o URL especificado, faz login e insere o código.

Enquanto isso, o aplicativo pesquisa um URL do Google em um intervalo especificado. Depois que o usuário aprova o acesso, a resposta do servidor do Google contém um token de acesso e um de atualização. O aplicativo deve armazenar o token de atualização para uso futuro e usar o token de acesso para acessar uma API do Google. Quando o token de acesso expira, o aplicativo usa o token de atualização para receber um novo.

O usuário faz login em um dispositivo separado que tenha um navegador.

Para ver mais detalhes, consulte Usar o OAuth 2.0 para dispositivos.

Contas de serviço

As APIs do Google, como a API Prediction e o Google Cloud Storage, podem agir em nome do seu aplicativo sem acessar as informações do usuário. Nessas situações, seu aplicativo precisa provar a própria identidade para a API, mas o consentimento do usuário não é necessário. Da mesma forma, em cenários corporativos, seu aplicativo pode solicitar acesso delegado a alguns recursos.

Para esses tipos de interação de servidor para servidor, você precisa de uma conta de serviço, que pertence ao aplicativo, e não a um usuário final individual. Seu aplicativo chama as APIs do Google em nome da conta de serviço, e o consentimento do usuário não é necessário. Em cenários que não sejam de conta de serviço, seu aplicativo chama as APIs do Google em nome dos usuários finais. O consentimento do usuário às vezes é necessário.

As credenciais de uma conta de serviço recebidas no Google API Consoleincluem um endereço de e-mail gerado exclusivo, um ID do cliente e pelo menos um par de chaves públicas/privadas. Use o ID do cliente e uma chave privada para criar um JWT assinado e construir uma solicitação de token de acesso no formato apropriado. O aplicativo envia a solicitação de token para o servidor de autorização do Google OAuth 2.0, que retorna um token de acesso. O aplicativo usa o token para acessar uma API do Google. Quando o token expira, o aplicativo repete o processo.

O aplicativo de servidor usa um JWT para solicitar um token do servidor de autorização do Google e, em seguida, usa o token para chamar um endpoint da API do Google. Nenhum usuário final está envolvido.

Para mais detalhes, consulte a documentação da conta de serviço.

Tamanho do token

O tamanho dos tokens pode variar, até os seguintes limites:

  • Códigos de autorização: 256 bytes
  • Tokens de acesso: 2.048 bytes
  • Tokens de atualização: 512 bytes

Os tokens de acesso retornados pela API Security Token Service do Google Cloud são estruturados de maneira semelhante aos tokens de acesso OAuth 2.0 da API do Google Cloud, mas têm limites de tamanho de token diferentes. Para mais detalhes, consulte a documentação da API.

O Google se reserva o direito de alterar o tamanho do token dentro desses limites, e seu aplicativo precisa oferecer suporte a tamanhos de token variáveis de acordo com isso.

Atualizar a validade do token

Escreva seu código para antecipar a possibilidade de um token de atualização concedido não funcionar mais. Um token de atualização pode parar de funcionar por um destes motivos:

  • O usuário revogou o acesso do app.
  • O token de atualização não é usado há seis meses.
  • O usuário alterou as senhas e o token de atualização contém escopos do Gmail.
  • A conta do usuário excedeu o número máximo de tokens de atualização concedidos (ativos).
  • O usuário pertence a uma organização do Google Cloud Platform com políticas de controle de sessão em vigor.

Um projeto do Google Cloud Platform com uma tela de permissão OAuth configurada para um tipo de usuário externo e um status de publicação de "quot;Testing"" recebe um token de atualização expirando em sete dias.

No momento, há um limite de 100 tokens de atualização por Conta do Google por ID do cliente do OAuth 2.0. Se o limite for atingido, a criação de um novo token de atualização invalidará automaticamente o mais antigo sem aviso prévio. Esse limite não se aplica a contas de serviço.

Há também um limite maior para o número total de tokens de atualização que uma conta de usuário ou de serviço pode ter em todos os clientes. A maioria dos usuários normais não excede esse limite, mas uma conta de desenvolvedor usada para testar uma implementação pode ser maior.

Se for necessário autorizar vários programas, máquinas ou dispositivos, uma solução alternativa é limitar o número de clientes autorizados por Conta do Google a 15 ou 20. Se você é um administrador do Google Workspace, pode criar outros usuários com privilégios de administrador e usá-los para autorizar alguns dos clientes.

Como lidar com políticas de controle de sessão para organizações do Google Cloud Platform (GCP)

Os administradores de organizações do GCP podem exigir a reautenticação frequente de usuários enquanto acessam os recursos do GCP usando o recurso de controle de sessão do Google Cloud. Essa política afeta o acesso ao Console do Google Cloud, ao SDK do Google Cloud (também conhecido como CLI gcloud) e a qualquer aplicativo OAuth de terceiros que exija o escopo do Cloud Platform. Se um usuário tiver uma política de controle de sessão em vigor durante a duração da sessão, as chamadas de API terão um erro semelhante ao que ocorreria se o token de atualização fosse revogado. A chamada falhará com um tipo de erro invalid_token. O tipo de suberro pode ser usado para distinguir entre um token de revogação e uma falha devido a uma política de controle de sessão. Como a duração da sessão pode ser muito limitada (de 1 a 24 horas), esse cenário precisa ser gerenciado de maneira otimizada, reiniciando uma sessão de autenticação.

Da mesma forma, não é permitido usar nem incentivar o uso de credenciais de usuário para implantação de servidor para servidor. Se as credenciais do usuário forem implantadas em um servidor para operações ou jobs de longa duração e um cliente aplicar políticas de controle de sessão a esses usuários, o aplicativo do servidor falhará porque não será possível reautenticar o usuário quando a duração da sessão expirar.

Para mais informações sobre como ajudar seus clientes a implantar esse recurso, consulte este artigo de ajuda focado em administradores.

Bibliotecas de cliente

As bibliotecas de cliente a seguir são integradas a frameworks conhecidos, o que simplifica a implementação do OAuth 2.0. Mais recursos serão adicionados às bibliotecas ao longo do tempo.