Esta página foi traduzida pela API Cloud Translation.
Switch to English

Usando OAuth 2.0 para acessar 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 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 credenciais de cliente OAuth 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 do uso do OAuth 2.0 com o Google (incluindo a opção de usar suas próprias credenciais de cliente), experimente 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 obter detalhes 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 OAuth 2.0. Basicamente, você segue cinco etapas:

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

Visite Google API Console para obter credenciais OAuth 2.0, como um ID de cliente e segredo do cliente, que são conhecidos pelo Google e por seu aplicativo. O conjunto de valores varia de acordo com o 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 chamado scope controla o conjunto de recursos e operações que um token de acesso permite. Durante a solicitação de token de acesso, seu aplicativo envia um ou mais valores no parâmetro de scope .

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 de 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 é denominado 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"; consulte 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 People pode retornar um escopo de https://www.googleapis.com/auth/contacts quando um aplicativo solicitou que um usuário autorizasse um escopo de https://www.google.com/m8/feeds/ ; o método people.updateContact API do Google People requer um escopo concedido de https://www.googleapis.com/auth/contacts .

4. Envie o token de acesso a uma API.

Depois que um aplicativo obtém um token de acesso, ele envia o token 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 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ão válidos apenas para o conjunto de operações e recursos descritos no scope da solicitação 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 vida útil limitada. 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 obter detalhes, consulte Usando OAuth 2.0 para aplicativos de servidor da web .

Aplicativos instalados

O ponto de extremidade Google OAuth 2.0 oferece suporte a aplicativos instalados em dispositivos como computadores, dispositivos móveis e tablets. Ao criar um ID de cliente por meio do Google API Console , especifique que este é um aplicativo instalado e selecione Android, aplicativo Chrome, iOS, Plataforma Universal do Windows (UWP) ou aplicativo Desktop como tipo de aplicativo.

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 obter 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 obter detalhes, consulte Usando OAuth 2.0 para aplicativos do lado do 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. Após o usuário aprovar 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 obter 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 esses tipos de interações servidor a servidor, você precisa de uma conta de serviço , que é uma conta que pertence ao 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.)

As credenciais de uma conta de serviço, que você obtém em Google API Console, incluem um endereço de e-mail gerado que é exclusivo, um ID de cliente e pelo menos um par de chave 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 obter detalhes, consulte a documentação da 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

Os tokens de acesso retornados pela API Security Token Service do Google Cloud são estruturados de forma semelhante aos tokens de acesso OAuth 2.0 da API do Google, mas têm limites de tamanho de token diferentes. Para obter 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.

Expiração do token de atualização

Você deve escrever seu código para antecipar a possibilidade de que um token de atualização concedido não funcione mais. Um token de atualização pode parar de funcionar por um destes motivos:

  • O usuário revogou o acesso ao 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. Esse 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ê precisar 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 a 15 ou 20. Se você for um administrador do Google Workspace , poderá criar usuários adicionais com privilégios administrativos 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 do GCP podem exigir a reautenticação frequente dos usuários enquanto eles acessam os recursos do GCP, usando o recurso de controle de sessão do Google Cloud. Essa política afeta o acesso ao Google Cloud Console, ao Google Cloud SDK (também conhecido como gcloud CLI) e a qualquer aplicativo OAuth de terceiros que requeira o escopo do Cloud Platform. Se um usuário tiver uma política de controle de sessão em vigor, no final da duração da sessão, suas chamadas de API apresentarão um erro semelhante ao que aconteceria se o token de atualização fosse revogado. Como as durações das sessões podem ser muito limitadas (entre 1 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 obter mais informações sobre como ajudar seus clientes a implantar esse recurso, consulte este artigo de ajuda voltado para o administrador.

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.