Usando OAuth 2.0 para acessar APIs do Google

APIs do Google usam o protocolo OAuth 2.0 para autenticação e autorização. O Google oferece suporte a cenários OAuth 2.0 comuns, como aqueles para aplicativos de servidor da web, do lado do cliente, instalados e de dispositivo de entrada limitada.

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

Esta página oferece uma visão geral dos cenários de autorização OAuth 2.0 que o Google oferece suporte e fornece links para conteúdo mais detalhado. Para detalhes sobre como usar o OAuth 2.0 para autenticação, consulte OpenID Ligação .

Etapas básicas

Todos os aplicativos seguem um padrão básico ao acessar uma API do Google usando OAuth 2.0. Basicamente, você segue cinco etapas:

1. Obter credenciais do OAuth 2.0 do Google API Console.

Visite o Google API Console para obter credenciais OAuth 2.0 como um segredo ID de cliente e cliente que são conhecidos para o Google e sua aplicação. O conjunto de valores varia com base no tipo de aplicativo que você está construindo. Por exemplo, um aplicativo JavaScript não requer um segredo, mas um aplicativo de servidor da web exige.

2. Obtenha um token de acesso do servidor de autorização do Google.

Antes que seu aplicativo possa acessar dados privados usando uma API do Google, ele deve obter um token de acesso que conceda acesso a essa API. Um único token de acesso pode conceder vários graus de acesso a várias APIs. Um parâmetro variável chamada scope controla o conjunto de recursos e operações que um acesso licenças de tokens. Durante a solicitação de acesso em token, o aplicativo envia um ou mais valores no scope parâmetro.

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

Algumas solicitações exigem uma etapa de autenticação em que o usuário efetua login com sua conta do Google. Depois de fazer login, o usuário é questionado se deseja conceder uma ou mais permissões que seu aplicativo está solicitando. Este 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á a seu aplicativo um token de acesso (ou um código de autorização que seu aplicativo pode usar para obter 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 de forma incremental, no momento em que o acesso é necessário, em vez de no início. Por exemplo, um aplicativo que deseja oferecer suporte ao salvamento de um evento em um calendário não deve solicitar acesso ao Google Agenda até que o usuário pressione o botão "Adicionar ao calendário"; veja autorização Incremental .

3. Examine os escopos de acesso concedidos pelo usuário.

Compare os escopos incluídos na resposta do token de acesso aos escopos necessários para acessar os recursos e a funcionalidade de seu aplicativo que dependem do acesso a uma API do Google relacionada. Desative todos os recursos do seu aplicativo que não funcionem sem acesso à API relacionada.

O escopo incluído em sua solicitação pode não corresponder ao escopo incluído em sua resposta, mesmo se o usuário concedeu todos os escopos solicitados. Consulte a documentação de cada API do Google para os escopos necessários para acesso. Uma API pode mapear vários 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 do Google As pessoas podem voltar um escopo de https://www.googleapis.com/auth/contacts quando um aplicativo solicitado um usuário autorizar um escopo de https://www.google.com/m8/feeds/ ; o método API Google Pessoas people.updateContact requer um escopo concedido de https://www.googleapis.com/auth/contacts .

4. Envie o token de acesso a uma API.

Depois de um aplicativo obtém um token de acesso, ele envia o token para a API do Google em um cabeçalho de solicitação HTTP Authorization . É possível enviar tokens como parâmetros de string de consulta de URI, mas não recomendamos, porque os parâmetros de URI podem acabar em arquivos de log que não são completamente seguros. Além disso, é uma boa prática REST evitar a criação de nomes de parâmetro URI desnecessários. Observe que o suporte a string de consulta será suspenso em 1º de junho de 2021.

Os tokens de acesso só são válidas para o conjunto de operações e recursos descritos no scope do pedido de token. Por exemplo, se um token de acesso for emitido para a API do Google Agenda, ele não concederá acesso à API de contatos do Google. Você pode, no entanto, enviar esse token de acesso à API do Google Agenda várias vezes para operações semelhantes.

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

Os tokens de acesso têm tempos de vida limitados. Se seu aplicativo precisa de acesso a uma API do Google além do tempo de vida de um único token de acesso, ele pode obter um token de atualização. Um token de atualização permite que seu aplicativo obtenha novos tokens de acesso.

Cenários

Aplicativos de servidor web

O ponto de extremidade Google OAuth 2.0 oferece suporte a aplicativos de servidor da web que usam linguagens e estruturas 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 que está sendo solicitado. O Google lida com a autenticação do usuário, 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. Depois que o token de acesso expira, o aplicativo usa o token de atualização para obter 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 Usando OAuth 2.0 para aplicações Web do servidor .

Aplicativos instalados

O ponto de extremidade Google OAuth 2.0 oferece suporte a aplicativos instalados em dispositivos como computadores, dispositivos móveis e tablets. Quando você cria um ID do cliente através da Google API Console , especificar que este é um aplicativo instalado, em seguida, selecione Android, app Chrome, iOS Universal Plataforma do Windows (UWP), ou aplicativo Desktop como o tipo de aplicação.

O processo resulta em um ID do cliente e, em alguns casos, um segredo do cliente, que você incorpora no código-fonte do seu aplicativo. (Neste contexto, o segredo do cliente obviamente não é tratado como um segredo.)

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 que está sendo solicitado. O Google lida com a autenticação do usuário, 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. Depois que o token de acesso expira, o aplicativo usa o token de atualização para obter 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 Usando OAuth 2.0 para aplicativos instalados .

Aplicativos do lado do cliente (JavaScript)

O ponto de extremidade Google OAuth 2.0 oferece suporte a aplicativos JavaScript que são 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 que está sendo solicitado. O Google lida com a autenticação do usuário, a seleção da sessão e o consentimento do usuário.

O resultado é um token de acesso, que o cliente deve 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 ao servidor de autorização do Google, recebe um token, valida o token e usa o token para chamar um endpoint da API do Google.

Para mais detalhes, consulte Usando OAuth 2.0 para aplicativos cliente .

Aplicativos em dispositivos de entrada limitada

O endpoint Google OAuth 2.0 oferece suporte a 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 obter 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 obtém a URL e o código do dispositivo e, a seguir, muda para um dispositivo ou computador separado com recursos de entrada mais avançados. O usuário inicia um navegador, navega até a URL especificada, efetua 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 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. Depois que o token de acesso expira, o aplicativo usa o token de atualização para obter um novo.

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

Para mais detalhes, consulte Usando OAuth 2.0 para dispositivos .

Contas de serviço

As APIs do Google, como a Prediction API 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 sua própria identidade para a API, mas nenhum consentimento do usuário é necessário. Da mesma forma, em cenários corporativos, seu aplicativo pode solicitar acesso delegado a alguns recursos.

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

Credenciais de uma conta de serviço, que você obter do Google API Console, incluir um endereço gerado e-mail que é único, um ID do cliente, e pelo menos um par de chaves pública / privada. Você usa 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. Em seguida, seu aplicativo envia a solicitação de token ao 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.

Seu 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 de conta de serviço .

Tamanho do token

Os tokens podem variar em tamanho, até os seguintes limites:

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

Acesso fichas retornado por do Google Cloud API Segurança Token Service são estruturados de forma semelhante a API OAuth Google tokens de acesso 2.0, mas têm diferentes limites de tamanho de token. Para mais detalhes, consulte a documentação da API .

O Google reserva-se o direito de alterar o tamanho do token dentro desses limites e seu aplicativo deve oferecer suporte a tamanhos de token variáveis ​​de acordo.

Vencimento do token de atualização

Você deve escrever 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 revogado o acesso de seu aplicativo .
  • 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 que possui políticas de controle de sessão em vigor.

Um projeto do Google Cloud Platform com uma tela de consentimento OAuth configurada para um tipo de usuário externo e um status de publicação de "Teste" recebe um token de atualização que expira em 7 dias.

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

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

Se você precisa autorizar vários programas, máquinas ou dispositivos, uma solução alternativa é limitar o número de clientes que você autoriza por Conta do Google para 15 ou 20. Se você é um administrador do Google Workspace , você pode criar usuários adicionais com privilégios administrativos e use-os para autorizar alguns dos clientes.

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

Os administradores de organizações de BPC pode exigir reautenticação frequente de usuários enquanto eles acessam recursos de BPC, usando o recurso de controle de sessão do Google Cloud . Isto impacta política de acesso ao Google Cloud Console, o SDK do Google Cloud (também conhecido como o CLI gcloud), e qualquer aplicação OAuth de terceiros que requer o escopo Cloud Platform. Se um usuário tem uma política de controle de sessão no lugar, em seguida, no termo da duração da sessão, as suas chamadas de API irá erro fora semelhante ao que aconteceria se o token de atualização foi revogada - a chamada falhará com um tipo de erro invalid_token ; o tipo de sub-erro 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 as durações da sessão podem ser muito limitadas (entre 1 hora a 24 horas), este cenário deve ser tratado normalmente reiniciando uma sessão de autenticação.

Da mesma forma, você não deve usar ou encorajar 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 trabalhos ou operações de longa execução e um cliente aplicar políticas de controle de sessão a esses usuários, o aplicativo do servidor falhará, pois não haverá como autenticar novamente o usuário quando a duração da sessão expirar.

Para mais informações sobre como ajudar seus clientes a implementar este recurso, consulte este artigo de ajuda admin-focalizada.

Bibliotecas cliente

As seguintes bibliotecas cliente integram-se a estruturas populares, o que torna a implementação do OAuth 2.0 mais simples. Mais recursos serão adicionados às bibliotecas ao longo do tempo.