Migrar a la API de credenciales de la cuenta de servicio

La API de credenciales de la cuenta de servicio crea credenciales de corta duración para las cuentas de servicio de la administración de identidades y accesos (IAM). También puedes usar esta API para firmar tokens web JSON (JWT), así como BLOB de datos binarios que contienen otros tipos de tokens.

La API de IAM también contiene métodos para firmar JWT y BLOB binarios. A partir del 1 de julio de 2020, estos métodos dejarán de estar disponibles en la API de REST y en todas las bibliotecas cliente de la API de IAM. Además, si usas la CLI de Google Cloud para firmar JWT, es posible que debas agregar una nueva reclamación al conjunto de reclamaciones de JWT. Aún puedes usar los métodos obsoletos, pero no son compatibles con funciones avanzadas como el agrupamiento de solicitudes HTTP. Te recomendamos migrar a la API de credenciales de la cuenta de servicio en su lugar.

En comparación con la API de IAM, la API de credenciales de la cuenta de servicio proporciona más flexibilidad para la hora de vencimiento de los JWT firmados. Además, la API de Service Account Credentials agrega varios métodos de API nuevos para generar tokens de robo de identidad.

En esta página, se explica cómo actualizar tu código existente para usar la API de credenciales de la cuenta de servicio. Si tienes comentarios sobre este cambio, puedes completar el formulario de comentarios. También puedes usar la dirección de correo electrónico [e-mail] para solicitar asistencia y proporcionar comentarios detallados.

Antes de comenzar

• Enable the Service Account Credentials API.

  Enable the API

Habilita registros de auditoría

Si deseas recibir registros de auditoría para solicitudes de firma de JWT y BLOB, debes habilitar los registros de auditoría de acceso a los datos para la API de IAM. La habilitación de los registros de auditoría de acceso a los datos para la API de IAM también habilita estos registros de auditoría para la API de credenciales de la cuenta de servicio.

Existen algunas diferencias notables entre las entradas de registro que genera cada API:

Diferencias de las entradas del registro de auditoría
Nombre del método	API de IAM El nombre del método (protoPayload.methodName) es uno de los siguientes: google.iam.admin.v1.SignBlob google.iam.admin.v1.SignJwt API de credenciales de la cuenta de servicio El nombre del método es uno de los siguientes: SignBlob SignJwt
Tipo de solicitud	API de IAM El tipo de solicitud (protoPayload.request.@type) es uno de los siguientes: type.googleapis.com/google.iam.admin.v1.SignBlobRequest type.googleapis.com/google.iam.admin.v1.SignJwtRequest API de credenciales de la cuenta de servicio El tipo de solicitud es uno de los siguientes: type.googleapis.com/google.iam.credentials.v1.SignBlobRequest type.googleapis.com/google.iam.credentials.v1.SignJwtRequest
Nombre del servicio	API de IAM El nombre del servicio (protoPayload.serviceName) es iam.googleapis.com. API de credenciales de la cuenta de servicio El nombre del servicio es iamcredentials.googleapis.com.

Los registros de auditoría de acceso a los datos se tienen en cuenta para la asignación mensual gratuita de transferencia de datos de registro. Si excedes esta asignación, se te cobrará por la transferencia de registros. Para obtener más detalles, consulta Precios de Google Cloud Observability.

Migra código para firmar JWT

En esta sección, se describe cómo migrar código que firma JWT a la API de credenciales de la cuenta de servicio.

Firma JWT con la API de REST

En la siguiente tabla, se muestran las diferencias entre firmar un JWT con la API de REST de IAM y firmar un JWT con la API de credenciales de la cuenta de servicio. Actualiza el código para reflejar las siguientes diferencias:

Diferencias para firmar un JWT
Extremos HTTP	API de IAM La API de IAM usa los siguientes métodos y extremos HTTP: POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signJwt En esta URL, project-id es el ID del proyecto y sa-email es la dirección de correo electrónico de la cuenta de servicio. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt En esta URL, el carácter comodín - reemplaza al ID del proyecto y sa-email es la dirección de correo electrónico de la cuenta de servicio. API de credenciales de la cuenta de servicio Usa el siguiente método y extremo HTTP. No reemplaces el carácter comodín por el ID del proyecto: POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt En esta URL, sa-email es la dirección de correo electrónico de la cuenta de servicio.
Cuerpo de la solicitud	API de IAM El cuerpo de la solicitud incluye un campo payload. Su valor es la carga útil de JWT que se firmará. La carga útil debe ser un objeto JSON, serializado como una string, que contiene un conjunto de reclamaciones JWT. Si proporcionas una reclamación de hora de vencimiento (exp), no deben establecerse para más de 12 horas. Si omites la reclamación de exp, se agrega de forma automática y se establece en 1 hora después. API de credenciales de la cuenta de servicio El cuerpo de la solicitud incluye un campo payload idéntico a la API de IAM, excepto por el comportamiento de la reclamación de hora de vencimiento (exp): Si proporcionas la reclamación de exp, no debe establecerse en más de 12 horas después. Si omites la reclamación de exp, no se agregará de forma automática. Debes proporcionar esta reclamación si usas el JWT firmado para autenticarte con las API de Google o con otra API que requiera la reclamación de exp.
Cuerpo de la respuesta	Ambas API usan los mismos campos en el cuerpo de la respuesta.

Firma JWT con una biblioteca cliente

Las bibliotecas cliente de la API de credenciales de la cuenta de servicio son independientes de las bibliotecas cliente de la API de IAM.

Si deseas usar la API de credenciales de la cuenta de servicio, agrega su biblioteca cliente a la aplicación y actualiza el código para usar la biblioteca cliente nueva:

C#

Agrega la biblioteca cliente de credenciales de la cuenta de servicio para C# a la aplicación. Usa el método SignJwt() para generar una firma.

El nombre de la cuenta de servicio debe usar el carácter comodín - para representar el ID del proyecto:

Válido: Nombre con carácter comodín

projects/-/serviceAccounts/[e-mail]

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente de IAM para C#, puedes quitarla de la aplicación.

Go

Agrega la biblioteca cliente de credenciales de la cuenta de servicio para Go a la aplicación. Usa la IamCredentialsClient.SignJwt() function para generar una firma.

El nombre de la cuenta de servicio debe usar el carácter comodín - para representar el ID del proyecto:

Válido: Nombre con carácter comodín

projects/-/serviceAccounts/[e-mail]

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente de IAM para Go, puedes quitarla de la aplicación.

Java

Agrega la biblioteca cliente de credenciales de la cuenta de servicio para Java a la aplicación. Usa el método IamCredentialsClient#signJwt() para generar una firma.

El nombre de la cuenta de servicio debe usar el carácter comodín - para representar el ID del proyecto:

Válido: Nombre con carácter comodín

projects/-/serviceAccounts/[e-mail]

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente de IAM para Java, puedes quitarla de la aplicación.

Node.js

Agrega la biblioteca cliente de credenciales de la cuenta de servicio para Node.js a la aplicación. Usa el método signJwt() para generar una firma.

El nombre de la cuenta de servicio debe usar el carácter comodín - para representar el ID del proyecto:

Válido: Nombre con carácter comodín

projects/-/serviceAccounts/[e-mail]

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente de IAM para Node.js, puedes quitarla de la aplicación.

PHP

Agrega la biblioteca cliente de credenciales de la cuenta de servicio para PHP a la aplicación. Usa el método signJwt() para generar una firma.

El nombre de la cuenta de servicio debe usar el carácter comodín - para representar el ID del proyecto:

Válido: Nombre con carácter comodín

projects/-/serviceAccounts/[e-mail]

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente de IAM para PHP, puedes quitarla de la aplicación.

Python

Agrega la biblioteca cliente de credenciales de la cuenta de servicio para Python a la aplicación. Usa el método sign_jwt() para generar una firma.

El nombre de la cuenta de servicio debe usar el carácter comodín - para representar el ID del proyecto:

Válido: Nombre con carácter comodín

projects/-/serviceAccounts/[e-mail]

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente iam_credentials, puedes quitarla de la aplicación.

Ruby

Agrega la biblioteca cliente de credenciales de la cuenta de servicio para Ruby a la aplicación. Usa el método sign_service_account_jwt() para generar una firma.

El nombre de la cuenta de servicio debe usar el carácter comodín - para representar el ID del proyecto:

Válido: Nombre con carácter comodín

projects/-/serviceAccounts/[e-mail]

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente de IAM para Ruby, puedes quitarla de la aplicación.

Migra código para firmar BLOB binarios

En esta sección, se describe cómo migrar el código que firma los BLOB binarios a la API de credenciales de la cuenta de servicio.

Firma BLOB binarios con la API de REST

En la siguiente tabla, se muestran las diferencias entre firmar un BLOB binario con la API de REST de IAM y firmar un BLOB binario con la API de credenciales de la cuenta de servicio. Actualiza el código para reflejar las siguientes diferencias:

Diferencias para firmar un BLOB binario
Extremos HTTP	API de IAM La API de IAM usa los siguientes métodos y extremos HTTP: POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signBlob En esta URL, project-id es el ID del proyecto y sa-email es la dirección de correo electrónico de la cuenta de servicio. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob En esta URL, el carácter comodín - reemplaza al ID del proyecto y sa-email es la dirección de correo electrónico de la cuenta de servicio. API de credenciales de la cuenta de servicio Usa el siguiente método y extremo HTTP. No reemplaces el carácter comodín por el ID del proyecto: POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob En esta URL, sa-email es la dirección de correo electrónico de la cuenta de servicio.
Cuerpo de la solicitud	API de IAM El cuerpo de la solicitud incluye un campo bytesToSign. Su valor es una string codificada en base64 que representa el BLOB binario que se firmará. API de credenciales de la cuenta de servicio El cuerpo de la solicitud incluye un campo payload que tiene el mismo valor que el campo bytesToSign en la API de IAM.
Cuerpo de la respuesta	API de IAM El cuerpo de la respuesta contiene un campo keyId, que identifica la clave que se usó para firmar el BLOB, y un campo signature, que contiene una string codificada en base64 que representa la firma. API de credenciales de la cuenta de servicio El cuerpo de la respuesta contiene un campo keyId idéntico al campo keyId en la API de IAM, así como un campo signedBlob idéntico al campo signature en la API de IAM. Nota: El campo signedBlob contiene solo la firma, no el BLOB original.

Firma BLOB binarios con una biblioteca cliente

Las bibliotecas cliente de la API de credenciales de la cuenta de servicio son independientes de las bibliotecas cliente de la API de IAM.

Si deseas usar la API de credenciales de la cuenta de servicio, agrega su biblioteca cliente a la aplicación y actualiza el código para usar la biblioteca cliente nueva:

C++

Si usas la biblioteca cliente para C++ de Cloud Storage a fin de firmar BLOB directamente o como una dependencia de otra biblioteca cliente, haz lo siguiente:

Actualiza a la versión 0.9.0 o una versión posterior de google-cloud-cpp.

Si usas otra biblioteca cliente para firmar BLOB, haz lo siguiente:

Comunícate con [e-mail] para obtener asistencia.

C#

Si usas la biblioteca cliente de IAM para C#, directamente o como una dependencia de otra biblioteca cliente, haz lo siguiente:

Agrega la biblioteca cliente de credenciales de la cuenta de servicio para C# a la aplicación. Usa el método SignBlob() para generar una firma.

El nombre de la cuenta de servicio debe usar el carácter comodín - para representar el ID del proyecto:

Válido: Nombre con carácter comodín

projects/-/serviceAccounts/[e-mail]

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente de IAM para C#, puedes quitarla de la aplicación.

Si usas el SDK de Firebase Admin DoNet, directamente o como una dependencia de otra biblioteca cliente:

Actualiza a la versión 1.17.1 o una versión posterior de firebase-admin-dotnet.

Si usas otra biblioteca cliente para firmar BLOB, haz lo siguiente:

Comunícate con [e-mail] para obtener asistencia.

Go

Si usas la biblioteca cliente de IAM para Go, directamente o como una dependencia de otra biblioteca cliente, haz lo siguiente:

Agrega la biblioteca cliente de credenciales de la cuenta de servicio para Go a la aplicación. Usa la IamCredentialsClient.SignBlob() function para generar una firma.

El nombre de la cuenta de servicio debe usar el carácter comodín - para representar el ID del proyecto:

Válido: Nombre con carácter comodín

projects/-/serviceAccounts/[e-mail]

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente de IAM para Go, puedes quitarla de la aplicación.

Si usas el SDK de Firebase Admin Go, directamente o como una dependencia de otra biblioteca cliente:

Actualiza a la versión 4.1.0 o una versión posterior de firebase-admin-go.

Si usas otra biblioteca cliente para firmar BLOB, haz lo siguiente:

Comunícate con [e-mail] para obtener asistencia.

Java

Si usas la biblioteca cliente de IAM para Java, directamente o como una dependencia de otra biblioteca cliente, haz lo siguiente:

Agrega la biblioteca cliente de credenciales de la cuenta de servicio para Java a la aplicación. Usa el método IamCredentialsClient#signBlob() para generar una firma.

El nombre de la cuenta de servicio debe usar el carácter comodín - para representar el ID del proyecto:

Válido: Nombre con carácter comodín

projects/-/serviceAccounts/[e-mail]

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente de IAM para Java, puedes quitarla de la aplicación.

Si usas la biblioteca de Google OAuth para Java, directamente o como una dependencia de otra biblioteca cliente, haz lo siguiente:

Actualiza a la versión 0.14.0 o una versión posterior de google-auth-library-java.

Si usas el SDK de Firebase Admin Java, directamente o como una dependencia de otra biblioteca cliente:

Actualiza a la versión 7.0.1 o una versión posterior de firebase-admin-java.

Si usas otra biblioteca cliente para firmar BLOB, haz lo siguiente:

Comunícate con [e-mail] para obtener asistencia.

Node.js

Si usas la biblioteca cliente de IAM para Node.js, directamente o como una dependencia de otra biblioteca cliente, haz lo siguiente:

Agrega la biblioteca cliente de credenciales de la cuenta de servicio para Node.js a la aplicación. Usa el método signBlob() para generar una firma.

El nombre de la cuenta de servicio debe usar el carácter comodín - para representar el ID del proyecto:

Válido: Nombre con carácter comodín

projects/-/serviceAccounts/[e-mail]

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente de IAM para Node.js, puedes quitarla de la aplicación.

Si usas la biblioteca de Google OAuth para Node.js, directamente o como una dependencia de otra biblioteca cliente, haz lo siguiente:

Actualiza a la versión 6.0.0 o una versión posterior de google-auth-library-nodejs.

Si usas el SDK de administrador de Firebase para Node.js directamente o como una dependencia de otra biblioteca cliente, haz lo siguiente:

Actualiza a la versión 8.13.0 o una versión posterior de firebase-admin-node.

Si usas otra biblioteca cliente para firmar BLOB, haz lo siguiente:

Comunícate con [e-mail] para obtener asistencia.

PHP

Si usas la biblioteca cliente de IAM para PHP directamente o como una dependencia de otra biblioteca cliente, haz lo siguiente:

Agrega la biblioteca cliente de credenciales de la cuenta de servicio para PHP a la aplicación. Usa el método signBlob() para generar una firma.

El nombre de la cuenta de servicio debe usar el carácter comodín - para representar el ID del proyecto:

Válido: Nombre con carácter comodín

projects/-/serviceAccounts/[e-mail]

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente de IAM para PHP, puedes quitarla de la aplicación.

Si usas la biblioteca de Google OAuth para PHP directamente o como una dependencia de otra biblioteca cliente, haz lo siguiente:

Actualiza a la versión 1.5.0 o una versión posterior de google-auth-library-php.

Si usas otra biblioteca cliente para firmar BLOB, haz lo siguiente:

Comunícate con [e-mail] para obtener asistencia.

Python

Si usas la biblioteca cliente de IAM para Python directamente o como una dependencia de otra biblioteca cliente, haz lo siguiente:

Agrega la biblioteca cliente de credenciales de la cuenta de servicio para Python a la aplicación. Usa el método sign_blob() para generar una firma.

El nombre de la cuenta de servicio debe usar el carácter comodín - para representar el ID del proyecto:

Válido: Nombre con carácter comodín

projects/-/serviceAccounts/[e-mail]

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente iam_credentials, puedes quitarla de la aplicación.

Si usas la biblioteca de Google OAuth para Python directamente o como una dependencia de otra biblioteca cliente, haz lo siguiente:

Actualiza a la versión 1.21.2 o una versión posterior de google-auth-library-python.

Si usas el cliente Python para Cloud Storage directamente o como una dependencia de otra biblioteca cliente, haz lo siguiente:

Actualiza a la versión 1.30.0 o una versión posterior de python-storage.

Si usas otra biblioteca cliente para firmar BLOB, haz lo siguiente:

Comunícate con [e-mail] para obtener asistencia.

Ruby

Si usas la biblioteca cliente de IAM para Ruby directamente o como una dependencia de otra biblioteca cliente, haz lo siguiente:

Agrega la biblioteca cliente de credenciales de la cuenta de servicio para Ruby a la aplicación. Usa el método sign_service_account_blob() para generar una firma.

El nombre de la cuenta de servicio debe usar el carácter comodín - para representar el ID del proyecto:

Válido: Nombre con carácter comodín

projects/-/serviceAccounts/[e-mail]

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente de IAM para Ruby, puedes quitarla de la aplicación.

Si usas otra biblioteca cliente para firmar BLOB, haz lo siguiente:

Comunícate con [e-mail] para obtener asistencia.

Migra el código que usa la CLI de gcloud

La CLI de Google Cloud proporciona comandos que usa la API de IAM para firmar JWT y BLOB binarios, incluidos los siguientes:

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

A partir del 1 de julio de 2021, actualizaremos estos comandos para usar la API de credenciales de la cuenta de servicio. Este cambio no afectará los comandos para firmar los BLOB.

Si usas la CLI de gcloud para firmar JWT, debes seguir estos pasos antes del 1 de julio de 2021:

1. Comprueba si incluyes la reclamación de la hora de vencimiento (exp) en el conjunto de reclamaciones de JWT.

   Si ya la incluiste, no es necesario que realices ningún cambio. Puedes omitir los pasos restantes.

   Si no incluyes esta reclamación, continúa con el siguiente paso.

2. Verifica si usas el JWT firmado para autenticarte con las API de Google o con otra API que requiera la reclamación de exp.

   Si la omites, la API de IAM lo configurará de forma automática en 1 hora después. Por el contrario, la API de credenciales de la cuenta de servicio no configura este campo de manera automática.

   Si estás seguro de que no necesitas la reclamación de exp, no es necesario que realices ningún cambio. Puedes omitir los pasos restantes.

   Si sabes que necesitas la reclamación de exp o si no estás seguro, continúa con el paso siguiente.

3. Actualiza tu código para crear JWT a fin de que se agregue la reclamación de exp al conjunto de reclamaciones de JWT.

   Puedes configurar la reclamación de exp hasta 1 hora después.

Verifica las cuotas

La cuota para la API de credenciales de la cuenta de servicio es independiente de la cuota para la API de IAM. Si recibiste un aumento de cuota con el fin de firmar JWT y BLOB con la API de IAM, es posible que también debas solicitar un aumento para la API de credenciales de la cuenta de servicio.

Nota: La mayoría de los clientes de Google Cloud usan la cuota predeterminada para firmar JWT y BLOB. Si usas la cuota predeterminada, no es necesario que leas esta sección.

Para ver tu cuota y el uso real de ambas API y, si es necesario, solicitar un aumento de cuota, haz lo siguiente:

1. En la consola de Google Cloud, ve a la página Cuotas.

   Ir a la página Cuotas

2. Selecciona un proyecto. Puedes hacer clic en un proyecto reciente o en Seleccionar proyecto para buscar en todos tus proyectos.

3. En el cuadro de texto Tabla de filtros que se encuentra sobre la tabla, ingresa Sign requests per minute y, luego, selecciona el valor que aparece.

4. En el cuadro de texto Tabla de filtros, selecciona O en la lista desplegable.

5. En el cuadro de texto Tabla de filtros, ingresa Generate credentials y, luego, selecciona el valor que aparece.

   En la consola de Google Cloud, se muestra tu uso actual para firmar JWT y BLOB durante el último minuto, tu uso máximo por minuto durante los últimos 7 días y tu cuota actual, que aparece en la columna Límite.

6. Compara las cuotas de cada fila en la tabla y asegúrate de que la cuota para la API de credenciales de la cuenta de servicio sea mayor que el uso máximo de 7 días de la API de IAM.

7. Opcional: Si tu cuota para la API de credenciales de la cuenta de servicio es demasiado baja, selecciona la casilla de verificación de la API de credenciales de la cuenta de servicio y, luego, haz clic en Editar cuotas. Completa el formulario para solicitar un aumento de cuota.

8. Repite estos pasos para cada proyecto en el que uses la API de IAM a fin de firmar JWT y BLOB.

¿Qué sigue?

• Obtén información sobre cómo crear un JWT firmado o un BLOB binario firmado con la API de REST de credenciales de la cuenta de servicio.
• Obtén información sobre la API de REST para la API de credenciales de la cuenta de servicio.
• Comprende las cuotas y los límites de IAM.