Usar o OAuth 2.0 para aplicativos de servidor para servidor

O sistema OAuth 2.0 do Google oferece suporte a interações de servidor para servidor, como as que ocorrem entre um servidor e um serviço do Google. Neste cenário, você precisa de uma conta de serviço, que é uma conta que pertence ao seu aplicativo e não a um usuário final. Seu chama as APIs do Google em nome da conta de serviço. Assim, os usuários não são diretamente envolvidas. Esse cenário às vezes é chamado de "OAuth de duas etapas", ou "2LO". (O termo relacionado "OAuth de três etapas" refere-se a cenários em que seu aplicativo chama APIs do Google em nome de 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 utiliza APIs do Google para funcionar com os próprios dados, e não com os dados do usuário. Por exemplo, um aplicativo que usa o Google Cloud O Datastore para persistência de dados usaria uma conta de serviço para autenticar as chamadas para o API Google Cloud Datastore.

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

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

Visão geral

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

Em seguida, o aplicativo se prepara para fazer chamadas de API autorizadas usando o método para solicitar um token de acesso do servidor de autenticação do OAuth 2.0.

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

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 um par de chaves pública/privada. Se a delegação em todo o domínio estiver ativada, o ID do cliente também fará parte das credenciais da conta de serviço.

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

Caso seu aplicativo seja executado no Google Compute Engine, uma conta de serviço também será configurada automaticamente ao criar o projeto, mas é necessário especificar os escopos precisa de acesso quando você cria uma instância do Google Compute Engine. Para mais informações, consulte Como preparar uma instância para usar contas de serviço.

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

首先,创建一个服务帐户:

  1. 打开 Service accounts page
  2. If prompted, select a project, or create a new one.
  3. 单击创建服务帐户
  4. Service account details下,键入服务帐户的名称、ID 和描述,然后点击Create and continue
  5. 可选:在Grant this service account access to project下,选择要授予服务帐户的 IAM 角色。
  6. 单击继续
  7. 可选:在Grant users access to this service account下,添加允许使用和管理服务帐户的用户或组。
  8. 单击完成

接下来,创建一个服务帐户密钥:

  1. 单击您创建的服务帐户的电子邮件地址。
  2. 单击密钥选项卡。
  3. 添加密钥下拉列表中,选择创建新密钥
  4. 单击创建

您的新公钥/私钥对已生成并下载到您的机器上;它作为私钥的唯一副本。您有责任安全地存储它。如果您丢失了这个密钥对,您将需要生成一个新的。

Você pode voltar para o API Console a qualquer momento para ver o endereço de e-mail, público impressões digitais de chaves e outras informações, ou para gerar pares de chave pública/privada adicionais. Para mais detalhes sobre credenciais de contas de serviço na API Console, consulte Contas de serviço no API Console arquivo de ajuda.

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

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

Usando uma conta do Google Workspace, um administrador do Workspace da organização pode autorizar uma para acessar dados de usuários do Workspace em nome dos 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 usaria uma conta de serviço para acessar a API Google Calendar em em nome dos usuários. Autorizar uma conta de serviço a acessar dados em nome dos usuários em um domínio é também é chamado de "delegar autoridade em todo o domínio" a uma conta de serviço.

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

  1. No do seu domínio do Google Workspace No Admin Console, acesse o Menu principal > Segurança > Controle de dados e acesso > 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 Add new;
  4. No campo ID do cliente, digite o ID do cliente da conta de serviço. Você pode encontrar ID do cliente da sua conta de serviço na Service accounts page:
  5. No campo Escopos do OAuth (delimitados por vírgula), digite a lista de escopos deve receber acesso a ele. Por exemplo, se o aplicativo precisa de um domínio acesso total à API Google Drive e à API Google Calendar, digite: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar.
  6. Clique em Autorizar.

Seu aplicativo agora tem autoridade para fazer chamadas de API como usuários no domínio do Workspace (para "falsificar" usuários). Ao se preparar para fazer essas chamadas de API delegadas, especifique explicitamente o usuário a ser personificar.

Como se preparar para fazer uma chamada de API delegada

Java

Depois de conseguir o endereço de e-mail do cliente e a chave privada do API Console, use o Biblioteca de cliente de APIs do Google para Java para criar um objeto GoogleCredential usando as credenciais da conta de serviço e os escopos que seu aplicativo precisa acessar. Exemplo:

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

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

Se você estiver desenvolvendo um aplicativo no Google Cloud Platform, poderá usar a credenciais padrão do aplicativo o que pode simplificar o processo.

Delegar autoridade em todo o domínio

Se você tiver delegado acesso em todo o domínio à conta de serviço e quiser personificar uma conta de usuário, especifique o endereço de e-mail da conta de usuário com o Método createDelegated do objeto GoogleCredential. Por exemplo:

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("workspace-user@example.com");

O código acima usa o objeto GoogleCredential para chamar o createDelegated() . O argumento do método createDelegated() precisa ser um usuário que pertença ao seu do Google Workspace. O código que faz a solicitação usará essa credencial para chamar o Google APIs usando sua conta de serviço.

Python

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

  1. Crie um objeto Credentials usando as credenciais da conta de serviço e o escopos aos quais seu aplicativo precisa de acesso. Por 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 aplicativo no Google Cloud Platform, poderá usar a credenciais padrão do aplicativo o que pode simplificar o processo.

  2. Delegar autoridade em todo o domínio

    Se você tiver delegado 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. Exemplo:

    delegated_credentials = credentials.with_subject('user@example.org')

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

HTTP/REST

Depois de conseguir o ID do cliente e a chave privada do API Console, seu aplicativo precisa concluir a 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. Processe 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, será possível usá-lo para chamar uma API do Google. Se a resposta não incluir uma solicitação token, seu JWT e sua solicitação de token podem não estar formatados corretamente, ou a conta de serviço pode não tem permissão para acessar os escopos solicitados.

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

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

O restante desta seção descreve as especificidades da criação de um JWT, assiná-lo, formando a solicitação do token de acesso e lidando com a resposta.

Como criar um JWT

Um JWT é composto por três partes: um cabeçalho, um conjunto de declarações e um 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 fornece resiliência contra alterações de codificação devido a operações de codificação repetidas. O cabeçalho, o conjunto de declarações e são concatenados com um caractere de ponto (.).

Um JWT é composto da seguinte maneira:

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

A string de base da 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 de a declaração e o [ID da chave da conta de serviço key](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) usado para assinar o JWT. O algoritmo e o formato são obrigatórios, e cada campo tem apenas um valor. À medida que algoritmos e formatos adicionais forem introduzidos, esse cabeçalho será alterado de maneira adequada. O ID da chave é opcional. Se um ID incorreto for especificado, o GCP tentará todas as chaves associadas à conta de serviço para verificar o token e rejeitar o token se nenhuma chave válida é 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 disso é 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 solicitado (escopos), o destino do token, o emissor, a hora em que o token foi emitido, e o ciclo de vida do token. A maioria dos campos é obrigatória. Assim como o cabeçalho JWT, O conjunto de declarações JWT é um objeto JSON 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. Eles podem aparecer em qualquer ordem o 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 alvo pretendido da declaração. Ao criar um token de acesso solicitação esse valor será sempre https://oauth2.googleapis.com/token.
exp O prazo de validade da declaração, especificado em segundos desde 00:00:00 UTC, 1o de janeiro de 1970. Esse valor tem no máximo uma hora após o horário de emissão.
iat A hora em que a declaração foi emitida, especificada em segundos desde 00:00:00 UTC, 1o de janeiro de 1970.

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

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "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 corporativos, um aplicativo pode usar a delegação em todo o domínio para agir em nome de um determinado usuário em uma organização. Permissão para fazer esse tipo de falsificação de identidade deve ser concedido antes que um aplicativo possa falsificar a identidade de um usuário e geralmente é tratado por um e superadministrador. Para mais informações, consulte Controle o acesso às APIs com a delegação em todo o domínio.

Para receber 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 JWT como o valor do parâmetro sub.

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

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

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

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "sub": "some.user@example.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
Como codificar o conjunto de declarações JWT

Assim como no cabeçalho JWT, o conjunto de declarações JWT deve ser serializado para UTF-8 e Base64url seguro. codificados. Veja abaixo um exemplo de representação JSON de um conjunto de declarações JWT:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
Como calcular a assinatura

Assinatura JSON da Web (JWS) é a especificação que orienta a mecânica de geração da assinatura do 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 somente algoritmo de assinatura compatível com o servidor de autorização do Google OAuth 2.0 é RSA usando Algoritmo de hash SHA-256. Isso é expresso como RS256 no alg. no 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 hash SHA-256) com a chave privada recebida de o Google API Console. A saída será uma matriz de bytes.

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. Ela deve ser o seguinte (as quebras de linha foram adicionadas para maior clareza):

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

Veja abaixo um exemplo de JWT antes da codificação Base64url:

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

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

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

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 POST HTTPS, e o corpo é URL codificados. O URL é exibido 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 string a seguir, codificada pelo URL conforme necessário: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion O JWT, incluindo assinatura.

Veja abaixo um despejo bruto da solicitação POST HTTPS usada em um token de acesso solicitação:

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

Abaixo está 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 o JWT e a solicitação de token de acesso estiverem formatados corretamente e a conta de serviço tiver permissão para executar a operação, a resposta JSON do servidor de autorização inclui 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 a janela de duração especificada pelo Valor de expires_in.

Como chamar APIs do Google

Java

Use o objeto GoogleCredential para chamar as APIs do Google concluindo a seguintes etapas:

  1. Crie um objeto de serviço para a API que você deseja chamar usando o GoogleCredential. Exemplo:
    SQLAdmin sqladmin =
        new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();
  2. Faça solicitações ao serviço da API usando o interface fornecida pelo objeto de serviço. Por exemplo, para listar as instâncias dos bancos de dados do Cloud SQL no empolgante-exemplo-123 projeto:
    SQLAdmin.Instances.List instances =
        sqladmin.instances().list("exciting-example-123").execute();

Python

Use o objeto Credentials autorizado para chamar as APIs do Google concluindo a seguintes etapas:

  1. Crie um objeto de serviço para a API que você quer chamar. Você cria um objeto de serviço chame a função build com o nome e a versão da API e a objeto Credentials autorizado. Por exemplo, para chamar a versão 1beta3 do API Cloud SQL Administration
    import googleapiclient.discovery
    
    sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
  2. Faça solicitações ao serviço da API usando o interface fornecida pelo objeto de serviço. Por exemplo, para listar as instâncias dos bancos de dados do Cloud SQL no empolgante-exemplo-123 projeto:
    response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP/REST

Depois que o aplicativo obtém um token de acesso, você pode usá-lo para fazer chamadas a um serviço em nome de uma determinada conta de serviço ou 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 à API incluindo uma consulta access_token ou um valor Bearer do 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 casos, você pode usar uma biblioteca de cliente para configurar suas chamadas para as APIs do Google (por exemplo, quando chamando a API Drive Files).

Você pode experimentar todas as APIs do Google e visualizar seus escopos em OAuth 2.0 Playground.

Exemplos GET HTTP

Uma chamada ao drive.files endpoint (a API Drive Files) usando a API 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 para o usuário autenticado com o access_token parâmetro da string de consulta:

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. Este é 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 do parâmetro da 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 fornecidos pelo valor expires_in. Quando um token de acesso expira, a aplicativo deve 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 está autorizada no o Admin Console do domínio do usuário.

Verifique se a conta de serviço está autorizada no página "Delegação em todo o domínio" do Admin Console para o usuário no sub reivindicação (campo).

Embora esse processo geralmente leve alguns minutos, a autorização pode levar até 24 horas para todos os usuários na 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éricos) no Admin Console. No página "Delegação em todo o domínio" no Admin Console, remover e adicionar o cliente novamente pelo 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 serão autorizados no Admin Console.

Verifique se a conta de serviço está autorizada no página "Delegação em todo o domínio" do Admin Console para o usuário no Declaração sub (campo) e que ela inclui todos os escopos que você está solicitando na declaração scope do JWT.

Embora esse processo geralmente leve alguns minutos, a autorização pode levar até 24 horas para todos os usuários na sua Conta do Google.

admin_policy_enforced (qualquer valor) A Conta do Google não pode autorizar um ou mais escopos solicitados devido à políticas do administrador do Google Workspace.

Consulte o artigo de ajuda para admins do Google Workspace Controle quais aplicativos de terceiros os apps internos acessam os dados do Google Workspace. o administrador pode restringir o acesso a todos os escopos ou escopos sensíveis e restritos até é concedido explicitamente ao seu ID do cliente OAuth.

invalid_client (qualquer valor)

O cliente OAuth ou o token JWT é inválido ou foi 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 e a conta de serviço OAuth estão configurado corretamente e se você está usando o endereço de e-mail correto.

Verifique se o token JWT está correto e foi emitido para o ID do cliente na solicitação.

invalid_grant Not a valid email. O usuário não existe. Verifique se o endereço de e-mail na declaração sub (campo) 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.

Normalmente, isso significa que o horário do sistema local não está correto. Isso também pode acontecer se o o valor de exp está a mais de 65 minutos adiantado em relação ao valor de iat; ou o valor de exp é menor que o valor de iat.

Verifique se o relógio no sistema em que o JWT é gerado está correto. Se necessário, sincronize seu tempo com NTP do Google:

invalid_grant Invalid JWT Signature.

A declaração JWT é assinada com uma chave privada não associada à conta de serviço pelo e-mail do cliente ou se a chave usada tiver sido excluída, desativada ou expirou.

Como alternativa, a asserção JWT pode estar codificada de forma incorreta. Ela deve ser Codificada em base64, sem novas linhas ou sinais de igual de padding.

Decodifique o conjunto de declarações 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 scope (campo) do JWT está preenchida e compare os escopos que ele contém com os escopos documentados das APIs que deseja usar, para garantir que não haja erros ou erros de digitação.

Observe que a lista de escopos na declaração scope precisa ser separada por espaços, não vírgulas.

disabled_client The OAuth client was disabled. A chave usada para assinar a declaração JWT está desativada.

Acesse 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 ao Google Contas em um determinado Organização do Google Cloud.

Use uma conta de serviço da organização para fazer a autenticação. Confirme os tipo de usuário do aplicativo para seu aplicativo OAuth.

Adendo: autorização da 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 do portador, em vez de um token de acesso OAuth 2.0. Quando isso é possível, você pode evitar ter para 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 GitHub das APIs do Google, você pode 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. Não se esqueça de mantenha o arquivo JSON recebido ao criar a conta.
  2. Usando qualquer biblioteca JWT padrão, como a encontrada em jwt.io, crie um JWT com um cabeçalho e payload, como no exemplo a seguir:
    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "abcdef1234567890"
    }
    .
    {
      "iss": "123456-compute@developer.gserviceaccount.com",
      "sub": "123456-compute@developer.gserviceaccount.com",
      "aud": "https://firestore.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600
    }
    • No campo kid do cabeçalho, especifique a chave privada da conta de serviço. ID. Esse valor está no campo private_key_id da sua conta de serviço arquivo JSON.
    • Nos campos iss e sub, especifique o e-mail da sua conta de serviço. endereço IP. Esse valor está no campo client_email do seu serviço arquivo JSON da conta de serviço.
    • No campo aud, especifique o endpoint da API. Por exemplo, https://SERVICE.googleapis.com/.
    • No campo iat, especifique o horário Unix atual. Para o exp, especifique o tempo exatamente 3.600 segundos depois, quando o JWT e depois ela expira.

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

Exemplo:

Java

Usando google-api-java-client e java-jwt:

GoogleCredential credential =
        GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = credential.getServiceAccountPrivateKey();
String privateKeyId = credential.getServiceAccountPrivateKeyId();

long now = System.currentTimeMillis();

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

Python

Usando PyJWT:

iat = time.time()
exp = iat + 3600
payload = {'iss': '123456-compute@developer.gserviceaccount.com',
           'sub': '123456-compute@developer.gserviceaccount.com',
           '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 o token do portador:
    GET /v1/projects/abc/databases/123/indexes HTTP/1.1
    Authorization: Bearer SIGNED_JWT
    Host: firestore.googleapis.com

Como implementar a Proteção entre contas

Uma etapa adicional que você deve tomar para proteger as informações está implementando o usando o serviço de proteção entre contas do Google. Esse serviço permite que você inscrever-se em notificações de ocorrências de segurança, que fornecem informações ao aplicativo sobre grandes mudanças na conta do usuário. Você pode então usar as informações para tomar medidas dependendo como você decide responder aos eventos.

Alguns exemplos dos tipos de evento enviados ao seu app pelo serviço de Proteção entre contas do Google são:

  • 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 Proteger contas de usuário com a página "Proteção entre contas" para mais informações sobre como implementar a Proteção entre contas e para conferir a lista completa de eventos disponíveis.