Migrar para a API de credenciais da conta de serviço

A API Service Account Credentials cria credenciais de curta duração para contas de serviço de gestão de identidade e de acesso (IAM). Também pode usar esta API para assinar símbolos da Web JSON (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. A partir de 1 de julho de 2020, estes métodos foram descontinuados na API REST e em todas as bibliotecas cliente da API IAM. Além disso, se usar a CLI do Google Cloud para assinar JWTs, pode ter de adicionar uma nova reivindicação ao conjunto de reivindicações JWT. Ainda pode usar os métodos descontinuados, mas estes não suportam funcionalidades avançadas, como o processamento em lote de pedidos HTTP. Em alternativa, recomendamos que 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 Account Credentials adiciona vários novos métodos de API para gerar tokens de roubo de identidade.

Esta página explica como atualizar o código existente para usar a API de credenciais da conta de serviço. Se tiver feedback sobre esta alteração, pode preencher o formulário de feedback. Também pode usar o endereço de email [e-mail] para pedir apoio técnico e enviar feedback detalhado.

Antes de começar

• Enable the Service Account Credentials API.

  Roles required to enable APIs

  To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

  Enable the API

Ativar registos de auditoria

Se quiser receber registos de auditoria para pedidos de assinatura de JWTs e blobs, tem de ativar os registos de auditoria de acesso a dados para a API IAM. A ativação dos registos de auditoria de acesso a dados para a API IAM também ativa estes registos de auditoria para a API Credentials da conta de serviço.

Existem algumas diferenças notáveis entre as entradas de registo que cada API gera:

Diferenças para entradas de registo 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 das credenciais da conta de serviço O nome do método é um dos seguintes: SignBlob SignJwt
Tipo de pedido	API IAM O tipo de pedido (protoPayload.request.@type) é um dos seguintes: type.googleapis.com/google.iam.admin.v1.SignBlobRequest type.googleapis.com/google.iam.admin.v1.SignJwtRequest API das credenciais da conta de serviço O tipo de pedido é 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 das credenciais da conta de serviço O nome do serviço é iamcredentials.googleapis.com.

Os registos de auditoria de acesso a dados são contabilizados na sua atribuição mensal gratuita de carregamento de dados de registo. Se exceder esta atribuição, a ingestão de registos é-lhe cobrada. Para ver detalhes, consulte os preços do Google Cloud Observability.

Migrar código para assinar JWTs

Esta secção descreve como migrar o código que assina JWTs para a API de credenciais de conta de serviço.

Assinar JWTs com a API REST

A tabela seguinte mostra as diferenças entre assinar um JWT com a API REST IAM e assinar um JWT com a API Service Account Credentials. Atualize o código para refletir estas diferenças:

Diferenças na assinatura de um JWT
Pontos finais HTTP	API IAM A API IAM usa os seguintes métodos e pontos finais HTTP: POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signJwt Neste URL, project-id é o ID do projeto e sa-email é o endereço de email da conta de serviço. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt Neste URL, o caráter universal - substitui o ID do projeto e sa-email é o endereço de email da conta de serviço. API das credenciais da conta de serviço Use o seguinte método HTTP e ponto final. Não substitua o caráter universal pelo ID do projeto: POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt Neste URL, sa-email é o endereço de email da conta de serviço.
Corpo do pedido	API IAM O corpo do pedido inclui um campo payload. O seu valor é a carga útil do JWT a assinar. O payload tem de ser um objeto JSON, serializado como uma string, que contenha um conjunto de afirmações JWT. Se fornecer uma reivindicação de tempo de expiração (exp), esta não pode ser superior a 12 horas no futuro. Se omitir a reivindicação exp, esta é adicionada automaticamente e é definida para 1 hora no futuro. API das credenciais da conta de serviço O corpo do pedido inclui um campo payload idêntico ao da API IAM, exceto no que diz respeito ao comportamento da reivindicação de data/hora de validade (exp): Se fornecer a reivindicação exp, esta não pode ser superior a 12 horas no futuro. Se omitir a reivindicação exp, não é adicionada automaticamente. Tem de fornecer esta reivindicação se usar o JWT assinado para autenticar com as APIs Google, ou com outra API que exija a reivindicação exp.
Corpo da resposta	Ambas as APIs usam os mesmos campos no corpo da resposta.

Assinar JWTs com uma biblioteca de cliente

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

Para usar a API Service Account Credentials, adicione a respetiva biblioteca cliente à sua aplicação e atualize o código para usar a nova biblioteca cliente:

C#

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

O nome da conta de serviço tem de usar o caráter universal - para representar o ID do projeto:

Válido: nome com caráter universal

projects/-/serviceAccounts/[e-mail]

Inválido: nome com ID do projeto

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

Se já não usar a biblioteca de cliente da IAM para C#, pode removê-la da sua aplicação.

Go

Adicione a biblioteca de cliente de credenciais da conta de serviço para Go à sua aplicação. Use o IamCredentialsClient.SignJwt() function para gerar uma assinatura.

O nome da conta de serviço tem de usar o caráter universal - para representar o ID do projeto:

Válido: nome com caráter universal

projects/-/serviceAccounts/[e-mail]

Inválido: nome com ID do projeto

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

Se já não usar a biblioteca de cliente da IAM para Go, pode removê-la da sua aplicação.

Java

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

O nome da conta de serviço tem de usar o caráter universal - para representar o ID do projeto:

Válido: nome com caráter universal

projects/-/serviceAccounts/[e-mail]

Inválido: nome com ID do projeto

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

Se já não usar a biblioteca cliente da IAM para Java, pode removê-la da sua aplicação.

Node.js

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

O nome da conta de serviço tem de usar o caráter universal - para representar o ID do projeto:

Válido: nome com caráter universal

projects/-/serviceAccounts/[e-mail]

Inválido: nome com ID do projeto

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

Se já não usar a biblioteca de cliente da IAM para Node.js, pode removê-la da sua aplicação.

PHP

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

O nome da conta de serviço tem de usar o caráter universal - para representar o ID do projeto:

Válido: nome com caráter universal

projects/-/serviceAccounts/[e-mail]

Inválido: nome com ID do projeto

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

Se já não usar a biblioteca cliente da IAM para PHP, pode removê-la da sua aplicação.

Python

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

O nome da conta de serviço tem de usar o caráter universal - para representar o ID do projeto:

Válido: nome com caráter universal

projects/-/serviceAccounts/[e-mail]

Inválido: nome com ID do projeto

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

Se já não usar a iam_credentials biblioteca de cliente, pode removê-la da sua aplicação.

Ruby

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

O nome da conta de serviço tem de usar o caráter universal - para representar o ID do projeto:

Válido: nome com caráter universal

projects/-/serviceAccounts/[e-mail]

Inválido: nome com ID do projeto

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

Se já não usar a biblioteca de cliente da IAM para Ruby, pode removê-la da sua aplicação.

Migrar código para assinar blobs binários

Esta secção descreve como migrar o código que assina blobs binários para a API Service Account Credentials.

Assinar blobs binários com a API REST

A tabela seguinte mostra as diferenças entre assinar um blob binário com a API REST IAM e assinar um blob binário com a API Service Account Credentials. Atualize o código para refletir estas diferenças:

Diferenças na assinatura de um blob binário
Pontos finais HTTP	API IAM A API IAM usa os seguintes métodos e pontos finais HTTP: POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signBlob Neste URL, project-id é o ID do projeto e sa-email é o endereço de email da conta de serviço. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob Neste URL, o caráter universal - substitui o ID do projeto e sa-email é o endereço de email da conta de serviço. API das credenciais da conta de serviço Use o seguinte método HTTP e ponto final. Não substitua o caráter universal pelo ID do projeto: POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob Neste URL, sa-email é o endereço de email da conta de serviço.
Corpo do pedido	API IAM O corpo do pedido inclui um campo bytesToSign. O respetivo valor é uma string codificada em base64 que representa o blob binário a assinar. API das credenciais da conta de serviço O corpo do pedido inclui um campo payload com 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 que foi usada para assinar o blob, e um campo signature, que contém uma string com codificação base64 que representa a assinatura. API das credenciais da conta de serviço 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. Nota: o campo signedBlob contém apenas a assinatura e não o blob original.

Assinar blobs binários com uma biblioteca de cliente

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

Para usar a API Service Account Credentials, adicione a respetiva biblioteca cliente à sua aplicação e atualize o código para usar a nova biblioteca cliente:

C++

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

Atualize para a versão 0.9.0 ou posterior do google-cloud-cpp.

Se usar outra biblioteca de cliente para assinar blobs:

Contacte o [e-mail] para receber apoio técnico.

C#

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

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

O nome da conta de serviço tem de usar o caráter universal - para representar o ID do projeto:

Válido: nome com caráter universal

projects/-/serviceAccounts/[e-mail]

Inválido: nome com ID do projeto

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

Se já não usar a biblioteca de cliente da IAM para C#, pode removê-la da sua aplicação.

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

Atualize para a versão 1.17.1 ou posterior do firebase-admin-dotnet.

Se usar outra biblioteca de cliente para assinar blobs:

Contacte o [e-mail] para receber apoio técnico.

Go

Se usar a biblioteca de cliente da 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 à sua aplicação. Use o IamCredentialsClient.SignBlob() function para gerar uma assinatura.

O nome da conta de serviço tem de usar o caráter universal - para representar o ID do projeto:

Válido: nome com caráter universal

projects/-/serviceAccounts/[e-mail]

Inválido: nome com ID do projeto

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

Se já não usar a biblioteca de cliente da IAM para Go, pode removê-la da sua aplicação.

Se usar o SDK Firebase Admin Go,diretamente ou como uma dependência de outra biblioteca cliente:

Atualize para a versão 4.1.0 ou posterior do firebase-admin-go.

Se usar outra biblioteca de cliente para assinar blobs:

Contacte o [e-mail] para receber apoio técnico.

Java

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

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

O nome da conta de serviço tem de usar o caráter universal - para representar o ID do projeto:

Válido: nome com caráter universal

projects/-/serviceAccounts/[e-mail]

Inválido: nome com ID do projeto

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

Se já não usar a biblioteca cliente da IAM para Java, pode removê-la da sua aplicação.

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

Atualize para a versão 0.14.0 ou posterior do google-auth-library-java.

Se usar o SDK Java do administrador do Firebase,diretamente ou como uma dependência de outra biblioteca cliente:

Atualize para a versão 7.0.1 ou posterior do firebase-admin-java.

Se usar outra biblioteca de cliente para assinar blobs:

Contacte o [e-mail] para receber apoio técnico.

Node.js

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

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

O nome da conta de serviço tem de usar o caráter universal - para representar o ID do projeto:

Válido: nome com caráter universal

projects/-/serviceAccounts/[e-mail]

Inválido: nome com ID do projeto

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

Se já não usar a biblioteca de cliente da IAM para Node.js, pode removê-la da sua aplicação.

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

Atualize para a versão 6.0.0 ou posterior do google-auth-library-nodejs.

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

Atualize para a versão 8.13.0 ou posterior do firebase-admin-node.

Se usar outra biblioteca de cliente para assinar blobs:

Contacte o [e-mail] para receber apoio técnico.

PHP

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

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

O nome da conta de serviço tem de usar o caráter universal - para representar o ID do projeto:

Válido: nome com caráter universal

projects/-/serviceAccounts/[e-mail]

Inválido: nome com ID do projeto

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

Se já não usar a biblioteca cliente da IAM para PHP, pode removê-la da sua aplicação.

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

Atualize para a versão 1.5.0 ou posterior do google-auth-library-php.

Se usar outra biblioteca de cliente para assinar blobs:

Contacte o [e-mail] para receber apoio técnico.

Python

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

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

O nome da conta de serviço tem de usar o caráter universal - para representar o ID do projeto:

Válido: nome com caráter universal

projects/-/serviceAccounts/[e-mail]

Inválido: nome com ID do projeto

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

Se já não usar a iam_credentials biblioteca de cliente, pode removê-la da sua aplicação.

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

Atualize para a versão 1.21.2 ou posterior do google-auth-library-python.

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

Atualize para a versão 1.30.0 ou posterior do python-storage.

Se usar outra biblioteca de cliente para assinar blobs:

Contacte o [e-mail] para receber apoio técnico.

Ruby

Se 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 à sua aplicação. Use o método sign_service_account_blob() para gerar uma assinatura.

O nome da conta de serviço tem de usar o caráter universal - para representar o ID do projeto:

Válido: nome com caráter universal

projects/-/serviceAccounts/[e-mail]

Inválido: nome com ID do projeto

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

Se já não usar a biblioteca de cliente da IAM para Ruby, pode removê-la da sua aplicação.

Se usar outra biblioteca de cliente para assinar blobs:

Contacte o [e-mail] para receber apoio técnico.

Migrar código que usa a CLI gcloud

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

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

A 1 de julho de 2021 ou após essa data, vamos atualizar estes comandos para usar a API Service Account Credentials. Esta alteração não afeta os comandos para assinar blobs.

Se usar a CLI gcloud para assinar JWTs, tem de seguir estes passos antes de 1 de julho de 2021:

1. Verifique se inclui a reivindicação de tempo de validade (exp) no conjunto de reivindicações JWT.

   Se já incluir esta reivindicação, não tem de fazer nenhuma alteração. Pode ignorar os restantes passos.

   Se não incluir esta reivindicação, avance para o passo seguinte.

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

   Se omitir esta reivindicação, a API IAM define-a automaticamente para 1 hora no futuro. Por outro lado, a API Service Account Credentials não define este campo automaticamente.

   Se tiver a certeza de que não precisa da reivindicação exp, não tem de fazer alterações. Pode ignorar os restantes passos.

   Se souber que precisa da reivindicação exp ou não tiver a certeza, continue para o passo seguinte.

3. Atualize o código para criar JWTs de modo que adicione a reivindicação exp ao conjunto de reivindicações do JWT.

   Pode definir a reivindicação exp até 1 hora no futuro.

Verificar quotas

A quota da API Service Account Credentials é separada da quota da API IAM. Se recebeu um aumento da quota para assinar JWTs e blobs com a API IAM, também pode ter de pedir um aumento para a API Service Account Credentials.

Nota: a maioria Google Cloud dos clientes usa a quota predefinida para assinar JWTs e blobs. Se usar a quota predefinida, não precisa de ler esta secção.

Para ver a sua quota e utilização real para ambas as APIs e pedir um aumento da quota, se necessário, faça o seguinte:

1. Na Google Cloud consola, aceda à página Quotas.

   Aceda à página Quotas

2. Selecione um projeto. Pode clicar num projeto recente ou em Selecionar projeto para pesquisar todos os seus projetos.

3. Na caixa de texto Filtrar tabela acima da tabela, introduza Sign requests per minute e, de seguida, selecione o valor apresentado.

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

5. Na caixa de texto Tabela de filtros, introduza Generate credentials e, de seguida, selecione o valor apresentado.

   A Google Cloud consola mostra a sua utilização atual para assinar JWTs e blobs no último minuto; a sua utilização máxima por minuto nos últimos 7 dias; e a sua quota atual, que aparece na coluna Limite.

6. Compare as quotas de cada linha na tabela e certifique-se de que a quota da API Service Account Credentials é superior ao pico de utilização de 7 dias da API IAM.

7. Opcional: se a sua quota para a API Service Account Credentials for demasiado baixa, selecione a caixa de verificação da API Service Account Credentials e, de seguida, clique em Editar quotas. Preencha o formulário para pedir um aumento da quota.

8. Repita estes passos para cada projeto onde usa a API IAM para assinar JWTs e blobs.

O que se segue?

• Saiba como criar um JWT assinado ou criar um blob binário assinado com a API REST de credenciais da conta de serviço.
• Obtenha detalhes sobre a API REST para a API Service Account Credentials.
• Compreenda as quotas e os limites da IAM.