Usar o OAuth 2.0 para aplicativos de servidor para servidor

<0x0 Para mais informações, consulte Visão geral da autenticação na documentação do Google Cloud Platform.

O sistema Google OAuth 2.0 aceita interações de servidor para servidor, como as que ocorrem entre um aplicativo da Web e um serviço do Google. Para esse cenário, 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, evitando o envolvimento direto dos usuários. Esse cenário às vezes é chamado de "OAuth de duas pernas" ou "2LO". O termo relacionado "OAuth de três etapas" se refere a cenários em que seu aplicativo chama as APIs do Google em nome dos usuários finais e em que o consentimento do usuário às vezes é necessário.

Normalmente, um aplicativo usa uma conta de serviço quando usa APIs do Google para trabalhar com os próprios dados, em vez dos dados de um usuário. Por exemplo, um aplicativo que usa o Google Cloud Datastore para persistência de dados usaria uma conta de serviço para autenticar as chamadas à API do Google Cloud Datastore.

Os administradores de domínio do Google Workspace também podem conceder às contas de serviço autoridade em todo o domínio para acessar dados do usuário em nome dos usuários no domínio.

Este documento descreve como um aplicativo pode concluir o fluxo OAuth 2.0 de servidor para servidor usando uma biblioteca de cliente das APIs do Google (recomendado) ou HTTP.

Com algumas APIs do Google, é possível fazer chamadas de API autorizadas usando um JWT assinado em vez de usar o OAuth 2.0, o que pode economizar uma solicitação de rede. Consulte Adendo: autorização de conta de serviço sem OAuth.

Visão geral

Para oferecer suporte às interações de servidor para servidor, primeiro crie uma conta de serviço para seu projeto no API Console. Se quiser acessar os dados dos usuários na sua conta do Google Workspace, delegue o acesso em todo o domínio à conta de serviço.

Em seguida, o aplicativo se prepara para fazer chamadas de API autorizadas usando as credenciais da conta de serviço para solicitar um token de acesso do servidor de autenticação OAuth 2.0.

Por fim, seu aplicativo pode usar o token de acesso para chamar as APIs do Google.

Recomendação:seu aplicativo pode concluir essas tarefas usando a biblioteca de cliente das APIs do Google para sua linguagem ou interagindo diretamente com o sistema OAuth 2.0 usando HTTP. No entanto, a mecânica das interações de autenticação de servidor para servidor exige que os aplicativos criem e assinem criptograficamente JSON Web Tokens (JWTs). É fácil cometer erros graves que podem ter um impacto severo na segurança do aplicativo.

Por isso, recomendamos usar bibliotecas, como as de cliente das APIs do Google, que abstraem a criptografia do código do seu aplicativo.

Como criar uma conta de serviço

As credenciais de uma conta de serviço incluem um endereço de e-mail gerado que é exclusivo e pelo menos um par de chaves públicas/privadas. Se a delegação em todo o domínio estiver ativada, um ID do cliente também fará parte das credenciais da conta de serviço.

Se o aplicativo for executado no Google App Engine, uma conta de serviço será configurada automaticamente quando você criar o projeto.

Se o aplicativo for executado no Google Compute Engine, uma conta de serviço também será configurada automaticamente ao criar o projeto, mas você precisará especificar os escopos a que o aplicativo precisa de acesso ao criar uma instância do Google Compute Engine. Para mais informações, consulte Preparar uma instância para usar contas de serviço.

Se o aplicativo não for executado no Google App Engine ou no Google Compute Engine, você precisará obter essas credenciais no Google API Console. Para gerar credenciais de conta de serviço ou ver as credenciais públicas que você já gerou, faça o seguinte:

Primeiro, crie uma conta de serviço:

1. Abra o Service accounts page.
2. If prompted, select a project, or create a new one.
3. Clique em Criar conta de serviço .
4. Em Detalhes da conta de serviço , digite um nome, ID e descrição para a conta de serviço e clique em Criar e continuar .
5. Opcional: em Grant this service account access to project , selecione os papéis do IAM a serem concedidos à conta de serviço.
6. Clique em Continuar .
7. Opcional: em Conceder aos usuários acesso a esta conta de serviço , adicione os usuários ou grupos que têm permissão para usar e gerenciar a conta de serviço.
8. Clique em Concluído .

Em seguida, crie uma chave de conta de serviço:

1. Clique no endereço de e-mail da conta de serviço que você criou.
2. Clique na guia Chaves .
3. Na lista suspensa Adicionar chave , selecione Criar nova chave .
4. Clique em Criar .

Seu novo par de chaves pública/privada é gerado e baixado em sua máquina; ele serve como a única cópia da chave privada. Você é responsável por armazená-lo com segurança. Se você perder esse par de chaves, precisará gerar um novo.

Você pode voltar ao API Console a qualquer momento para conferir o endereço de e-mail, as impressões digitais da chave pública e outras informações ou para gerar mais pares de chaves públicas/privadas. Para mais detalhes sobre as credenciais da conta de serviço no API Console, consulte Contas de serviço no arquivo de ajuda do API Console.

Anote o endereço de e-mail da conta de serviço e armazene o arquivo de chave privada da conta em um local acessível ao aplicativo. Seu aplicativo precisa deles para fazer chamadas de API autorizadas.

Observação:armazene e gerencie chaves privadas com segurança nos ambientes de desenvolvimento e produção. O Google não mantém uma cópia das suas chaves privadas, apenas das chaves públicas. Consulte a seção Como processar credenciais do cliente com segurança das políticas do OAuth 2.0 para mais informações.

Delegar autoridade em todo o domínio à conta de serviço

Com uma conta do Google Workspace, um administrador do Workspace da organização pode autorizar um aplicativo a acessar dados de usuários do Workspace em nome de usuários no domínio do Google Workspace. Por exemplo, um aplicativo que usa a API Google Calendar para adicionar eventos às agendas de todos os usuários em um domínio do Google Workspace usa uma conta de serviço para acessar essa API em nome dos usuários. Autorizar uma conta de serviço a acessar dados em nome de usuários em um domínio é, às vezes, denominado "delegar autoridade em todo o domínio" a uma conta de serviço.

Observação:quando você usa o Google Workspace Marketplace para instalar um aplicativo no seu domínio, as permissões necessárias são concedidas automaticamente ao aplicativo durante a instalação. Não é necessário autorizar manualmente as contas de serviço usadas pelo aplicativo.

Observação:embora seja possível usar contas de serviço em aplicativos executados em um domínio do Google Workspace, elas não são membros da sua conta do Google Workspace e não estão sujeitas às políticas de domínio definidas pelos administradores do Google Workspace. Por exemplo, uma política definida no Admin Console do Google Workspace para restringir a capacidade dos usuários finais do Google Workspace de compartilhar documentos fora do domínio não se aplicaria a contas de serviço.

Para delegar autoridade em todo o domínio a uma conta de serviço, um superadministrador do domínio do Google Workspace precisa concluir as etapas a seguir:

1. No Admin Console do seu domínio do Google Workspace, acesse Menu principal > Segurança > Controle de acesso e dados > Controles de API.
2. No painel Delegação em todo o domínio, selecione Gerenciar a delegação em todo o domínio.
3. Clique em Adicionar novo.
4. No campo ID do cliente, digite o ID do cliente da conta de serviço. É possível encontrar o ID do cliente da sua conta de serviço em Service accounts page.
5. No campo Escopos do OAuth (delimitados por vírgula), insira a lista de escopos a que seu aplicativo deve ter acesso. Por exemplo, se o aplicativo precisar de acesso total em todo o domínio à API Google Drive e à API Google Calendar, insira: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar.
6. Clique em Autorizar.

Agora, seu aplicativo tem autoridade para fazer chamadas de API como usuários no seu domínio do Workspace (para "representar" usuários). Ao se preparar para fazer essas chamadas de API delegadas, você especifica explicitamente o usuário a ser representado.

Observação:geralmente, o acesso por substituição de usuário é concedido alguns minutos após a adição do ID do cliente, mas, em alguns casos, pode levar até 24 horas para ser propagado a todos os usuários da sua Conta do Google.

Preparar-se para fazer uma chamada de API delegada

Java

Depois de receber o endereço de e-mail do cliente e a chave privada do API Console, use a biblioteca Google Auth para Java para criar um objeto GoogleCredentials com as credenciais da conta de serviço e os escopos que seu aplicativo precisa acessar. Exemplo:

import com.google.auth.oauth2.GoogleCredentials;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

Se você estiver desenvolvendo um app no Google Cloud Platform, use as credenciais padrão do aplicativo para simplificar o processo.

Delegar autoridade em todo o domínio

Se você delegou o acesso em todo o domínio à conta de serviço e quer representar uma conta de usuário, especifique o endereço de e-mail da conta de usuário com o método createDelegated do objeto GoogleCredentials. Por exemplo:

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("[e-mail]");

O código acima usa o objeto GoogleCredentials para chamar o método createDelegated(). O argumento do método createDelegated() precisa ser um usuário que pertence à sua conta do Workspace. O código que faz a solicitação usa essa credencial para chamar as APIs do Google com sua conta de serviço.

Python

Depois de receber o endereço de e-mail do cliente e a chave privada do API Console, use a biblioteca de cliente de APIs do Google para Python para concluir as seguintes etapas:

1. Crie um objeto Credentials com base nas credenciais da conta de serviço e nos escopos que seu aplicativo precisa acessar. Exemplo:

   from google.oauth2 import service_account
   
   SCOPES = ['https://www.googleapis.com/auth/sqlservice.admin']
   SERVICE_ACCOUNT_FILE = '/path/to/service.json'
   
   credentials = service_account.Credentials.from_service_account_file(
           SERVICE_ACCOUNT_FILE, scopes=SCOPES)

   Se você estiver desenvolvendo um app no Google Cloud Platform, use as credenciais padrão do aplicativo para simplificar o processo.

2. Delegar autoridade em todo o domínio

   Se você tiver delegado o acesso em todo o domínio à conta de serviço e quiser representar uma conta de usuário, use o método with_subject de um objeto ServiceAccountCredentials atual. Exemplo:

   delegated_credentials = credentials.with_subject('[e-mail]')

Use o objeto "Credentials" para chamar as APIs do Google no seu aplicativo.

HTTP/REST

Recomendação:embora seu aplicativo possa concluir essas tarefas interagindo diretamente com o sistema OAuth 2.0 usando HTTP, a mecânica das interações de autenticação de servidor para servidor exige que os aplicativos criem e assinem criptograficamente JSON Web Tokens (JWTs). É fácil cometer erros graves que podem ter um impacto severo na segurança do aplicativo.

Por isso, recomendamos usar bibliotecas, como as de cliente das APIs do Google, que abstraem a criptografia do código do seu aplicativo.

Depois de receber o ID do cliente e a chave privada do API Console, seu aplicativo precisa concluir as seguintes etapas:

1. Crie um JSON Web Token (JWT, pronunciado "jot") que inclua um cabeçalho, um conjunto de declarações e uma assinatura.
2. Solicite um token de acesso do servidor de autorização do Google OAuth 2.0.
3. Processar a resposta JSON retornada pelo servidor de autorização.

As seções a seguir descrevem como concluir essas etapas.

Se a resposta incluir um token de acesso, use-o para chamar uma API do Google. Se a resposta não incluir um token de acesso, talvez seu JWT e sua solicitação de token não estejam formatados corretamente ou a conta de serviço não tenha permissão para acessar os escopos solicitados.

Quando o token de acesso expira, seu aplicativo gera outro JWT, assina e solicita outro token de acesso.

O restante desta seção descreve os detalhes da criação e assinatura de um JWT, da formação da solicitação de token de acesso e do tratamento da resposta.

Como criar um JWT

Um JWT é composto de três partes: um cabeçalho, um conjunto de declarações e uma assinatura. O cabeçalho e o conjunto de declarações são objetos JSON. Esses objetos JSON são serializados para bytes UTF-8 e codificados usando a codificação Base64url. Essa codificação oferece resiliência contra mudanças devido a operações repetidas. O cabeçalho, o conjunto de declarações e a assinatura são concatenados com um caractere de ponto (.).

Um JWT é composto da seguinte forma:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

A string de base para a assinatura é a seguinte:

{Base64url encoded header}.{Base64url encoded claim set}

Como formar o cabeçalho JWT

O cabeçalho consiste em três campos que indicam o algoritmo de assinatura, o formato da declaração e o [ID da chave da conta de serviço](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) usada para assinar o JWT. O algoritmo e o formato são obrigatórios, e cada campo tem apenas um valor. À medida que outros algoritmos e formatos forem introduzidos, esse cabeçalho vai mudar de acordo. O ID da chave é opcional. Se um ID incorreto for especificado, o GCP vai tentar todas as chaves associadas à conta de serviço para verificar o token e rejeitá-lo se nenhuma chave válida for encontrada. O Google se reserva o direito de rejeitar tokens com IDs de chave incorretos no futuro.

As contas de serviço dependem do algoritmo RSA SHA-256 e do formato de token JWT. Como resultado, a representação JSON do cabeçalho é a seguinte:

{"alg":"RS256","typ":"JWT", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}

A representação Base64url é a seguinte:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=

Como formar o conjunto de declarações JWT

O conjunto de declarações JWT contém informações sobre o JWT, incluindo as permissões solicitadas (escopos), o destino do token, o emissor, o horário em que o token foi emitido e o ciclo de vida dele. A maioria dos campos é obrigatória. Assim como o cabeçalho JWT, o conjunto de declarações JWT é um objeto JSON e é usado no cálculo da assinatura.

Reivindicações obrigatórias

As declarações obrigatórias no conjunto de declarações JWT são mostradas abaixo. Elas podem aparecer em qualquer ordem no conjunto de reivindicações.

Nome	Descrição
iss	O endereço de e-mail da conta de serviço.
scope	Uma lista delimitada por espaço das permissões solicitadas pelo aplicativo.
aud	Um descritor do destino pretendido da declaração. Ao fazer uma solicitação de token de acesso, esse valor é sempre https://oauth2.googleapis.com/token.
exp	O prazo de validade da declaração, especificado como segundos desde 00:00:00 UTC, 1º de janeiro de 1970. Esse valor tem um máximo de uma hora após o horário de emissão.
iat	O horário em que a declaração foi emitida, especificado como segundos desde 00:00:00 UTC, 1º de janeiro de 1970.

Confira abaixo a representação JSON dos campos obrigatórios em um conjunto de declarações JWT:

{
  "iss": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Outras reivindicações

Em alguns casos empresariais, um aplicativo pode usar a delegação em todo o domínio para agir em nome de um usuário específico em uma organização. A permissão para realizar esse tipo de representação precisa ser concedida antes que um aplicativo possa representar um usuário. Geralmente, isso é feito por um superadministrador. Para mais informações, consulte Controlar o acesso às APIs com a delegação em todo o domínio.

Para conseguir um token de acesso que conceda a um aplicativo acesso delegado a um recurso, inclua o endereço de e-mail do usuário no conjunto de declarações do JWT como o valor do campo sub.

Nome	Descrição
sub	O endereço de e-mail do usuário para quem o aplicativo está solicitando acesso delegado.

Se um aplicativo não tiver permissão para representar um usuário, a resposta a uma solicitação de token de acesso que inclua o campo sub será um erro.

Confira abaixo um exemplo de conjunto de declarações JWT que inclui o campo sub:

{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Codificar o conjunto de declarações JWT

Assim como o cabeçalho JWT, o conjunto de declarações JWT precisa ser serializado para UTF-8 e codificado em Base64url seguro. Confira abaixo um exemplo de representação JSON de um conjunto de declarações JWT:

{
  "iss": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Como calcular a assinatura

A JSON Web Signature (JWS) é a especificação que orienta a mecânica de geração da assinatura para o JWT. A entrada da assinatura é a matriz de bytes do seguinte conteúdo:

{Base64url encoded header}.{Base64url encoded claim set}

O algoritmo de assinatura no cabeçalho JWT precisa ser usado ao calcular a assinatura. O único algoritmo de assinatura compatível com o servidor de autorização do Google OAuth 2.0 é RSA usando o algoritmo de hash SHA-256. Ele é expresso como RS256 no campo alg do cabeçalho JWT.

Assine a representação UTF-8 da entrada usando SHA256withRSA (também conhecido como RSASSA-PKCS1-V1_5-SIGN com a função de hash SHA-256) com a chave privada obtida do Google API Console. A saída será uma matriz de bytes.

Em seguida, a assinatura precisa ser codificada em Base64url. O cabeçalho, o conjunto de declarações e a assinatura são concatenados com um caractere de ponto (.). O resultado é o JWT. Ele deve ser o seguinte (quebras de linha adicionadas para maior clareza):

{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}

Confira abaixo um exemplo de JWT antes da codificação em base64url:

{"alg":"RS256","typ":"JWT"}.
{
"iss":"[e-mail]",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]

Confira abaixo um exemplo de JWT assinado e pronto para transmissão:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ

Como fazer a solicitação de token de acesso

Depois de gerar o JWT assinado, um aplicativo pode usá-lo para solicitar um token de acesso. Essa solicitação de token de acesso é uma solicitação HTTPS POST, e o corpo é codificado por URL. O URL é mostrado abaixo:

https://oauth2.googleapis.com/token

Os seguintes parâmetros são obrigatórios na solicitação HTTPS POST:

Nome	Descrição
grant_type	Use a seguinte string, codificada por URL conforme necessário: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	O JWT, incluindo a assinatura.

A seguir, há um despejo bruto da solicitação HTTPS POST usada em uma solicitação de token de acesso:

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

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ

Confira abaixo a mesma solicitação, usando curl:

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

Como processar a resposta

Se a solicitação de JWT e token de acesso estiverem bem formadas e a conta de serviço tiver permissão para realizar a operação, a resposta JSON do servidor de autorização incluirá um token de acesso. Veja a seguir um exemplo de resposta:

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

Os tokens de acesso podem ser reutilizados durante o período especificado pelo valor expires_in.

Como chamar APIs do Google

Java

Use o objeto GoogleCredentials para chamar as APIs do Google seguindo estas etapas:

1. Crie um objeto de serviço para a API que você quer chamar usando o objeto GoogleCredentials. Exemplo:

   SQLAdmin sqladmin =
       new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credentials).build();

2. Faça solicitações ao serviço de API usando a interface fornecida pelo objeto de serviço. Por exemplo, para listar as instâncias de bancos de dados do Cloud SQL no projeto exciting-example-123:

   SQLAdmin.Instances.List instances =
       sqladmin.instances().list("exciting-example-123").execute();

Python

Use o objeto Credentials autorizado para chamar as APIs do Google seguindo estas etapas:

1. Crie um objeto de serviço para a API que você quer chamar. Para criar um objeto de serviço, chame a função build com o nome e a versão da API e o objeto Credentials autorizado. Por exemplo, para chamar a versão 1beta3 da API Cloud SQL Administration:

   import googleapiclient.discovery
   
   sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)

2. Faça solicitações ao serviço de API usando a interface fornecida pelo objeto de serviço. Por exemplo, para listar as instâncias de bancos de dados do Cloud SQL no projeto exciting-example-123:

   response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP/REST

Depois que o aplicativo recebe um token de acesso, ele pode ser usado para fazer chamadas a uma API do Google em nome de uma determinada conta de serviço ou 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 à API incluindo um parâmetro de consulta access_token ou um valor de cabeçalho HTTP Authorization Bearer. Quando possível, o cabeçalho HTTP é preferível, porque as strings de consulta tendem a ficar visíveis nos registros do servidor. Na maioria dos casos, é possível usar uma biblioteca de cliente para configurar suas chamadas às APIs do Google (por exemplo, ao chamar a API Drive Files).

Você pode testar todas as APIs do Google e conferir os escopos delas no OAuth 2.0 Playground.

Exemplos de HTTP GET

Uma chamada para o endpoint drive.files (API Drive Files) usando o cabeçalho HTTP Authorization: Bearer pode ser semelhante ao seguinte. É necessário 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 do 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. Confira 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, como alternativa, a opção de parâmetro de string de consulta:

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

Quando os tokens de acesso expiram

Os tokens de acesso emitidos pelo servidor de autorização do Google OAuth 2.0 expiram após a duração fornecida pelo valor expires_in. Quando um token de acesso expira, o aplicativo precisa gerar outro JWT, assiná-lo e solicitar outro token de acesso.

Códigos de erro do JWT

Campo error	Campo error_description	Significado	Como resolver
unauthorized_client	Unauthorized client or scope in request.	Se você estiver tentando usar a delegação em todo o domínio, a conta de serviço não estará autorizada no Admin Console do domínio do usuário.	Verifique se a conta de serviço está autorizada na página Delegação em todo o domínio do Admin Console para o usuário na declaração (campo) sub. Embora isso geralmente leve alguns minutos, a autorização pode levar até 24 horas para ser propagada a todos os usuários da sua Conta do Google.
unauthorized_client	Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested.	Uma conta de serviço foi autorizada usando o endereço de e-mail do cliente em vez do ID do cliente (numérico) no Admin Console.	Na página Delegação em todo o domínio do Admin Console, remova o cliente e adicione-o novamente com o ID numérico.
access_denied	(qualquer valor)	Se você estiver usando a delegação em todo o domínio, um ou mais escopos solicitados não estarão autorizados no Admin Console.	Verifique se a conta de serviço está autorizada na página Delegação em todo o domínio do Admin Console para o usuário na declaração sub (campo) e se ela inclui todos os escopos solicitados na declaração scope do JWT. Embora isso geralmente leve alguns minutos, a autorização pode levar até 24 horas para ser propagada a todos os usuários da sua Conta do Google.
admin_policy_enforced	(qualquer valor)	A Conta do Google não pode autorizar 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 saber como um administrador pode restringir o acesso a todos os escopos ou a escopos sensíveis e restritos até que o acesso seja concedido explicitamente ao ID do cliente OAuth.
invalid_client	(qualquer valor)	O cliente OAuth ou o token JWT é inválido ou está configurado incorretamente. Consulte a descrição do erro para mais detalhes.	Verifique se o token JWT é válido e contém declarações corretas. Verifique se o cliente OAuth e a conta de serviço estão configurados corretamente e se você está usando o endereço de e-mail certo. Verifique se o token JWT está correto e foi emitido para o ID do cliente na solicitação.
deleted_client	(qualquer valor)	O cliente OAuth usado para fazer a solicitação foi excluído. A exclusão pode acontecer de forma manual ou automática no caso de clientes inativos . Os clientes excluídos podem ser restaurados em até 30 dias após a exclusão. Saiba mais.	Use um ID de cliente que ainda esteja ativo.
invalid_grant	Not a valid email.	O usuário não existe.	Verifique se o endereço de e-mail na declaração (campo) sub está correto.
invalid_grant	Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your 'iat' and 'exp' values and use a clock with skew to account for clock differences between systems.	Em geral, isso significa que a hora do sistema local não está correta. Isso também pode acontecer se o valor de exp for mais de 65 minutos no futuro do valor de iat ou se o valor de exp for menor que o valor de iat.	Verifique se o relógio do sistema em que o JWT é gerado está correto. Se necessário, sincronize seu horário com o NTP do Google.
invalid_grant	Invalid JWT Signature.	A declaração JWT foi assinada com uma chave privada não associada à conta de serviço identificada pelo e-mail do cliente ou a chave usada foi excluída, desativada ou expirou. Como alternativa, a declaração JWT pode estar codificada incorretamente. Ela precisa ser codificada em Base64, sem novas linhas ou sinais de igual de padding.	Decodifique o conjunto de declarações do JWT e verifique se a chave que assinou a declaração está associada à conta de serviço. Tente usar uma biblioteca OAuth fornecida pelo Google para garantir que o JWT seja gerado corretamente.
invalid_scope	Invalid OAuth scope or ID token audience provided.	Nenhum escopo foi solicitado (lista vazia de escopos) ou um dos escopos solicitados não existe (ou seja, é inválido).	Verifique se a declaração (campo) scope do JWT está preenchida e compare os escopos que ela contém com os escopos documentados das APIs que você quer usar para garantir que não haja erros ou erros de digitação. A lista de escopos na declaração scope precisa ser separada por espaços, não por vírgulas.
disabled_client	The OAuth client was disabled.	A chave usada para assinar a declaração JWT está desativada.	Acesse o Google API Consolee, em IAM e administrador > Contas de serviço, ative a conta de serviço que contém o "ID da chave" usado para assinar a declaração.
org_internal	This client is restricted to users within its organization.	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 do Google Cloud específica.	Use uma conta de serviço da organização para autenticar. Confirme a configuração do tipo de usuário para seu aplicativo OAuth.

Adendo: autorização de conta de serviço sem OAuth

Com algumas APIs do Google, é possível fazer chamadas de API autorizadas usando um JWT assinado diretamente como um token de portador, em vez de um token de acesso OAuth 2.0. Quando isso é possível, você evita ter que fazer uma solicitação de rede ao servidor de autorização do Google antes de fazer uma chamada de API.

Se a API que você quer chamar tiver uma definição de serviço publicada no repositório do GitHub das APIs do Google, será possível fazer chamadas de API autorizadas usando um JWT em vez de um token de acesso. Para fazer isso, siga estas etapas:

1. Crie uma conta de serviço conforme descrito acima. Guarde o arquivo JSON que você recebe ao criar a conta.
2. Usando qualquer biblioteca JWT padrão, como uma encontrada em jwt.io, crie um JWT com um cabeçalho e um payload como o exemplo a seguir:

   {
     "alg": "RS256",
     "typ": "JWT",
     "kid": "abcdef1234567890"
   }
   .
   {
     "iss": "[e-mail]",
     "sub": "[e-mail]",
     "aud": "https://firestore.googleapis.com/",
     "iat": 1511900000,
     "exp": 1511903600
   }

• No campo kid do cabeçalho, especifique o ID da chave privada da sua conta de serviço. Você encontra esse valor no campo private_key_id do arquivo JSON da conta de serviço.
• Nos campos iss e sub, especifique o endereço de e-mail da conta de serviço. Você encontra esse valor no campo client_email do arquivo JSON da conta de serviço.
• No campo aud, especifique o endpoint da API. Por exemplo, https://SERVICE.googleapis.com/.
• Para o campo iat, especifique a hora atual do Unix. Para o campo exp, especifique a hora exatamente 3.600 segundos depois, quando o JWT vai expirar.

Assine o JWT com RSA-256 usando a chave privada encontrada no arquivo JSON da conta de serviço.

Exemplo:

Java

Usando google-auth-library-java e java-jwt:

import com.google.auth.oauth2.ServiceAccountCredentials;
...
GoogleCredentials credentials =
        GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = ((ServiceAccountCredentials) credentials).getPrivateKey();
String privateKeyId = ((ServiceAccountCredentials) credentials).getPrivateKeyId();

long now = System.currentTimeMillis();

try {
    Algorithm algorithm = Algorithm.RSA256(null, privateKey);
    String signedJwt = JWT.create()
        .withKeyId(privateKeyId)
        .withIssuer("[e-mail]")
        .withSubject("[e-mail]")
        .withAudience("https://firestore.googleapis.com/")
        .withIssuedAt(new Date(now))
        .withExpiresAt(new Date(now + 3600 * 1000L))
        .sign(algorithm);
} catch ...

Python

Ao usar PyJWT:

iat = time.time()
exp = iat + 3600
payload = {'iss': '[e-mail]',
           'sub': '[e-mail]',
           'aud': 'https://firestore.googleapis.com/',
           'iat': iat,
           'exp': exp}
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
signed_jwt = jwt.encode(payload, PRIVATE_KEY_FROM_JSON, headers=additional_headers,
                       algorithm='RS256')

1. Chame a API usando o JWT assinado como token de portador:

   GET /v1/projects/abc/databases/123/indexes HTTP/1.1
   Authorization: Bearer SIGNED_JWT
   Host: firestore.googleapis.com

Implementar a Proteção entre contas

Outra etapa para proteger as contas dos usuários é implementar a proteção entre contas usando o serviço de proteção entre contas do Google. Com esse serviço, você pode assinar notificações de eventos de segurança que fornecem informações ao seu aplicativo sobre mudanças importantes na conta do usuário. Depois, use as informações para tomar medidas dependendo de como você decide responder aos eventos.

Alguns exemplos dos tipos de eventos enviados ao seu app pelo Serviço de proteção entre contas do Google:

• https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
• https://schemas.openid.net/secevent/oauth/event-type/token-revoked
• https://schemas.openid.net/secevent/risc/event-type/account-disabled

Consulte a página Proteger contas de usuário com a Proteção entre contas para mais informações sobre como implementar a Proteção entre contas e a lista completa de eventos disponíveis.