Migrar a la API de credenciales de cuentas de servicio

La API Service Account Credentials crea credenciales de corta duración para las cuentas de servicio de Gestión de Identidades y Accesos (IAM). También puedes usar esta API para firmar JSON Web Tokens (JWTs), así como blobs de datos binarios que contengan otros tipos de tokens.

La API IAM también contiene métodos para firmar JWTs y blobs binarios. Desde el 1 de julio del 2020, estos métodos están obsoletos en la API REST y en todas las bibliotecas de cliente de la API IAM. Además, si usas Google Cloud CLI para firmar JWTs, puede que tengas que añadir una nueva reclamación al conjunto de reclamaciones del JWT. Puedes seguir usando los métodos obsoletos, pero no admiten funciones avanzadas como el envío de solicitudes HTTP por lotes. Te recomendamos que migres a la API de credenciales de cuentas de servicio.

En comparación con la API IAM, la API de credenciales de cuentas de servicio ofrece más flexibilidad en cuanto al tiempo de vencimiento de los JWTs firmados. Además, la API Service Account Credentials añade varios métodos de API nuevos para generar tokens de suplantación de identidad.

En esta página se explica cómo actualizar el código para usar la API Service Account Credentials. Si quieres enviarnos algún comentario sobre este cambio, puedes rellenar el formulario de comentarios. También puedes usar la dirección de correo [e-mail] para solicitar asistencia y enviar comentarios detallados.

Antes de empezar

• 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

Habilitar los registros de auditoría

Si quieres recibir registros de auditoría de las solicitudes para firmar JWTs y blobs, debes habilitar los registros de auditoría de acceso a datos de la API IAM. Si habilitas los registros de auditoría de acceso a datos para la API IAM, también se habilitarán para la API Service Account Credentials.

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

Diferencias en las entradas del registro de auditoría
Nombre del método	API IAM El nombre del método (protoPayload.methodName) es uno de los siguientes: google.iam.admin.v1.SignBlob google.iam.admin.v1.SignJwt API Service Account Credentials El nombre del método es uno de los siguientes: SignBlob SignJwt
Tipo de solicitud	API 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 Service Account Credentials 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 IAM El nombre del servicio (protoPayload.serviceName) es iam.googleapis.com. API Service Account Credentials El nombre del servicio es iamcredentials.googleapis.com.

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

Migrar código para firmar JWTs

En esta sección se describe cómo migrar el código que firma JWTs a la API de credenciales de cuentas de servicio.

Firmar JWTs con la API REST

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

Diferencias al firmar un JWT
Endpoints HTTP	API IAM La API IAM usa los siguientes métodos y endpoints 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 de la cuenta de servicio. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt En esta URL, el carácter comodín - sustituye al ID del proyecto y sa-email es la dirección de correo de la cuenta de servicio. API Service Account Credentials Usa el siguiente método HTTP y endpoint. No sustituyas 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 de la cuenta de servicio.
Cuerpo de la solicitud	API IAM El cuerpo de la solicitud incluye un campo payload. Su valor es la carga útil de JWT que se va a firmar. La carga útil debe ser un objeto JSON, serializado como una cadena, que contenga un conjunto de reclamaciones de JWT. Si proporcionas una reclamación de tiempo de vencimiento (exp), no debe ser superior a 12 horas en el futuro. Si omites la reclamación exp, se añade automáticamente y se establece en 1 hora en el futuro. API Service Account Credentials El cuerpo de la solicitud incluye un campo payload idéntico al de la API IAM, excepto por el comportamiento de la reclamación del tiempo de vencimiento (exp): Si proporcionas la reclamación de exp, no debe ser de más de 12 horas en el futuro. Si omite la reclamación exp, no se añadirá automáticamente. Debes proporcionar esta reclamación si usas el JWT firmado para autenticarte en las APIs de Google o en otra API que requiera la reclamación exp.
Cuerpo de la respuesta	Ambas APIs usan los mismos campos en el cuerpo de la respuesta.

Firmar JWTs con una biblioteca de cliente

Las bibliotecas de cliente de la API Service Account Credentials son independientes de las bibliotecas de cliente de la API IAM.

Para usar la API Service Account Credentials, añade su biblioteca de cliente a tu aplicación y actualiza el código para usar la nueva biblioteca de cliente:

C#

Añade la biblioteca de cliente de credenciales de cuenta de servicio para C# a tu 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 de proyecto

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

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

Go

Añade la biblioteca cliente de credenciales de cuenta de servicio para Go a tu aplicación. Usa 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 de proyecto

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

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

Java

Añade la biblioteca de cliente de credenciales de cuenta de servicio para Java a tu 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 de proyecto

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

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

Node.js

Añade la biblioteca de cliente de credenciales de cuenta de servicio para Node.js a tu 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 de proyecto

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

Si ya no usas la biblioteca de cliente de gestión de identidades y accesos para Node.js, puedes quitarla de tu aplicación.

PHP

Añade la biblioteca cliente de credenciales de cuenta de servicio para PHP a tu 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 de proyecto

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

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

Python

Añade la biblioteca de cliente de credenciales de cuenta de servicio para Python a tu 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 de proyecto

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

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

Ruby

Añade la biblioteca cliente de credenciales de cuenta de servicio para Ruby a tu 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 de proyecto

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

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

Migrar código para firmar blobs binarios

En esta sección se describe cómo migrar código que firma blobs binarios a la API de credenciales de cuentas de servicio.

Firmar blobs binarios con la API REST

En la siguiente tabla se muestran las diferencias entre firmar un blob binario con la API REST de IAM y firmar un blob binario con la API de credenciales de cuentas de servicio. Actualiza tu código para reflejar estas diferencias:

Diferencias al firmar un blob binario
Endpoints HTTP	API IAM La API IAM usa los siguientes métodos y endpoints 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 de la cuenta de servicio. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob En esta URL, el carácter comodín - sustituye al ID del proyecto y sa-email es la dirección de correo de la cuenta de servicio. API Service Account Credentials Usa el siguiente método HTTP y endpoint. No sustituyas 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 de la cuenta de servicio.
Cuerpo de la solicitud	API IAM El cuerpo de la solicitud incluye un campo bytesToSign. Su valor es una cadena codificada en Base64 que representa el blob binario que se va a firmar. API Service Account Credentials El cuerpo de la solicitud incluye un campo payload que tiene el mismo valor que el campo bytesToSign de la API IAM.
Cuerpo de la respuesta	API IAM El cuerpo de la respuesta contiene un campo keyId, que identifica la clave que se ha usado para firmar el blob, y un campo signature, que contiene una cadena codificada en base64 que representa la firma. API Service Account Credentials El cuerpo de la respuesta contiene un campo keyId idéntico al campo keyId de la API IAM, así como un campo signedBlob idéntico al campo signature de la API IAM. Nota: El campo signedBlob solo contiene la firma, no el blob original.

Firmar blobs binarios con una biblioteca de cliente

Las bibliotecas de cliente de la API Service Account Credentials son independientes de las bibliotecas de cliente de la API IAM.

Para usar la API Service Account Credentials, añade su biblioteca de cliente a tu aplicación y actualiza el código para usar la nueva biblioteca de cliente:

C++

Si usas la biblioteca de cliente de Cloud Storage para C++ para firmar blobs, ya sea directamente o como dependencia de otra biblioteca de cliente, haz lo siguiente:

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

Si usas otra biblioteca de cliente para firmar blobs:

Si necesitas ayuda, ponte en contacto con [e-mail].

C#

Si usas la biblioteca de cliente de IAM para C#,ya sea directamente o como dependencia de otra biblioteca de cliente:

Añade la biblioteca de cliente de credenciales de cuenta de servicio para C# a tu 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 de proyecto

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

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

Si usas el SDK de administrador de Firebase para .NET, ya sea directamente o como dependencia de otra biblioteca de cliente, sigue estos pasos:

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

Si usas otra biblioteca de cliente para firmar blobs:

Si necesitas ayuda, ponte en contacto con [e-mail].

Go

Si usas la biblioteca de cliente de IAM para Go,ya sea directamente o como dependencia de otra biblioteca de cliente:

Añade la biblioteca cliente de credenciales de cuenta de servicio para Go a tu aplicación. Usa 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 de proyecto

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

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

Si usas el SDK de administrador de Go de Firebase, ya sea directamente o como dependencia de otra biblioteca de cliente, haz lo siguiente:

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

Si usas otra biblioteca de cliente para firmar blobs:

Si necesitas ayuda, ponte en contacto con [e-mail].

Java

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

Añade la biblioteca de cliente de credenciales de cuenta de servicio para Java a tu 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 de proyecto

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

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

Si usas la biblioteca de autenticación de Google para Java, ya sea directamente o como dependencia de otra biblioteca de cliente, sigue estos pasos:

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

Si usas el SDK de administrador de Java de Firebase, ya sea directamente o como dependencia de otra biblioteca de cliente, sigue estos pasos:

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

Si usas otra biblioteca de cliente para firmar blobs:

Si necesitas ayuda, ponte en contacto con [e-mail].

Node.js

Si usas la biblioteca de cliente de IAM para Node.js,ya sea directamente o como dependencia de otra biblioteca de cliente:

Añade la biblioteca de cliente de credenciales de cuenta de servicio para Node.js a tu 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 de proyecto

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

Si ya no usas la biblioteca de cliente de gestión de identidades y accesos para Node.js, puedes quitarla de tu aplicación.

Si usas la biblioteca de autenticación de Google para Node.js, ya sea directamente o como dependencia de otra biblioteca de cliente, haz lo siguiente:

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

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

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

Si usas otra biblioteca de cliente para firmar blobs:

Si necesitas ayuda, ponte en contacto con [e-mail].

PHP

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

Añade la biblioteca cliente de credenciales de cuenta de servicio para PHP a tu 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 de proyecto

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

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

Si usas la biblioteca de autenticación de Google para PHP, ya sea directamente o como dependencia de otra biblioteca de cliente, sigue estos pasos:

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

Si usas otra biblioteca de cliente para firmar blobs:

Si necesitas ayuda, ponte en contacto con [e-mail].

Python

Si usas la biblioteca de cliente de IAM para Python,ya sea directamente o como dependencia de otra biblioteca de cliente:

Añade la biblioteca de cliente de credenciales de cuenta de servicio para Python a tu 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 de proyecto

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

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

Si usas la biblioteca de autenticación de Google para Python, ya sea directamente o como dependencia de otra biblioteca de cliente, haz lo siguiente:

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

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

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

Si usas otra biblioteca de cliente para firmar blobs:

Si necesitas ayuda, ponte en contacto con [e-mail].

Ruby

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

Añade la biblioteca cliente de credenciales de cuenta de servicio para Ruby a tu 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 de proyecto

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

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

Si usas otra biblioteca de cliente para firmar blobs:

Si necesitas ayuda, ponte en contacto con [e-mail].

Migrar código que usa la CLI de gcloud

La CLI de Google Cloud proporciona comandos que usan la API IAM para firmar JWTs y blobs binarios, entre los que se incluyen los siguientes:

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

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

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

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

   Si ya incluye esta reclamación, no tiene que hacer ningún cambio. Puedes saltarte los pasos restantes.

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

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

   Si omites esta reclamación, la API de IAM la establecerá automáticamente en 1 hora en el futuro. Por el contrario, la API de credenciales de cuentas de servicio no define este campo automáticamente.

   Si tienes claro que no necesitas la reclamación exp, no tienes que hacer ningún cambio. Puedes saltarte los pasos restantes.

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

3. Actualiza el código para crear JWTs de forma que añada la reclamación exp al conjunto de reclamaciones del JWT.

   Puedes programar la reclamación de exp con hasta 1 hora de antelación.

Consultar cuotas

La cuota de la API Service Account Credentials es independiente de la cuota de la API IAM. Si has recibido un aumento de cuota para firmar JWTs y blobs con la API IAM, es posible que también tengas que solicitar un aumento para la API Service Account Credentials.

Nota: La mayoría Google Cloud de los clientes usan la cuota predeterminada para firmar JWTs y blobs. Si usa la cuota predeterminada, no tiene que leer esta sección.

Para ver tu cuota y el uso real de ambas APIs, así como para solicitar un aumento de la cuota si es necesario, haz lo siguiente:

1. En la Google Cloud consola, 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 todos tus proyectos.

3. En el cuadro de texto Filtrar tabla situado encima de la tabla, introduzca Sign requests per minute y, a continuación, seleccione el valor que aparece.

4. En el cuadro de texto Filtrar tabla, selecciona O en la lista desplegable.

5. En el cuadro de texto Filtrar tabla, introduce Generate credentials y, a continuación, selecciona el valor que aparece.

   La consola Google Cloud muestra el uso actual de la firma de JWTs y blobs durante el último minuto, el pico de uso por minuto de los últimos 7 días y la cuota actual, que aparece en la columna Límite.

6. Compara las cuotas de cada fila de la tabla y asegúrate de que tu cuota de la API Service Account Credentials sea superior al pico de uso de la API IAM de los últimos siete días.

7. Opcional: Si tu cuota de la API Service Account Credentials es demasiado baja, selecciona la casilla de la API Service Account Credentials y haz clic en Editar cuotas. Rellena el formulario para solicitar un aumento de cuota.

8. Repite estos pasos en cada proyecto en el que uses la API de IAM para firmar JWTs y blobs.

Siguientes pasos

• Consulta cómo crear un JWT firmado o crear un blob binario firmado con la API REST de credenciales de cuenta de servicio.
• Consulta los detalles de la API REST de la API Service Account Credentials.
• Consulta las cuotas y los límites de IAM.