En esta guía, se describe cómo usar la federación de Workload Identity con otros proveedores de identidad (IdP).
Las cargas de trabajo que se ejecutan fuera de Google Cloud pueden tener acceso a credenciales existentes y específicas del entorno, por ejemplo:
Una carga de trabajo puede obtener una aserción de SAML o un token de OpenID Connect (OIDC) de un proveedor de identidad (IdP) que se ejecuta en el mismo entorno.
A fin de autenticarte en Google Cloud, puedes permitir que la carga de trabajo intercambie sus credenciales específicas del entorno para credenciales de Google Cloud de corta duración mediante la federación de Workload Identity.
Una carga de trabajo puede tener otros tipos de credenciales, como un certificado de cliente mTLS.
Cuando combinas la federación de identidades para cargas de trabajo con un agente de tokens personalizado, puedes permitir que las cargas de trabajo usen otros tipos de credenciales para obtener credenciales de Google Cloud de corta duración.
La federación de Workload Identity puede ayudarte a reducir la cantidad de credenciales que requieren rotación.
En las siguientes secciones, se describe cómo puedes usar la federación de Workload Identity con IdP que admiten protocolos de autenticación de OpenID Connect (OIDC) o SAML.
Prepara el IdP externo
Solo debes realizar estos pasos una vez para cada IdP.
Antes de comenzar, verifica que tu IdP externo cumpla con los siguientes requisitos:
OIDC
El IdP es compatible con OpenID Connect 1.0.
Los metadatos de OIDC y los extremos de JWKS del IdP están protegidos con SSL y TLS, las URL del extremo comienzan con
https://
y son accesibles de forma pública a través de Internet.Google Cloud usa estos extremos para descargar el conjunto de claves de tu IdP y usa este conjunto de claves a fin de validar tokens.
Los extremos que están protegidos con certificados autofirmados no son compatibles con Google Cloud.
SAML
El IdP es compatible con SAML 2.0.
El IdP proporciona un documento de metadatos de SAML SP que describe la configuración del proveedor de servicios de SAML y contiene el certificado de firma del IdP.
Google Cloud usa este certificado para validar las aserciones y respuestas de SAML.
Si tu IdP cumple con estos criterios, haz lo siguiente:
OIDC
Configura tu IdP para que tu carga de trabajo pueda obtener tokens de ID que cumplan con los siguientes criterios:
- Los tokens se firman con el algoritmo
RS256
oES256
. Los tokens contienen una reclamación
aud
con el siguiente valor:https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
Reemplaza lo siguiente:
PROJECT_NUMBER
: Es el número del proyecto de Google Cloud que usas para crear el grupo de Workload Identity.POOL_ID
: Es un ID que elijas que identifique el grupo de Workload Identity. Debes usar el mismo ID cuando crees el grupo de identidades para cargas de trabajo más adelante.PROVIDER_ID
: Es un ID que elijas que identifique al proveedor de grupos de Workload Identity. Debes usar el mismo ID cuando crees el proveedor de grupos de Workload Identity más adelante.
Como alternativa, puedes configurar el proveedor del grupo de Workload Identity para que espere un público personalizado.
Los tokens contienen una reclamación
exp
que está en el futuro y una reclamacióniat
que está en el pasado.El valor de
exp
debe ser mayor que el deiat
en 24 horas como máximo.
Por lo general, es mejor usar tokens de ID cuando realizas un intercambio de tokens, ya que estos reflejan la identidad del usuario. Si decides usar tokens de acceso, asegúrate de que los tokens de acceso cumplan con los siguientes requisitos adicionales:
- Los tokens de acceso tienen formato de token web JSON
Los tokens de acceso contienen una reclamación
ISSUER
para que la URLISSUER/.well-known/openid-configuration
apunte al extremo de metadatos OIDC del IdP.Para subir claves JWK locales (vista previa), consulta Administra JWKs de OIDC.
SAML
Configura tu IdP para que las aserciones de SAML contengan elementos que cumplan con los siguientes criterios:
- Un elemento
Issuer
configurado en el ID de entidad configurado en el proveedor del grupo de Workload Identity. El formato del emisor debe omitirse o establecerse enurn:oasis:names:tc:SAML:2.0:nameid-format:entity
. - Un elemento
Subject
con lo siguiente:- un elemento
NameID
. - exactamente un elemento
SubjectConfirmation
conMethod
configurado comourn:oasis:names:tc:SAML:2.0:cm:bearer
. - un elemento
SubjectConfirmationData
conNotOnOrAfter
configurado en una marca de tiempo que se produce en el futuro y no hay un valorNotBefore
- un elemento
Un elemento
Conditions
con lo siguiente:- Se omitió
NotBefore
o pertenece al pasado. - Se omitió
NotOnOrAfter
o pertenece al futuro. Un
Audience
con el siguiente formato:https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
Reemplaza lo siguiente:
PROJECT_NUMBER
: Es el número del proyecto de Google Cloud que usas para crear el grupo de Workload Identity.POOL_ID
: Es un ID que elijas que identifique el grupo de Workload Identity. Debes usar el mismo ID cuando crees el grupo de identidades para cargas de trabajo más adelante.PROVIDER_ID
: Es un ID que elijas que identifique al proveedor de grupos de Workload Identity. Debes usar el mismo ID cuando crees el proveedor de grupos de Workload Identity más adelante.
- Se omitió
al menos un elemento
AuthnStatement
.un elemento
SessionNotOnOrAfter
con una marca de tiempo que ocurra en el futuro. De manera alternativa, omite el elemento.
Para las aserciones de SAML que se incluyen en una respuesta SAML, la respuesta SAML debe contener lo siguiente:
- exactamente una aserción que cumpla con los criterios de aserción de SAML que se describió antes en esta sección.
- un atributo
IssueInstant
con un valor de menos de 1 hora de antigüedad. - el código de estado
urn:oasis:names:tc:SAML:2.0:status:Success
.
La aserción de SAML, la respuesta o ambas deben estar firmadas.
Configura la federación de Workload Identity
Solo debes realizar estos pasos una vez para cada IdP. Luego, puedes usar el mismo grupo y proveedor de Workload Identity para varias cargas de trabajo y en varios proyectos de Google Cloud.
Para comenzar a configurar la federación de Workload Identity, haz lo siguiente:
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Es mejor usar un proyecto exclusivo para administrar los grupos y los proveedores de identidades para cargas de trabajo.
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.
Administra JWK de OIDC (opcional)
En esta sección, se muestra cómo administrar los JWK de OIDC subidos de forma automática en los proveedores de OIDC del grupo de Workload Identity.
Crea un proveedor y sube JWK de OIDC
Para crear JWK de OIDC, consulta Implementaciones de JWT, JWS, JWE, JWK y JWA.
Para subir un archivo JWK de OIDC cuando creas un proveedor de grupo de Workload Identity, ejecuta el comando gcloud iam workload-identity-pools providers create-oidc con --jwk-json-path="JWK_JSON_PATH"
.
Reemplaza JWK_JSON_PATH
por la ruta de acceso al archivo JSON de JWK.
Esta operación crea claves subidas con las del archivo.
Actualiza los JWK de OIDC
Para actualizar JWK de OIDC, ejecuta el comando gcloud iam workload-identity-pools providers update-oidc con --jwk-json-path="JWK_JSON_PATH"
.
Reemplaza JWK_JSON_PATH
por la ruta de acceso al archivo JSON de JWK.
Esta operación reemplaza cualquier clave subida existente por las que están en el archivo. No puedes restablecer las claves reemplazadas.
Borra todos los JWK de OIDC subidos
Para borrar todos los JWK de OIDC subidos y volver a usar el URI de la entidad emisora para recuperar las claves, ejecuta el comando gcloud iam workload-identity-pools providers update-oidc con --jwk-json-path="JWK_JSON_PATH"
.
Reemplaza JWK_JSON_PATH
por la ruta a un archivo vacío.
Usa la marca --issuer-uri
para establecer el URI de la entidad emisora.
Esta operación borra todas tus claves subidas existentes con las del archivo. No puedes restablecer las claves borradas.
Define una condición y la asignación de atributos
Los tokens de OIDC o las aserciones de SAML emitidas por el IdP pueden contener varios atributos, y debes decidir qué atributo deseas usar como identificador de asunto (google.subject
) en Google Cloud.
De manera opcional, puedes asignar atributos adicionales. Luego, puedes hacer referencia a estos atributos adicionales cuando otorgues acceso a los recursos.
OIDC
Las asignaciones de atributos pueden usar las reclamaciones incorporadas en el token de ID o el token de acceso emitido por el IdP externo.
Debes asignar una de estas reclamaciones a google.subject
para identificar de forma única al usuario. Para protegerte contra las amenazas de falsificación de identidad, elige un reclamo con un valor único que no pueda cambiarse.
Muchos IdP propagan la reclamación sub
con un ID inmutable y único. Para estos IdP, considera asignar la reclamación de sub
a google.subject
:
google.subject=assertion.sub
Evita usar una reclamación como email
con este propósito. Por lo general, las direcciones de correo electrónico se pueden reasignar o cambiar, por lo que no identifican de forma única y permanente a un usuario.
SAML
Tus asignaciones de atributos pueden usar los elementos <Subject>
y <Attribute>
incorporados en la aserción emitida por el IdP externo. Se puede hacer referencia a los atributos de SAML mediante las siguientes palabras clave:
assertion.subject
, contiene elNameID
del usuario autenticado que se encontró en el elemento<Subject>
.assertion.attributes['ATTRIBUTE_NAME']
, contiene una lista de valores para el<Attribute>
con nombre similar.
Debes asignar una de estas reclamaciones a google.subject
para identificar de forma única al usuario. Para protegerte contra las amenazas de falsificación de identidad, elige un reclamo con un valor único que no pueda cambiarse.
Muchos IdP propagan el NameId
con un ID inmutable y único. Para estos IdP, considera asignar el atributo NameId
a google.subject
:
google.subject=assertion.subject
Evita usar un atributo como http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
para este fin. Por lo general, las direcciones de correo electrónico se pueden reasignar o cambiar, por lo que no identifican de forma única y permanente a un usuario.
De manera opcional, puedes definir una condición de atributo.
Las condiciones de los atributos son expresiones CEL que pueden verificar los atributos de aserción y los atributos de destino. Si la condición del atributo se evalúa como true
para una credencial determinada, se acepta la credencial. De lo contrario, se rechaza la credencial.
OIDC
Puedes usar una condición de atributo a fin de restringir qué usuarios pueden usar la federación de Workload Identity para obtener tokens de Google Cloud de corta duración.
Por ejemplo, la siguiente condición restringe el acceso a los tokens que contienen una reclamación service_account
personalizada con un valor true
:
assertion.service_account==true
SAML
Puedes usar una condición de atributo a fin de restringir qué usuarios pueden usar la federación de Workload Identity para obtener tokens de Google Cloud de corta duración.
Por ejemplo, la siguiente condición restringe el acceso a las aserciones que contienen un atributo https://example.com/SAML/Attributes/AllowGcpFederation
personalizado con un valor true
:
assertion.attributes['https://example.com/SAML/Attributes/AllowGcpFederation'][0]=='true'
Crea el proveedor y el grupo de Workload Identity
Roles obligatorios
Para obtener los permisos que necesitas para configurar la federación de Workload Identity, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto:
-
Administrador de grupos de Workload Identity (
roles/iam.workloadIdentityPoolAdmin
) -
Administrador de cuenta de servicio (
roles/iam.serviceAccountAdmin
)
Si quieres obtener más información para otorgar roles, consulta Administra el acceso.
También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.
De manera alternativa, el rol básico de propietario de IAM (roles/owner
) también incluye permisos para configurar la federación de identidades.
No deberías otorgar roles básicos en un entorno de producción, pero puedes otorgarlas en un entorno de desarrollo o de prueba.
Ya recopilaste toda la información que necesitas para crear un grupo y un proveedor de Workload Identity:
Consola
En la consola de Google Cloud, ve a la página Proveedor y grupo de cargas de trabajo nuevos.
En Crear un grupo de identidades, ingresa lo siguiente:
- Nombre: Es el nombre del grupo. El nombre también se usa como el ID del grupo. No puedes cambiar el ID del grupo más adelante.
- Descripción: Es el texto que describe el propósito del grupo.
Haz clic en Continuar.
Establece la configuración del proveedor de la siguiente manera:
OIDC
- En Selecciona un proveedor, selecciona OpenID Connect (OIDC).
- En Nombre del proveedor, ingresa un nombre para el proveedor. El nombre también se usa como el ID del proveedor. No puedes cambiar el ID del proveedor después de crearlo.
- En URL de la entidad emisora, ingresa la URL de la entidad emisora de tu IdP. La URL debe comenzar con
https://
. - Opcional: En Archivo JWK (JSON), elige un archivo JWK para subir. Si no se proporciona este campo, Google Cloud intenta recuperar un JWK de la entidad emisora.
- Público permitido: Público esperado de tokens de ID.
SAML
- En Selecciona un proveedor, selecciona SAML.
- En Nombre del proveedor, ingresa un nombre para el proveedor. El nombre también se usa como el ID del proveedor. No puedes cambiar el ID del proveedor después de crearlo.
- En Archivo de metadatos de IdP (XML), sube el documento XML de metadatos de SAML que proporciona tu proveedor de identidad.
Haz clic en Continuar.
En Configura los atributos del proveedor, agrega las asignaciones de atributos que identificaste antes en esta guía.
En Condiciones del atributo, ingresa la condición del atributo que identificaste antes en esta guía. Deja el campo en blanco si no tienes una condición de atributo.
Para crear el grupo y el proveedor de Workload Identity, haz clic en Guardar.
gcloud
Para crear un nuevo grupo de Workload Identity, ejecuta el siguiente comando:
gcloud iam workload-identity-pools create POOL_ID \ --location="global" \ --description="DESCRIPTION" \ --display-name="DISPLAY_NAME"
Reemplaza lo siguiente:
POOL_ID
: el ID único para el grupo.DISPLAY_NAME
: el nombre del grupo.DESCRIPTION
: una descripción del grupo que eliges. Esta descripción aparece cuando otorgas acceso a identidades de grupo.
Para agregar un proveedor de grupos de Workload Identity, haz lo siguiente:
OIDC
Para agregar un proveedor de grupos de Workload Identity de OIDC, ejecuta el siguiente comando:
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \ --location="global" \ --workload-identity-pool="POOL_ID" \ --issuer-uri="ISSUER" \ --allowed-audiences="AUDIENCE" \ --attribute-mapping="MAPPINGS" \ --attribute-condition="CONDITIONS" --jwk-json-path="JWK_JSON_PATH"
Reemplaza lo siguiente:
PROVIDER_ID
: Un ID de proveedor de grupos de identidades para cargas de trabajo único que elijas.POOL_ID
: El ID del grupo de identidades de cargas de trabajo que creaste antes.ISSUER
: Es un URI de la entidad emisora, como se define en los metadatos de OIDC.AUDIENCE
: El público esperado de los tokens de ID, que, para muchos proveedores, coincide con el ID de cliente.MAPPINGS
: Una lista separada por comas de las asignaciones de atributos que creaste antes en esta guía.CONDITIONS
: Es una condición de atributo opcional que creaste antes en esta guía. Quita el parámetro si no tienes una condición de atributo.JWK_JSON_PATH
: Una ruta de acceso opcional a un JWK de OIDC subido de forma local. Si no se proporciona este parámetro, Google Cloud usa la ruta de acceso/.well-known/openid-configuration
de tu IdP para obtener los JWK que contienen las claves públicas.
SAML
Para agregar un proveedor de grupos de Workload Identity de SAML, ejecuta el siguiente comando:
gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \ --location="global" \ --workload-identity-pool="POOL_ID" \ --idp-metadata-path="IDP_METADATA_PATH" \ --attribute-mapping="MAPPINGS" \ --attribute-condition="CONDITIONS"
Reemplaza lo siguiente:
POOL_ID
: el ID del grupo.IDP_METADATA_PATH
: la ruta local al documento de metadatos del IdP de SAMLMAPPINGS
: una lista separada por comas de las asignaciones de atributos que creaste antes en esta guía.CONDITIONS
: la condición de atributo que creaste antes en esta guía (opcional).
El prefijo
gcp-
está reservado y no se puede usar en un ID de grupo ni de proveedor.Opcional: Acepta las aserciones de SAML encriptadas de tu IdP
Para permitir que tu IdP de SAML 2.0 produzca aserciones de SAML encriptadas que la federación de identidades de personal pueda aceptar, haz lo siguiente:
- En la federación de identidades para cargas de trabajo, haz lo siguiente:
- Crea un par de claves asimétricas para tu proveedor de grupos de identidades para cargas de trabajo.
- Descargar un archivo de certificado que contenga la clave pública
- Configura tu IdP de SAML para usar la clave pública a fin de encriptar las aserciones de SAML que emite.
- En el IdP, haz lo siguiente:
- Habilita la encriptación de aserciones, también conocida como encriptación de tokens.
- Sube la clave pública que creaste en la federación de identidades para cargas de trabajo.
- Confirma que tu IdP produzca aserciones de SAML encriptadas.
Crea claves de encriptación de aserciones de SAML de la federación de identidades para cargas de trabajo
En esta sección, se explica cómo crear un par de claves asimétricas que permite que la federación de identidades para cargas de trabajo acepte aserciones de SAML encriptadas.
Google Cloud usa la clave privada para desencriptar las aserciones de SAML que emite tu IdP. Para crear un par de claves asimétricas que se usarán con la encriptación SAML, ejecuta el siguiente comando. Para obtener más información, consulta Algoritmos de encriptación de SAML compatibles.
gcloud iam workload-identity-pools providers keys create KEY_ID \ --workload-identity-pool WORKLOAD_POOL_ID \ --provider PROVIDER_ID \ --location global \ --use encryption \ --spec KEY_SPECIFICATION
Reemplaza lo siguiente:
KEY_ID
: un nombre de clave que elijasWORKLOAD_POOL_ID
: el ID del grupoPROVIDER_ID
: el ID del proveedor-
KEY_SPECIFICATION
: la especificación de clave, que puede serrsa-2048
,rsa-3072
yrsa-4096
.
Después de crear el par de claves, ejecuta el siguiente comando para descargar la clave pública en un archivo de certificado. Solo la federación de identidades de personal tiene acceso a la clave privada.
gcloud iam workload-identity-pools providers keys describe KEY_ID \ --workload-identity-pool WORKLOAD_POOL_ID \ --provider PROVIDER_ID \ --location global \ --format "value(keyData.key)" \ > CERTIFICATE_PATH
Reemplaza lo siguiente:
KEY_ID
: el nombre de la claveWORKLOAD_POOL_ID
: el ID del grupoPROVIDER_ID
: el ID del proveedorCERTIFICATE_PATH
: la ruta en la que se escribe el certificado, por ejemplo,saml-certificate.cer
osaml-certificate.pem
Configura tu IdP compatible con SAML 2.0 para emitir aserciones de SAML encriptadas
Configura tu IdP de SAML para usar el certificado público descargado del último paso a fin de encriptar las aserciones de SAML que emite. Consulta al equipo de IdP para obtener instrucciones específicas.
Después de configurar tu IdP para encriptar las aserciones de SAML, te recomendamos que te asegures de que las aserciones que genera en realidad estén encriptadas. Incluso con la encriptación de aserciones de SAML configurada, la federación de identidades de personal puede procesar aserciones de texto simple.
Borra claves de encriptación de la federación de Workload Identity
Para borrar claves de encriptación de SAML, ejecuta el siguiente comando:gcloud iam workload-identity-pools providers keys delete KEY_ID \ --workload-identity-pool WORKLOAD_POOL_ID \ --provider PROVIDER_ID \ --location global
Reemplaza lo siguiente:
KEY_ID
: el nombre de la claveWORKLOAD_POOL_ID
: el ID del grupoPROVIDER_ID
: el ID del proveedor
Algoritmos de encriptación SAML compatibles
La federación de identidades de personal admite los siguientes algoritmos de transporte de claves:
- http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
- http://www.w3.org/2009/xmlenc11#rsa-oaep"
- http://www.w3.org/2001/04/xmlenc#rsa-1_5"
La federación de identidades para cargas de trabajo admite los siguientes algoritmos de encriptación de bloques:
Autentica una carga de trabajo
Debes seguir estos pasos una vez por cada carga de trabajo.
Permite que tu carga de trabajo externa acceda a los recursos de Google Cloud
Para proporcionar a tu carga de trabajo acceso a los recursos de Google Cloud, te recomendamos que otorgues acceso directo a los recursos al principal. En este caso, la principal es el usuario federado. Algunos productos de Google Cloud tienen limitaciones de las APIs de Google Cloud. Si tu carga de trabajo llama a un extremo de API que tiene una limitación, puedes usar la identidad temporal como cuenta de servicio. En este caso, la principal es la cuenta de servicio de Google Cloud, que actúa como la identidad. Debes otorgar acceso a la cuenta de servicio en el recurso.
Acceso directo a recursos
Puedes otorgar acceso a una identidad federada directamente en los recursos mediante la consola de Google Cloud o la CLI de gcloud.
Console
Para usar la consola de Google Cloud para otorgar roles de IAM directamente en un recurso, debes ir a la página del recurso y, luego, otorgar el rol. En el siguiente ejemplo, se muestra cómo ir a la página de Cloud Storage y otorgar el rol de visualizador de objetos de almacenamiento (roles/storage.objectViewer
) a una identidad federada directamente en un bucket de Cloud Storage.
- En la consola de Google Cloud, ve a la página Buckets de Cloud Storage.
En la lista de buckets, haz clic en el nombre del bucket para el que deseas otorgar el rol.
Elige la pestaña Permisos cerca de la parte superior de la página.
Haz clic en el botón add_box Otorgar acceso.
Aparecerá el cuadro de diálogo Agregar principales.
En el campo Nuevas principales, ingresa una o más identidades que necesiten acceso a tu bucket.
Por tema
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
Reemplaza lo siguiente:
PROJECT_NUMBER
: el número del proyectoPOOL_ID
: el ID del grupo de cargas de trabajoSUBJECT
: el asunto individual asignado desde tu IdP, por ejemplo,administrator@example.com
Por grupo
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP
Reemplaza lo siguiente:
PROJECT_NUMBER
: el número del proyectoWORKLOAD_POOL_ID
: el ID del grupo de cargas de trabajoGROUP
: el grupo asignado desde tu IdP, por ejemplo:administrator-group@example.com
Por atributo
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
Reemplaza lo siguiente:
PROJECT_NUMBER
: el número del proyectoWORKLOAD_POOL_ID
: el ID del grupo de cargas de trabajoATTRIBUTE_NAME
: uno de los atributos que se asignó a partir de tu IdPATTRIBUTE_VALUE
: el valor del atributo.
Elige un rol (o roles) del menú desplegable Selecciona una rol. Los roles que seleccionas aparecen en el panel con una descripción breve del permiso que otorgan.
Haz clic en Guardar.
gcloud
Para usar la CLI de gcloud para otorgar roles de IAM en un recurso en un proyecto, haz lo siguiente:
Obtén el número del proyecto en el que se define el recurso.
gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
Otorga el acceso al recurso.
Para usar la CLI de gcloud a fin de otorgar el rol de usuario de Workload Identity (
roles/iam.workloadIdentityUser
) a identidades externas que cumplan con ciertos criterios, ejecuta el siguiente comando.Por tema
gcloud storage buckets add-iam-policy-binding BUCKET_ID \ --role=roles/storage.objectViewer \ --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"
Por grupo
gcloud storage buckets add-iam-policy-binding BUCKET_ID \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"
Por atributo
gcloud storage buckets add-iam-policy-binding BUCKET_ID \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"
Reemplaza lo siguiente:
BUCKET_ID
: el bucket en el que se otorga accesoPROJECT_NUMBER
: el número del proyecto que contiene el grupo de Workload Identity.POOL_ID
: el ID del grupo de identidades para cargas de trabajoSUBJECT
: el valor esperado para el atributo que asignaste agoogle.subject
GROUP
: el valor esperado para el atributo que asignaste agoogle.groups
ATTRIBUTE_NAME
: el nombre de un atributo personalizado en la asignación de atributosATTRIBUTE_VALUE
: el valor del atributo personalizado en la asignación de atributos
Puedes otorgar roles en cualquier recurso de Google Cloud que admita políticas de permisos de IAM.
Uso de identidad temporal como cuenta de servicio
Para crear una cuenta de servicio para la carga de trabajo externa, haz lo siguiente:
Enable the IAM, Security Token Service, and Service Account Credentials APIs.
Crea una cuenta de servicio que represente la carga de trabajo. Es mejor usar una cuenta de servicio dedicada para cada carga de trabajo.
No es necesario que la cuenta de servicio esté en el mismo proyecto que el grupo de identidades para cargas de trabajo.
Otorga acceso a la cuenta de servicio a los recursos a los que deseas que accedan las identidades externas.
Otorga el rol de usuario de Workload Identity (
roles/iam.workloadIdentityUser
) a la cuenta de servicio:Crea una cuenta de servicio que represente la carga de trabajo. Te recomendamos que uses una cuenta de servicio dedicada para cada carga de trabajo.
No es necesario que la cuenta de servicio esté en el mismo proyecto que el grupo de Workload Identity, pero debes consultar el proyecto que contiene la cuenta de servicio.
Para otorgar acceso a una identidad federada mediante identidad temporal como cuenta de servicio con la consola de Google Cloud o la CLI de gcloud, haz lo siguiente:
Console
Para usar la consola de Google Cloud para otorgar roles de IAM a una identidad federada con una cuenta de servicio, haz lo siguiente:
Para crear una cuenta de servicio que sirva como la identidad que se usará, haz lo siguiente:
Enable the IAM, Security Token Service, and Service Account Credentials APIs.
Crea una cuenta de servicio que represente la identidad de la carga de trabajo. Te recomendamos que uses una cuenta de servicio dedicada para cada carga de trabajo.
No es necesario que la cuenta de servicio esté en el mismo proyecto que el grupo de Workload Identity, pero cuando otorgas acceso a IAM, debes hacer referencia al proyecto que contiene la cuenta de servicio.
Otorga acceso a la cuenta de servicio a los recursos a los que deseas que accedan las identidades externas.
Para otorgar acceso mediante la identidad temporal como cuenta de servicio, haz lo siguiente.
Ve a la página Grupos de Workload Identity.
Selecciona Otorgar acceso.
En el cuadro de diálogo Otorgar acceso a la cuenta de servicio, selecciona Otorgar acceso mediante la identidad temporal como cuenta de servicio.
En la lista Cuentas de servicio, selecciona la cuenta de servicio para las identidades externas que actuarán en nombre de ella y haz lo siguiente:
Para elegir qué identidades en el grupo pueden actuar en nombre de la cuenta de servicio, realiza una de las siguientes acciones:
Para permitir que solo las identidades específicas del grupo de identidades para cargas de trabajo actúen en nombre de la cuenta de servicio, selecciona Solo identidades que coinciden con el filtro.
En la lista Nombre del atributo, selecciona el atributo que deseas filtrar.
En el campo Valor del atributo, ingresa el valor esperado del atributo; por ejemplo, si usas una asignación de atributos
google.subject=assertion.sub
, establece el nombre del atributo ensubject
y el valor del atributo en el valor de la declaraciónsub
en los tokens que emite tu proveedor de identidad externo.
Para guardar la configuración, haz clic en Guardar y, luego, en Descartar.
gcloud
Para usar la CLI de gcloud a fin de otorgar el rol de usuario de Workload Identity (
roles/iam.workloadIdentityUser
) a identidades externas que cumplan con ciertos criterios, ejecuta el siguiente comando.Por tema
gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --role=roles/storage.objectViewer \ --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"
Por grupo
gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"
Por atributo
gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"
Reemplaza lo siguiente:
SERVICE_ACCOUNT_EMAIL
: La dirección de correo electrónico de la cuenta de servicioPROJECT_NUMBER
: el número del proyecto que contiene el grupo de Workload Identity.POOL_ID
: el ID del grupo de identidades para cargas de trabajoSUBJECT
: el valor esperado para el atributo que asignaste agoogle.subject
GROUP
: el valor esperado para el atributo que asignaste agoogle.groups
ATTRIBUTE_NAME
: el nombre de un atributo personalizado en la asignación de atributosATTRIBUTE_VALUE
: el valor del atributo personalizado en la asignación de atributos
Descarga una configuración de credenciales
En esta sección, se describe cómo descargar la configuración de las credenciales mediante la consola de Google Cloud.
Para permitir que tu carga de trabajo acceda a las bibliotecas cliente, primero debes descargar y configurar las credenciales predeterminadas de la aplicación (ADC) mediante lo siguiente:
-
En la consola de Google Cloud, ve a la página Grupos de Workload Identity.
Ir a Grupos de Workload Identity -
En la tabla, selecciona tu grupo para ir a la página de detalles del grupo.
-
Haz clic en Otorgar acceso.
-
Selecciona Otorgar acceso con identidades federadas (recomendado).
-
Para descargar la credencial predeterminada de la aplicación (ADC) de modo que tu carga de trabajo pueda acceder a las bibliotecas cliente, haz lo siguiente:
-
Haz clic en Descargar configuración.
-
En el cuadro de diálogo Configurar tu aplicación, haz lo siguiente:
-
En la lista desplegable Proveedor, selecciona tu proveedor.
-
En ruta de token de OIDC o ruta de aserción de SAML, ingresa la ruta de acceso en la que se encuentra el token o la aserción.
En la lista desplegable Tipo de formato, selecciona el formato.
-
-
Haz clic en Descargar configuración y toma nota de la ruta de acceso en la que guardaste el archivo.
-
Crea una configuración de credenciales
Las bibliotecas cliente de Cloud, la CLI de gcloud y Terraform pueden obtener credenciales externas de forma automática y usarlas para acceder a Google Cloud. Para permitir que las bibliotecas y las herramientas completen este proceso, debes proporcionar un archivo de configuración de credenciales. Este archivo define lo siguiente:
- Dónde obtener credenciales externas
- Qué grupo y proveedor de identidades para cargas de trabajo usar
- Qué cuenta de servicio actuará en nombre de ella si usas la identidad temporal como cuenta de servicio
Las bibliotecas cliente de Cloud obtienen credenciales externas de un archivo local, una URL HTTP, mediante la ejecución de un ejecutable local:
Credenciales basadas en ejecutables: Las bibliotecas inician un ejecutable cada vez que necesitan una credencial nueva. Si el ejecutable logra obtener una nueva credencial externa, debe escribir un documento JSON en
STDOUT
que se ve de la siguiente manera:OIDC
{ "version": 1, "success": true, "token_type": "urn:ietf:params:oauth:token-type:id_token", "id_token": "HEADER.PAYLOAD.SIGNATURE", "expiration_time": 1620499962 }
Si el ejecutable no puede obtener una credencial nueva, debe escribir un documento JSON en
STDOUT
que se vea así:{ "version": 1, "success": false, "code": "401", "message": "Caller not authorized." }
Los documentos JSON usan los siguientes campos:
version
: Es la versión del resultado de JSON. Solo se admite la versión 1.success
: Es el estado de la respuesta.Cuando es
true
, la respuesta debe contener los camposid_token
ytoken_type
. El ejecutable debe salir con el código de salida 0.Cuando es
false
, la respuesta debe contener los camposcode
ymessage
, y salir con un valor distinto de cero.token_type
: el tipo de token de la credencial externa. Los valores admitidos sonurn:ietf:params:oauth:token-type:id_token
urn:ietf:params:oauth:token-type:jwt
id_token
: la credencial externaexpiration_time
: El tiempo de vencimiento del token de OIDC en segundos (tiempo de la época Unix). El campo solo es obligatorio cuando se especifica un archivo de salida en la configuración de la credencial.code
: La string de código de error.message
: el mensaje de error
SAML
{ "version": 1, "success": true, "token_type": "urn:ietf:params:oauth:token-type:saml2", "saml_response": "...", "expiration_time": 1620499962 }
Si el ejecutable no puede obtener una credencial nueva, debe escribir un documento JSON en
STDOUT
que se vea así:{ "version": 1, "success": false, "code": "401", "message": "Caller not authorized." }
Los documentos JSON usan los siguientes campos:
version
: Es la versión del resultado de JSON. Solo se admite la versión 1.success
: Es el estado de la respuesta.Cuando es
true
, la respuesta debe contener los camposid_token
ytoken_type
. El ejecutable debe salir con el código de salida 0.Cuando es
false
, la respuesta debe contener los camposcode
ymessage
, y salir con un valor distinto de cero.token_type
: el tipo de token de la credencial externa. Debe serurn:ietf:params:oauth:token-type:saml2
.saml_response
: Es la respuesta de SAML o la aserción de SAML codificada en base64.expiration_time
: El tiempo de vencimiento de la aserción en segundos (tiempo Unix). El campo solo es obligatorio cuando se especifica un archivo de salida en la configuración de la credencial.code
: La string de código de error.message
: el mensaje de error
Cuando se inicia el ejecutable, las bibliotecas cliente establecen las siguientes variables de entorno:
GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE
: Público de la configuración de las credenciales. Siempre presente.GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE
: El tipo de token del asunto esperado. Siempre presente.GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL
: Correo electrónico de la cuenta de servicio Solo está presente cuando se usa el robo de identidad de cuentas de servicio.GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE
: Ubicación del archivo de salida de la configuración de credenciales. Solo está presente cuando se especifica en la configuración de credenciales.
Para usar credenciales basadas en ejecutables, debes configurar la variable de entorno
GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES
como1
.Credenciales basadas en archivos: Las bibliotecas leen la credencial externa de un archivo de texto sin formato local o JSON. Por ejemplo:
JSON
{ "mytoken": "ey... }
Texto
ey...
La credencial externa puede tener las siguientes características:
- un token de OIDC
- una respuesta de SAML
- una aserción de SAML codificada en base64
Debes actualizar el archivo de forma periódica para que siempre contenga una credencial válida. Por ejemplo, si el token de OIDC o la aserción de SAML son válidos durante una hora, debes actualizar el archivo al menos una vez por hora.
Credenciales basadas en URL: Las bibliotecas realizan una solicitud
GET
a un extremo HTTP cada vez que necesitan una credencial nueva. El extremo debe mostrar una respuesta JSON o de texto sin formato que sea equivalente al formato que usan las credenciales basadas en archivos.
Para crear un archivo de configuración de credenciales, haz lo siguiente:
Credenciales basadas en ejecutables
gcloud iam workload-identity-pools create-cred-config \ projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \ --service-account=SERVICE_ACCOUNT_EMAIL \ --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \ --output-file=FILEPATH.json \ --executable-command=EXECUTABLE_COMMAND \ --executable-timeout-millis=EXECUTABLE_TIMEOUT \ --executable-output-file=EXECUTABLE_OUTPUT_FILE
Reemplaza lo siguiente:
PROJECT_NUMBER
: El número del proyecto que contiene el grupo de Workload Identity.POOL_ID
: El ID del grupo de Workload Identity.PROVIDER_ID
: El ID del proveedor de grupos de Workload Identity.SERVICE_ACCOUNT_EMAIL
: Si usas la identidad temporal como cuenta de servicio, reemplaza por la dirección de correo electrónico de la cuenta de servicio. Omite esta marca si no usas la identidad de otra cuenta de servicio.SERVICE_ACCOUNT_TOKEN_LIFETIME
: Si usas la identidad temporal como cuenta de servicio, reemplaza por la vida útil del token de acceso de la cuenta de servicio, en segundos; el valor predeterminado es de una hora cuando no se proporciona. Omite esta marca si no usas la identidad temporal como cuenta de servicio. Para especificar un ciclo de vida de más de una hora, debes configurar la restricción de la política de la organizaciónconstraints/iam.allowServiceAccountCredentialLifetimeExtension
.FILEPATH
: El archivo en el que se guardará la configuraciónEXECUTABLE_COMMAND
: El comando completo, incluidos los argumentos, para ejecutar a fin de recuperar el token de ID de OIDC, por ejemplo,--executable-command="/path/to/command --foo=bar"
.EXECUTABLE_TIMEOUT
: La duración opcional en milisegundos que se esperará para que se ejecute el ejecutable (el valor predeterminado es de 30 segundos).EXECUTABLE_OUTPUT_FILE
: Una ruta de acceso que apunta a las credenciales 3PI generadas por el ejecutable. Esto es útil para almacenar en caché las credenciales. Si especificas esta ruta de acceso, las bibliotecas de Auth verificarán su existencia antes de ejecutar el archivo ejecutable.
Credenciales basadas en archivos
gcloud iam workload-identity-pools create-cred-config \ projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \ --service-account=SERVICE_ACCOUNT_EMAIL \ --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \ --output-file=FILEPATH.json \ --credential-source-file=TOKEN_FILEPATH \ --credential-source-type=SOURCE_TYPE \ --credential-source-field-name=FIELD_NAME
Reemplaza lo siguiente:
PROJECT_NUMBER
: El número del proyecto que contiene el grupo de Workload Identity.POOL_ID
: El ID del grupo de Workload Identity.PROVIDER_ID
: El ID del proveedor de grupos de Workload Identity.SERVICE_ACCOUNT_EMAIL
: Si usas la identidad de otra cuenta de servicio, reemplaza por la dirección de correo electrónico de la cuenta de servicio. Omite esta marca si no usas la identidad de otra cuenta de servicio.SERVICE_ACCOUNT_TOKEN_LIFETIME
: Si usas la identidad temporal como cuenta de servicio, reemplaza por la vida útil del token de acceso de la cuenta de servicio, en segundos; el valor predeterminado es de una hora cuando no se proporciona. Omite esta marca si no usas la identidad temporal como cuenta de servicio. Para especificar un ciclo de vida de más de una hora, debes configurar la restricción de la política de la organizaciónconstraints/iam.allowServiceAccountCredentialLifetimeExtension
.FILEPATH
: El archivo en el que se guardará la configuración.TOKEN_FILEPATH
: La ruta en la que se almacenan los tokens de ID de OIDC.SOURCE_TYPE
: El formato del archivo de token de ID de OIDC, configurado comotext
(predeterminado) ojson
.FIELD_NAME
: El campo en el archivo de texto que contiene el token (siSOURCE_TYPE
esjson
).
Credenciales basadas en URL
gcloud iam workload-identity-pools create-cred-config \ projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \ --service-account=SERVICE_ACCOUNT_EMAIL \ --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \ --output-file=FILEPATH.json \ --credential-source-url="TOKEN_URL" \ --credential-source-headers="KEY_1=VALUE_1,KEY_2=VALUE_2" \ --credential-source-type=SOURCE_TYPE \ --credential-source-field-name=FIELD_NAME
Reemplaza lo siguiente:
PROJECT_NUMBER
: El número del proyecto que contiene el grupo de Workload Identity.POOL_ID
: El ID del grupo de Workload Identity.PROVIDER_ID
: El ID del proveedor de grupos de Workload Identity.SERVICE_ACCOUNT_EMAIL
: Si usas la identidad temporal como cuenta de servicio, reemplázala por la dirección de correo electrónico de la cuenta de servicio. Omite esta marca si no usas la identidad de otra cuenta de servicio.SERVICE_ACCOUNT_TOKEN_LIFETIME
: Si usas la identidad temporal como cuenta de servicio, reemplaza por la vida útil del token de acceso de la cuenta de servicio, en segundos; el valor predeterminado es de una hora cuando no se proporciona. Omite esta marca si no usas la identidad temporal como cuenta de servicio. Para especificar un ciclo de vida de más de una hora, debes configurar la restricción de la política de la organizaciónconstraints/iam.allowServiceAccountCredentialLifetimeExtension
.FILEPATH
: El archivo para guardar la configuración.TOKEN_URL
: Es la URL del que se recuperará el token de ID de OIDC.KEY_n
,VALUE_n
: Son los encabezados personalizados que se deben incluir en la solicitud HTTP aTOKEN_URL
.SOURCE_TYPE
: Es el formato del archivo de token de ID de OIDC, configurado comotext
(predeterminado) ojson
.FIELD_NAME
: Es el campo en el archivo de texto que contiene el token (siSOURCE_TYPE
esjson
).
Usa la configuración de credenciales para acceder a Google Cloud
Para permitir que las herramientas y las bibliotecas cliente usen tu configuración de credenciales, haz lo siguiente:
Inicializa una variable de entorno
GOOGLE_APPLICATION_CREDENTIALS
y apúntala al archivo de configuración de credenciales:Bash
export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
En el ejemplo anterior,FILEPATH
es la ruta de acceso relativa al archivo de configuración de credenciales.PowerShell
$env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
En el ejemplo anterior,FILEPATH
es la ruta de acceso relativa al archivo de configuración de credenciales.Usa una biblioteca cliente o herramienta que admita la federación de Workload Identity y pueda encontrar credenciales de forma automática:
C++
Las bibliotecas cliente de Google Cloud para C++ admiten la federación de identidades para cargas de trabajo desde la versión v2.6.0. Para usar la federación de identidades para cargas de trabajo, debes compilar las bibliotecas cliente con la versión 1.36.0 o posterior de gRPC.
Go
Las bibliotecas cliente para Go admiten la federación de identidades si usan la versión v0.0.0-20210218202405-ba52d332ba99 o una versión posterior del módulo
golang.org/x/oauth2
.Para verificar qué versión de este módulo usa tu biblioteca cliente, ejecuta los siguientes comandos:
cd $GOPATH/src/cloud.google.com/go go list -m golang.org/x/oauth2
Java
Las bibliotecas cliente para Java admiten la federación de identidades si usan la versión 0.24.0 o posterior del artefacto
com.google.auth:google-auth-library-oauth2-http
.Para verificar qué versión de este artefacto usa tu biblioteca cliente, ejecuta el siguiente comando de Maven en el directorio de tu aplicación:
mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
Node.js
Las bibliotecas cliente de Node.js admiten la federación de identidades para cargas de trabajo si usan la versión 7.0.2 o una versión posterior del paquete
google-auth-library
.Para verificar qué versión de este paquete usa tu biblioteca cliente, ejecuta el siguiente comando en el directorio de tu aplicación:
npm list google-auth-library
Cuando creas un objeto
GoogleAuth
, puedes especificar un ID del proyecto o puedes permitir queGoogleAuth
encuentre el ID del proyecto automáticamente. Para encontrar el ID del proyecto de manera automática, la cuenta de servicio en el archivo de configuración debe tener el rol de Navegador (roles/browser
) o un rol con permisos equivalentes en tu proyecto. Para obtener más información, consulta elREADME
del paquetegoogle-auth-library
.Python
Las bibliotecas cliente para Python admiten la federación de identidades si usan la versión 1.27.0 o posterior del paquete
google-auth
.Para verificar qué versión de este paquete usa tu biblioteca cliente, ejecuta el siguiente comando en el entorno en el que está instalado el paquete:
pip show google-auth
Si deseas especificar un ID del proyecto para el cliente de autenticación, puedes configurar la variable de entorno
GOOGLE_CLOUD_PROJECT
o permitir que el cliente busque el ID del proyecto automáticamente. Para encontrar el ID del proyecto de manera automática, la cuenta de servicio en el archivo de configuración debe tener el rol de Navegador (roles/browser
) o un rol con permisos equivalentes en tu proyecto. Para obtener más información, consulta la guía del usuario del paquetegoogle-auth
.gcloud
Para autenticar con la federación de identidades para cargas de trabajo, usa el comando
gcloud auth login
:gcloud auth login --cred-file=FILEPATH.json
Reemplaza
FILEPATH
por la ruta de acceso al archivo de configuración de credenciales.La asistencia para la federación de identidades para cargas de trabajo en la CLI de gcloud está disponible en la versión 363.0.0 y posteriores de gcloud CLI.
Terraform
El proveedor de servicios en la nube admite la federación de identidades para cargas de trabajo si usas la versión 3.61.0 o una posterior:
terraform { required_providers { google = { source = "hashicorp/google" version = "~> 3.61.0" } } }
gsutil
Para autenticar a través de la federación de identidades para cargas de trabajo, usa uno de los siguientes métodos:
Cuando uses gsutil junto con gcloud, accede con normalidad:
gcloud auth login --cred-file=FILEPATH.json
Cuando uses gsutil como una aplicación de línea de comandos independiente, edita el archivo .boto para incluir la siguiente sección:
[Credentials] gs_external_account_file = FILEPATH
En ambos casos, reemplaza
FILEPATH
por la ruta de acceso al archivo de configuración de la credencial.La asistencia para la federación de identidades para cargas de trabajo en gsutil está disponible en la versión 379.0.0 y posteriores de gcloud CLI.
bq
Para autenticar a través de la federación de identidades para cargas de trabajo, usa el comando
gcloud auth login
de la siguiente manera:gcloud auth login --cred-file=FILEPATH.json
Reemplaza
FILEPATH
por la ruta de acceso al archivo de configuración de credenciales.La compatibilidad con la federación de identidades para cargas de trabajo en bq está disponible en la versión 390.0.0 y posteriores de la CLI de gcloud.
¿Qué sigue?
- Obtén más información sobre la federación de Workload Identity.
- Obtén más información sobre las prácticas recomendadas para usar la federación de Workload Identity.
- Consulta cómo puedes administrar grupos y proveedores de identidades para cargas de trabajo.