Como migrar para a API Service Account Credentials

A API Service Account Credentials cria credenciais de curta duração para contas de serviço de gerenciamento de identidade e acesso (IAM, na sigla em inglês). Também é possível usar essa API para assinar JSON Web Tokens (JWTs), bem como blobs de dados binários que contêm outros tipos de tokens.

A API IAM também contém métodos para assinar JWTs e blobs binários. Desde 1º de julho de 2020, esses métodos estão obsoletos na API REST e em todas as bibliotecas de cliente da API IAM. Além disso, se você usar a CLI do Google Cloud para assinar JWTs, talvez seja necessário adicionar uma nova declaração ao conjunto de declarações do JWT. Ainda é possível usar os métodos descontinuados, mas eles não oferecem suporte a recursos avançados, como o agrupamento de solicitações HTTP. Em vez disso, recomendamos que você migre para a API Service Account Credentials.

Em comparação com a API IAM, a API Service Account Credentials oferece mais flexibilidade para o prazo de validade dos JWTs assinados. Além disso, a API Service Credentials adiciona vários novos métodos de API para gerar tokens de representação.

Nesta página, explicamos como atualizar seu código para usar a API Service Account Credentials. Se você tiver comentários sobre essa alteração, preencha o formulário de feedback. Também é possível usar o endereço de e-mail [e-mail] para solicitar suporte e fornecer feedback detalhado.

Antes de começar

• Enable the Service Account Credentials API.

  Enable the API

Como ativar registros de auditoria

Se você quiser receber registros de auditoria para solicitações de assinatura de JWTs e blobs, será necessário ativar os registros de auditoria de acesso a dados para a API IAM. A ativação de registros de auditoria de acesso a dados para a API IAM também permite esses registros de auditoria para a API Service Account Credentials.

Há algumas diferenças notáveis entre as entradas de registro que cada API gera:

Diferenças para entradas de registro de auditoria
Nome do método	API IAM O nome do método (protoPayload.methodName) é um dos seguintes: google.iam.admin.v1.SignBlob google.iam.admin.v1.SignJwt API Service Account Credentials O nome do método é um dos seguintes: SignBlob SignJwt
Tipo de solicitação	API IAM O tipo de solicitação (protoPayload.request.@type) é um dos seguintes: type.googleapis.com/google.iam.admin.v1.SignBlobRequest type.googleapis.com/google.iam.admin.v1.SignJwtRequest API Service Account Credentials O tipo de solicitação é um dos seguintes: type.googleapis.com/google.iam.credentials.v1.SignBlobRequest type.googleapis.com/google.iam.credentials.v1.SignJwtRequest
Nome do serviço	API IAM O nome do serviço (protoPayload.serviceName) é iam.googleapis.com. API Service Account Credentials O nome do serviço é iamcredentials.googleapis.com.

Os registros de auditoria de acesso a dados são contabilizados na cota mensal gratuita de ingestão de dados de registro. Se você exceder essa cota, será cobrado pela ingestão de registros. Para detalhes, consulte Preços do Google Cloud Observability.

Como migrar código para assinar JWTs

Veja nesta seção como migrar o código que assina os JWTs para a API Service Account Credentials.

Como assinar JWTs com a API REST

A tabela a seguir mostra as diferenças entre assinar um JWT com a API REST do IAM e assinar um JWT com a API Service Account Credentials. Atualize seu código para refletir essas diferenças:

Diferenças de assinatura de um JWT
Endpoints HTTP	API IAM A API IAM usa os seguintes endpoints e métodos HTTP: POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signJwt Nesse URL, project-id é o ID do projeto, e sa-email é o endereço de e-mail da conta de serviço. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt Nesse URL, o caractere curinga - substitui o ID do projeto, e sa-email é o endereço de e-mail da conta de serviço. API Service Account Credentials Use o endpoint e o método HTTP a seguir. Não substitua o caractere curinga pelo ID do projeto: POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt Nesse URL, sa-email é o endereço de e-mail da conta de serviço.
Corpo da solicitação	API IAM O corpo da solicitação inclui um campo payload. O valor é o payload do JWT a ser assinado. O payload precisa ser um objeto JSON, serializado como uma string, que contém um conjunto de declarações JWT. Se você fornecer uma declaração de prazo de validade (exp), ela não poderá ser posterior a 2 horas no futuro. Se você omitir a declaração exp, ela será adicionada automaticamente e definida como 1 hora no futuro. API Service Account Credentials O corpo da solicitação inclui um campo payload idêntico à API IAM, exceto pelo comportamento da declaração de prazo de validade (exp): Se você fornecer a declaração exp, ela não poderá ter mais de 12 horas no futuro. Se você omitir a declaração exp, ela não será adicionada automaticamente. Você precisa fornecer essa declaração se usar o JWT assinado para se autenticar com as APIs do Google ou com outra API que exija a declaração exp.
Corpo da resposta	Ambas as APIs usam os mesmos campos no corpo da resposta.

Como assinar JWTs com uma biblioteca de cliente

As bibliotecas de cliente da API Service Account Credentials são separadas das bibliotecas de cliente da API IAM.

Para usar a API Service Account Credentials, adicione a biblioteca de cliente ao aplicativo e atualize o código para usar a nova biblioteca de cliente:

C#

Adicione a biblioteca de cliente de credenciais da conta de serviço para C# ao aplicativo. Use o método SignJwt() para gerar uma assinatura.

O nome da conta de serviço precisa usar o caractere curinga - para representar o ID do projeto:

Válido: nome com caractere curinga

projects/-/serviceAccounts/[e-mail]

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/[e-mail]

Se você não usar mais a biblioteca de cliente do IAM para C#, poderá removê-la do aplicativo.

Go

Adicione a biblioteca de cliente de credenciais da conta de serviço para Go ao aplicativo. Use IamCredentialsClient.SignJwt() function para gerar uma assinatura.

O nome da conta de serviço precisa usar o caractere curinga - para representar o ID do projeto:

Válido: nome com caractere curinga

projects/-/serviceAccounts/[e-mail]

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/[e-mail]

Se você não usar mais a biblioteca de cliente do IAM para Go, poderá removê-la do aplicativo.

Java

Adicione a biblioteca de cliente de credenciais da conta de serviço para Java ao aplicativo. Use o método IamCredentialsClient#signJwt() para gerar uma assinatura.

O nome da conta de serviço precisa usar o caractere curinga - para representar o ID do projeto:

Válido: nome com caractere curinga

projects/-/serviceAccounts/[e-mail]

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/[e-mail]

Se você não usar mais a biblioteca de cliente do IAM para Java, poderá removê-la do aplicativo.

Node.js

Adicione a biblioteca de cliente de credenciais da conta de serviço para Node.js ao aplicativo. Use o método signJwt() para gerar uma assinatura.

O nome da conta de serviço precisa usar o caractere curinga - para representar o ID do projeto:

Válido: nome com caractere curinga

projects/-/serviceAccounts/[e-mail]

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/[e-mail]

Se você não usar mais a biblioteca de cliente do IAM para Node.js, poderá removê-la do aplicativo.

PHP

Adicione a biblioteca de cliente de credenciais da conta de serviço para PHP ao aplicativo. Use o método signJwt() para gerar uma assinatura.

O nome da conta de serviço precisa usar o caractere curinga - para representar o ID do projeto:

Válido: nome com caractere curinga

projects/-/serviceAccounts/[e-mail]

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/[e-mail]

Se você não usar mais a biblioteca de cliente do IAM para PHP, poderá removê-la do aplicativo.

Python

Adicione a biblioteca de cliente de credenciais da conta de serviço para Python ao aplicativo. Use o método sign_jwt() para gerar uma assinatura.

O nome da conta de serviço precisa usar o caractere curinga - para representar o ID do projeto:

Válido: nome com caractere curinga

projects/-/serviceAccounts/[e-mail]

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/[e-mail]

Se você não usar mais a biblioteca de cliente iam_credentials, poderá removê-la do aplicativo.

Ruby

Adicione a biblioteca de cliente de credenciais da conta de serviço para Ruby ao aplicativo. Use o método sign_service_account_jwt() para gerar uma assinatura.

O nome da conta de serviço precisa usar o caractere curinga - para representar o ID do projeto:

Válido: nome com caractere curinga

projects/-/serviceAccounts/[e-mail]

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/[e-mail]

Se você não usar mais a biblioteca de cliente do IAM para Ruby, poderá removê-la do aplicativo.

Como migrar código para assinar blobs binários

Nesta seção, descrevemos como migrar o código que assina blobs binários para a API Service Account Credentials.

Como assinar blobs binários com a API REST

Veja na tabela a seguir as diferenças entre a assinatura de um blob binário com a API REST do IAM e a assinatura de um blob binário com a API Service Account Credentials. Atualize seu código para refletir essas diferenças:

Diferenças para assinar um blob binário
Endpoints HTTP	API IAM A API IAM usa os seguintes endpoints e métodos HTTP: POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signBlob Nesse URL, project-id é o ID do projeto, e sa-email é o endereço de e-mail da conta de serviço. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob Nesse URL, o caractere curinga - substitui o ID do projeto, e sa-email é o endereço de e-mail da conta de serviço. API Service Account Credentials Use o endpoint e o método HTTP a seguir. Não substitua o caractere curinga pelo ID do projeto: POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob Nesse URL, sa-email é o endereço de e-mail da conta de serviço.
Corpo da solicitação	API IAM O corpo da solicitação inclui um campo bytesToSign. Seu valor é uma string codificada em base64 que representa o blob binário a ser assinado. API Service Account Credentials O corpo da solicitação inclui um campo payload que tem o mesmo valor que o campo bytesToSign na API IAM.
Corpo da resposta	API IAM O corpo da resposta contém um campo keyId, que identifica a chave usada para assinar o blob, e um campo signature, que contém uma string codificada em base64 que representa a assinatura. API Service Account Credentials O corpo da resposta contém um campo keyId idêntico ao campo keyId na API IAM, bem como um campo signedBlob idêntico ao campo signature na API IAM. Observação: o campo signedBlob contém apenas a assinatura, não o blob original.

Como assinar blobs binários com uma biblioteca de cliente

As bibliotecas de cliente da API Service Account Credentials são separadas das bibliotecas de cliente da API IAM.

Para usar a API Service Account Credentials, adicione a biblioteca de cliente ao aplicativo e atualize o código para usar a nova biblioteca de cliente:

C++

Se você usar a biblioteca de cliente em C++ do Cloud Storage para assinar blobs diretamente ou como uma dependência de outra biblioteca de cliente:

Faça upgrade para a versão 0.9.0 ou posterior de google-cloud-cpp.

Se você usar outra biblioteca de cliente para assinar blobs:

Entre em contato com [e-mail] para suporte.

C#

Se você usar a biblioteca de cliente do IAM para C# diretamente ou como uma dependência de outra biblioteca de cliente:

Adicione a biblioteca de cliente de credenciais da conta de serviço para C# ao aplicativo. Use o método SignBlob() para gerar uma assinatura.

O nome da conta de serviço precisa usar o caractere curinga - para representar o ID do projeto:

Válido: nome com caractere curinga

projects/-/serviceAccounts/[e-mail]

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/[e-mail]

Se você não usar mais a biblioteca de cliente do IAM para C#, poderá removê-la do aplicativo.

Se você usa o SDK Admin DotNet do Firebase ou diretamente como uma dependência de outra biblioteca de cliente:

Faça upgrade para a versão 1.17.1 ou posterior de firebase-admin-dotnet.

Se você usar outra biblioteca de cliente para assinar blobs:

Entre em contato com [e-mail] para suporte.

Go

Se você usar a biblioteca de cliente do IAM para Go diretamente ou como uma dependência de outra biblioteca de cliente:

Adicione a biblioteca de cliente de credenciais da conta de serviço para Go ao aplicativo. Use IamCredentialsClient.SignBlob() function para gerar uma assinatura.

O nome da conta de serviço precisa usar o caractere curinga - para representar o ID do projeto:

Válido: nome com caractere curinga

projects/-/serviceAccounts/[e-mail]

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/[e-mail]

Se você não usar mais a biblioteca de cliente do IAM para Go, poderá removê-la do aplicativo.

Se você usa o SDK Admin Go do Firebase ou diretamente como uma dependência de outra biblioteca de cliente:

Faça upgrade para a versão 4.1.0 ou posterior de firebase-admin-go.

Se você usar outra biblioteca de cliente para assinar blobs:

Entre em contato com [e-mail] para suporte.

Java

Se você usar a biblioteca de cliente do IAM para Java diretamente ou como uma dependência de outra biblioteca de cliente:

Adicione a biblioteca de cliente de credenciais da conta de serviço para Java ao aplicativo. Use o método IamCredentialsClient#signBlob() para gerar uma assinatura.

O nome da conta de serviço precisa usar o caractere curinga - para representar o ID do projeto:

Válido: nome com caractere curinga

projects/-/serviceAccounts/[e-mail]

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/[e-mail]

Se você não usar mais a biblioteca de cliente do IAM para Java, poderá removê-la do aplicativo.

Se você usar a biblioteca do Google Auth para Java diretamente ou como uma dependência de outra biblioteca de cliente:

Faça upgrade para a versão 0.14.0 ou posterior de google-auth-library-java.

Se você usa o SDK Admin Java do Firebase ou diretamente como uma dependência de outra biblioteca de cliente:

Faça upgrade para a versão 7.0.1 ou posterior de firebase-admin-java.

Se você usar outra biblioteca de cliente para assinar blobs:

Entre em contato com [e-mail] para suporte.

Node.js

Se você usar a biblioteca de cliente do IAM para Node.js diretamente ou como uma dependência de outra biblioteca de cliente:

Adicione a biblioteca de cliente de credenciais da conta de serviço para Node.js ao aplicativo. Use o método signBlob() para gerar uma assinatura.

O nome da conta de serviço precisa usar o caractere curinga - para representar o ID do projeto:

Válido: nome com caractere curinga

projects/-/serviceAccounts/[e-mail]

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/[e-mail]

Se você não usar mais a biblioteca de cliente do IAM para Node.js, poderá removê-la do aplicativo.

Se você usar a biblioteca do Google Auth para Node.js diretamente ou como uma dependência de outra biblioteca de cliente:

Faça upgrade para a versão 6.0.0 ou posterior de google-auth-library-nodejs.

Se você usar o SDK Admin para Node.js do Firebase diretamente ou como uma dependência de outra biblioteca de cliente:

Faça upgrade para a versão 8.13.0 ou posterior de firebase-admin-node.

Se você usar outra biblioteca de cliente para assinar blobs:

Entre em contato com [e-mail] para suporte.

PHP

Se você usar a biblioteca de cliente do IAM para PHP diretamente ou como uma dependência de outra biblioteca de cliente:

Adicione a biblioteca de cliente de credenciais da conta de serviço para PHP ao aplicativo. Use o método signBlob() para gerar uma assinatura.

O nome da conta de serviço precisa usar o caractere curinga - para representar o ID do projeto:

Válido: nome com caractere curinga

projects/-/serviceAccounts/[e-mail]

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/[e-mail]

Se você não usar mais a biblioteca de cliente do IAM para PHP, poderá removê-la do aplicativo.

Se você usar a biblioteca do Google Auth para PHP diretamente ou como uma dependência de outra biblioteca de cliente:

Faça upgrade para a versão 1.5.0 ou posterior de google-auth-library-php.

Se você usar outra biblioteca de cliente para assinar blobs:

Entre em contato com [e-mail] para suporte.

Python

Se você usar a biblioteca de cliente do IAM para Python diretamente ou como uma dependência de outra biblioteca de cliente:

Adicione a biblioteca de cliente de credenciais da conta de serviço para Python ao aplicativo. Use o método sign_blob() para gerar uma assinatura.

O nome da conta de serviço precisa usar o caractere curinga - para representar o ID do projeto:

Válido: nome com caractere curinga

projects/-/serviceAccounts/[e-mail]

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/[e-mail]

Se você não usar mais a biblioteca de cliente iam_credentials, poderá removê-la do aplicativo.

Se você usar a biblioteca do Google Auth para Python diretamente ou como uma dependência de outra biblioteca de cliente:

Faça upgrade para a versão 1.21.2 ou posterior de google-auth-library-python.

Se você usar o cliente Python para Cloud Storage diretamente ou como uma dependência de outra biblioteca de cliente:

Faça upgrade para a versão 1.30.0 ou posterior de python-storage.

Se você usar outra biblioteca de cliente para assinar blobs:

Entre em contato com [e-mail] para suporte.

Ruby

Se você usar a biblioteca de cliente do IAM para Ruby diretamente ou como uma dependência de outra biblioteca de cliente:

Adicione a biblioteca de cliente de credenciais da conta de serviço para Ruby ao aplicativo. Use o método sign_service_account_blob() para gerar uma assinatura.

O nome da conta de serviço precisa usar o caractere curinga - para representar o ID do projeto:

Válido: nome com caractere curinga

projects/-/serviceAccounts/[e-mail]

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/[e-mail]

Se você não usar mais a biblioteca de cliente do IAM para Ruby, poderá removê-la do aplicativo.

Se você usar outra biblioteca de cliente para assinar blobs:

Entre em contato com [e-mail] para suporte.

Como migrar o código que usa a ferramenta gcloud

A CLI do Google Cloud fornece comandos que usam a API IAM para assinar JWTs e blobs binários, incluindo:

• gcloud beta iam service-accounts sign-jwt
• gcloud iam service-accounts sign-blob

A partir de 1º de julho de 2021, atualizaremos esses comandos para usar a API Service Account Credentials. Essa alteração não afetará os comandos para assinar blobs.

Se você usar a CLI gcloud para assinar JWTs, siga estas etapas antes de 1º de julho de 2021:

1. Verifique se você incluiu a declaração de prazo de validade (exp) no conjunto de declarações JWT.

   Caso você já inclua essa reivindicação, não será necessário fazer alterações. É possível pular as etapas restantes.

   Se você não incluir essa reivindicação, prossiga para a próxima etapa.

2. Verifique se você usa o JWT assinado para se autenticar com as APIs do Google ou com outra API que exija a declaração exp.

   Se você omitir essa declaração, a API IAM a definirá automaticamente como 1 hora no futuro. Por outro lado, a API Service Account Credentials não define esse campo automaticamente.

   Se você tiver certeza de que não precisa da declaração exp, não precisará fazer alterações. É possível pular as etapas restantes.

   Se você sabe que precisa da reivindicação exp ou não tem certeza, prossiga para a próxima etapa.

3. Atualize seu código para criar JWTs e possibilitar que ele adicione a declaração exp ao conjunto de declarações JWT.

   É possível definir a declaração exp em até 1 hora.

Como verificar cotas

A cota da API Service Account Credentials é separada da cota para a API IAM. Se você recebeu um aumento de cota para assinar JWTs e blobs com a API IAM, talvez seja necessário solicitar um aumento para a API Service Account Credentials.

Observação: a maioria dos clientes do Google Cloud usa a cota padrão para assinar JWTs e blobs. Se você usar a cota padrão, não precisará ler esta seção.

Para visualizar sua cota e o uso real das duas APIs e solicitar um aumento na cota, se necessário, faça o seguinte:

1. No console do Google Cloud, acesse a página Cotas.

   Acessar a página "Cotas"

2. Selecione um projeto. É possível clicar em um projeto recente ou em Selecionar projeto para pesquisar todos os projetos.

3. Na caixa de texto Filtrar tabela acima da tabela, insira Sign requests per minute e selecione o valor exibido.

4. Na caixa de texto Filtrar tabela, selecione OU na lista suspensa.

5. Na caixa de texto Filtrar tabela, digite Generate credentials e selecione o valor que aparece.

   O console do Google Cloud mostra seu uso atual para assinar JWTs e blobs no último minuto. Ele também mostra seu pico de uso por minuto nos últimos sete dias e sua cota atual, exibida na coluna Limite.

6. Compare as cotas de cada linha na tabela e verifique se a cota da API Service Account Credentials é maior do que o pico de uso da API IAM em sete dias.

7. Opcional: se a cota da API Service Account Credentials for muito baixa, marque a caixa de seleção da API Service Account Credentials e clique em Editar cotas. Preencha o formulário para solicitar um aumento de cota.

8. Repita essas etapas para cada projeto em que você usa a API IAM para assinar JWTs e blobs.

A seguir

• Descubra como criar um JWT assinado ou criar um blob binário assinado com a API REST de credenciais da conta de serviço.
• Veja detalhes sobre a API REST para a API Service Account Credentials.
• Entenda cotas e limites do IAM.