Migra a la API de las 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. Debes migrar a la API de credenciales de la cuenta de servicio antes del 1 de julio de 2021. Además, si usas la herramienta de línea de comandos de gcloud para firmar los JWT, es posible que debas agregar una nueva reclamación al conjunto de reclamaciones del JWT.

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 credenciales de la cuenta de servicio impide que realices la autenticación con un token autofirmado y, luego, obtengas otro token autofirmado. Como resultado, si un atacante obtiene un token firmado, no puede usarlo para actualizar el token.

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 iam-sign-deprecation-public@google.com para solicitar asistencia y proporcionar comentarios detallados.

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 información, consulta Precios de Google Cloud's operations suite.

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 debe establecerse para más de 1 hora después. 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 nueva biblioteca cliente:

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

No válido: Nombre con ID del proyecto

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

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

No válido: Nombre con ID del proyecto

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

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

No válido: Nombre con ID del proyecto

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

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

No válido: Nombre con ID del proyecto

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

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

No válido: Nombre con ID del proyecto

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

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

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente de IAM para Python, 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/my-service-account@my-project.iam.gserviceaccount.com

No válido: Nombre con ID del proyecto

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

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.

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

No válido: Nombre con ID del proyecto

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

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

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

Comunícate con iam-sign-deprecation-public@google.com 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/my-service-account@my-project.iam.gserviceaccount.com

No válido: Nombre con ID del proyecto

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

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

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

Comunícate con iam-sign-deprecation-public@google.com 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/my-service-account@my-project.iam.gserviceaccount.com

No válido: Nombre con ID del proyecto

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

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 otra biblioteca cliente para firmar BLOB, haz lo siguiente:

Comunícate con iam-sign-deprecation-public@google.com 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/my-service-account@my-project.iam.gserviceaccount.com

No válido: Nombre con ID del proyecto

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

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

No válido: Nombre con ID del proyecto

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

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

No válido: Nombre con ID del proyecto

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

Si ya no usas la biblioteca cliente de IAM para Python, 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 iam-sign-deprecation-public@google.com 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/my-service-account@my-project.iam.gserviceaccount.com

No válido: Nombre con ID del proyecto

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

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 iam-sign-deprecation-public@google.com para obtener asistencia.

Migra el código que usa la herramienta de gcloud

La herramienta de línea de comandos de gcloud proporciona comandos que usa la API de IAM para firmar JWT y BLOB binarios, incluidos los siguientes:

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

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 Cloud Console, 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 Cloud Console, 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.

Próximos pasos