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. É necessário migrar para a API Service Account Credentials antes de 1º de julho de 2021. Além disso, se você usar a ferramenta de linha de comando gcloud para assinar JWTs, talvez seja necessário adicionar uma nova declaração ao conjunto de declarações do JWT.

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 Account Credentials impede que você faça a autenticação com um token autoassinado e receba outro token autoassinado. Como resultado, se um invasor receber um token assinado, ele não poderá usá-lo para atualizar o token.

Nesta página, explicamos como atualizar seu código para usar a API Service Account Credentials. Se tiver comentários sobre essa alteração, preencha o formulário de feedback ou envie um feedback detalhado para iam-sign-deprecation-public@google.com.

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 pacote de operações do Google Cloud.

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 1 hora 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/my-service-account@my-project.iam.gserviceaccount.com

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Se o payload da solicitação contiver uma declaração de prazo de validade (exp), ela não poderá ter mais de 12 horas no futuro. Se você omitir essa declaração, ela não será adicionada automaticamente. Forneça essa declaração se você usar o JWT assinado para se autenticar com as APIs do Google ou com outra API que exija a declaração exp.

Se você não usar mais a biblioteca de cliente do IAM para C#, será possível 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/my-service-account@my-project.iam.gserviceaccount.com

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Se o payload da solicitação contiver uma declaração de prazo de validade (exp), ela não poderá ter mais de 12 horas no futuro. Se você omitir essa declaração, ela não será adicionada automaticamente. Forneça essa declaração se você usar o JWT assinado para se autenticar com as APIs do Google ou com outra API que exija a declaração exp.

Se você não usar mais a biblioteca de cliente do IAM para Go, será possível 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/my-service-account@my-project.iam.gserviceaccount.com

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Se o payload da solicitação contiver uma declaração de prazo de validade (exp), ela não poderá ter mais de 12 horas no futuro. Se você omitir essa declaração, ela não será adicionada automaticamente. Forneça essa declaração se você usar o JWT assinado para se autenticar com as APIs do Google ou com outra API que exija a declaração exp.

Se você não usar mais a biblioteca de cliente do IAM para Java, será possível 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/my-service-account@my-project.iam.gserviceaccount.com

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Se o payload da solicitação contiver uma declaração de prazo de validade (exp), ela não poderá ter mais de 12 horas no futuro. Se você omitir essa declaração, ela não será adicionada automaticamente. Forneça essa declaração se você usar o JWT assinado para se autenticar com as APIs do Google ou com outra API que exija a declaração exp.

Se você não usar mais a biblioteca de cliente do IAM para Node.js, será possível 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/my-service-account@my-project.iam.gserviceaccount.com

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Se o payload da solicitação contiver uma declaração de prazo de validade (exp), ela não poderá ter mais de 12 horas no futuro. Se você omitir essa declaração, ela não será adicionada automaticamente. Forneça essa declaração se você usar o JWT assinado para se autenticar com as APIs do Google ou com outra API que exija a declaração exp.

Se você não usar mais a biblioteca de cliente do IAM para PHP, será possível 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/my-service-account@my-project.iam.gserviceaccount.com

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Se o payload da solicitação contiver uma declaração de prazo de validade (exp), ela não poderá ter mais de 12 horas no futuro. Se você omitir essa declaração, ela não será adicionada automaticamente. Forneça essa declaração se você usar o JWT assinado para se autenticar com as APIs do Google ou com outra API que exija a declaração exp.

Se você não usar mais a biblioteca de cliente do IAM para Python, será possível 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/my-service-account@my-project.iam.gserviceaccount.com

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Se o payload da solicitação contiver uma declaração de prazo de validade (exp), ela não poderá ter mais de 12 horas no futuro. Se você omitir essa declaração, ela não será adicionada automaticamente. Forneça essa declaração se você usar o JWT assinado para se autenticar com as APIs do Google ou com outra API que exija a declaração exp.

Se você não usar mais a biblioteca de cliente do IAM para Ruby, será possível 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.

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#

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/my-service-account@my-project.iam.gserviceaccount.com

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

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

Go

Adicione a biblioteca de cliente de credenciais da conta de serviço para Go ao aplicativo. Use o método 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/my-service-account@my-project.iam.gserviceaccount.com

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Se você não usar mais a biblioteca de cliente do IAM para Go, será possível 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#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/my-service-account@my-project.iam.gserviceaccount.com

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Se você não usar mais a biblioteca de cliente do IAM para Java, será possível 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 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/my-service-account@my-project.iam.gserviceaccount.com

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Se você não usar mais a biblioteca de cliente do IAM para Node.js, será possível 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 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/my-service-account@my-project.iam.gserviceaccount.com

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Se você não usar mais a biblioteca de cliente do IAM para PHP, será possível 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_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/my-service-account@my-project.iam.gserviceaccount.com

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Se você não usar mais a biblioteca de cliente do IAM para Python, será possível 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_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/my-service-account@my-project.iam.gserviceaccount.com

Inválido: nome com o ID do projeto

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

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

Como migrar o código que usa a ferramenta gcloud

A ferramenta de linha de comando gcloud fornece comandos que usam a API IAM para assinar JWTs e blobs binários, incluindo:

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 ferramenta 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.

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 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 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