GCP Workload Identity Federation permite autorizar identidades externas (por ejemplo del Identity Provider de la empresa, un runner de CI/CD o AWS) para recursos de GCP sin claves permanentes de Service Account de Google. El resultado es Keyless Access con tokens de corta duración que se renuevan automáticamente. En este artículo explico, con un enfoque práctico, los requisitos, la arquitectura, las trampas típicas, los pasos de verificación, los pasos de implementación concretos, así como las medidas de auditoría y monitorización para mantener el funcionamiento seguro y auditable.
¿Por qué Workload Identity Federation?
Workload Identity Federation (WIF) es un mecanismo de intercambio de tokens: un token emitido externamente (frecuentemente un OIDC‑JWT; OIDC significa OpenID Connect, una capa de identidad sobre OAuth 2.0) se intercambia mediante el Google Security Token Service (STS) por un access_token temporal de Google. Las credenciales de corta duración reducen el riesgo de fugas de claves persistentes porque los tokens caducan automáticamente. Al mismo tiempo simplifican la rotación y garantizan que los permisos se controlen de forma centralizada mediante roles de IAM.
Componentes esenciales, brevemente explicados
Un resumen rápido de los términos centrales:
- Workload Identity Pool: Colección de identidades externas confiables. Técnicamente es un recurso de GCP que agrupa providers.
- Provider: Define una fuente de identidad externa como un OIDC‑Issuer o un endpoint AWS STS. Contiene el issuer URI y las allowed‑audiences permitidas.
- Service Account: Identidad interna de GCP con roles; los principals externos pueden asumir esta identidad mediante impersonation.
- STS (Security Token Service): El endpoint de Google para el intercambio de tokens (subject_token → access_token).
- JWKS (JSON Web Key Set): Claves públicas del IdP que se usan para verificar JWTs. Las rotaciones suelen causar fallos si no se gestionan correctamente.
Requisitos previos y primera decisión de arquitectura
Verifique de antemano los requisitos organizativos y técnicos: permisos IAM adecuados para crear pools y providers, un IdP estable con endpoint JWKS disponible, sistemas sincronizados por NTP (la hora es central para la validez de los tokens) y un proyecto de auditoría para el almacenamiento a largo plazo de logs. Decida además si desea permitir sólo determinadas audiences por provider y qué claims utilizará como atributos (por ejemplo repo‑ID, subject, email).
Guía de implementación concreta
El orden es importante: Pool → Provider → Service Account → Binding → Test. A continuación encontrará pasos basados en comandos que debería ejecutar en proyectos de prueba.
1) Crear Workload Identity Pool
gcloud iam workload-identity-pools create my-pool
--project=PROJECT_ID
--location="global"
--display-name="My Identity Pool"
2) Crear OIDC Provider
gcloud iam workload-identity-pools providers create-oidc my-oidc-provider
--project=PROJECT_ID
--location="global"
--workload-identity-pool="my-pool"
--display-name="AzureAD Provider"
--issuer-uri="https://login.microsoftonline.com/TENANT_ID/v2.0"
--allowed-audiences="api://my-app-client-id"
Por qué es importante: el Issuer‑URI y las allowed‑audiences evitan que se acepten tokens arbitrarios. Las audiences son las IDs de cliente destino, es decir, la audience (aud) esperada en el JWT.
3) Crear Service Account y Binding con condición de atributos
gcloud iam service-accounts create my-app-sa
--project=PROJECT_ID
--display-name="Service Account for federated workloads"
PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format='value(projectNumber)')
gcloud iam service-accounts add-iam-policy-binding my-app-sa@PROJECT_ID.iam.gserviceaccount.com
--project=PROJECT_ID
--role=roles/iam.workloadIdentityUser
--member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/my-pool/attribute.repository/my-app"
Buenas prácticas: utilice atributos precisos (aquí attribute.repository) o condiciones de IAM (conditions) para restringir el acceso de forma granular.
4) Probar el intercambio de tokens
curl -s -X POST https://sts.googleapis.com/v1/token
-H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
subject_token_type=urn:ietf:params:oauth:token-type:jwt&
subject_token=EXTERNAL_OIDC_TOKEN&
requested_token_type=urn:ietf:params:oauth:token-type:access_token&
&audience=//iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/my-pool/providers/my-oidc-provider&
scope=https://www.googleapis.com/auth/cloud-platform"
Si el intercambio falla, compruebe: JWT válido, audience, issuer, accesibilidad del JWKS y desajuste del NTP (NTP‑skew).
Operacionalización de GCP Workload Identity Federation
El salto de la prueba de concepto al funcionamiento productivo requiere políticas para el ciclo de vida, las pruebas y la observabilidad. La operacionalización incluye pruebas automáticas, monitorización de las tasas de STS, supervisión del JWKS y revisiones periódicas de IAM.
Pruebas automatizadas
Programe jobs de CI que realicen periódicamente un intercambio completo de tokens y ejecuten una operación API minimalista (p. ej., leer metadatos de un bucket). Establezca umbrales para tiempos de respuesta y tasas de error. Ejemplo de un sencillo script BASH de prueba que verifica el intercambio y el acceso:
#!/bin/bash
# exchange-and-test.sh
EXTERNAL_TOKEN="$1"
PROJECT_NUMBER="$2"
POOL="my-pool"
PROVIDER="my-oidc-provider"
RESPONSE=$(curl -s -X POST https://sts.googleapis.com/v1/token
-H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token_type=urn:ietf:params:oauth:token-type:jwt&subject_token=${EXTERNAL_TOKEN}&requested_token_type=urn:ietf:params:oauth:token-type:access_token&audience=//iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL}/providers/${PROVIDER}&scope=https://www.googleapis.com/auth/cloud-platform")
ACCESS_TOKEN=$(echo "$RESPONSE" | jq -r .access_token)
if [ -z "$ACCESS_TOKEN" ] || [ "$ACCESS_TOKEN" == "null" ]; then
echo "Token exchange failed: $RESPONSE" >&2
exit 2
fi
# Test: list buckets (minimal permission vorausgesetzt)
curl -s -H "Authorization: Bearer ${ACCESS_TOKEN}"
"https://storage.googleapis.com/storage/v1/b?project=PROJECT_ID" | jq .
Monitorización, cuotas y límites de tasa de STS
Tenga en cuenta las cuotas de la API STS: altas tasas de intercambio (p. ej., muchos jobs pequeños de CI) pueden alcanzar los límites. Supervise las tasas de error de las API de Google y configure backoff/retry en los clientes. Además, debe crear alarmas para aumentos inusuales de impersonaciones o intercambios de tokens.
# Beispiel: einfache Log‑Abfrage nach STS Exchanges
gcloud logging read 'protoPayload.methodName="google.iam.sts.v1.Sts.Exchange"' --project=PROJECT_ID --limit=50
Rotación de JWKS y estabilidad del IdP
Las rotaciones JWKS en el IdP son una causa frecuente de fallos: se publica un nuevo par de claves, pero los clientes almacenan en caché claves antiguas. Verifique la disponibilidad del endpoint JWKS, el TTL de caché de sus clientes y coordine las rotaciones. Una fase de pruebas antes del paso a producción evita fallos inesperados.
Prácticas de auditoría y forense
La auditoría es especialmente importante con WIF porque los tokens de corta duración no son visibles en los inventarios. Active al menos:
- Cloud Audit Logs: Admin Activity (cambios), Data Access (acceso a datos, activar opcionalmente), System Event Logs.
- STS y Impersonation Events: muestran los intercambios de tokens y quién se ha hecho pasar por un Service Account.
- Exportación a BigQuery para análisis a largo plazo y consultas forenses.
Ejemplo: Consulta de BigQuery para eventos de Exchange
-- Búsqueda de Token Exchanges y eventos de Impersonation
SELECT
protopayload_auditlog.authenticationInfo.principalEmail AS principal,
timestamp,
protopayload_auditlog.methodName AS method,
resource.labels.project_id AS project_id
FROM `PROJECT_ID.logging_dataset.cloudaudit_googleapis_com_activity_*`
WHERE protopayload_auditlog.methodName LIKE "%workloadIdentityPools%"
OR protopayload_auditlog.methodName LIKE "%Sts.Exchange%"
ORDER BY timestamp DESC
LIMIT 100;
Use estas consultas también para alertas automáticas (p. ej. principals inesperados o tasas elevadas).
Específico para operación de Zammad
En instalaciones de Zammad que usan GCS o Pub/Sub, recomendamos los siguientes puntos: limite las funciones a las acciones estrictamente necesarias (p. ej. roles/storage.objectCreator en lugar de administrador completo), instrumente los flujos de subida de modo que cada subida genere un evento en el registro de auditoría, y realice comprobaciones periódicas de integridad de la lista de objetos contra los registros de auditoría para detectar subidas perdidas o no autorizadas. Las configuraciones de Zammad con backends de almacenamiento externos deberían tener vistas de monitorización dedicadas, de modo que errores de subida, errores de autenticación o respuestas Permission‑Denied sean detectados inmediatamente.
Diseño de permisos: privilegios mínimos y modelo de roles
Una introducción estable de WIF suele fallar por roles demasiado amplios. Trabaje con un modelo de roles que apoye los siguientes principios: Least Privilege (privilegios mínimos), Segregation (roles separados para lectura/escritura/auditoría) y Contextual Binding (acceso solo con los claims correctos). Ejemplos:
- roles/storage.objectViewer: para funciones de lectura
- roles/storage.objectCreator: para trabajos de subida
- Rol personalizado con exactamente los métodos API requeridos cuando las funciones predefinidas son demasiado amplias
Revise cada rol mediante una revisión de permisos IAM: ¿qué métodos API se necesitan realmente? Elimine todo lo que no sea estrictamente necesario.
Migración de Service‑Account‑Keys: plan de sustitución gradual
Desarrolle una migración escalonada en lugar de un corte brusco. Fases típicas:
- Inventariar: ¿Qué servicios usan Service‑Account‑Keys? Use registros y escaneos de Secret‑Management.
- Operación en paralelo: implemente acceso WIF en paralelo a las claves existentes; utilice feature‑flags o overrides de configuración.
- Prueba: pruebas cercanas a producción con shadow‑traffic o proyectos de prueba.
- Baja gradual: rotar y revocar claves tras pruebas exitosas, eliminar claves en Secret Manager.
Importante: mantenga una opción de recuperación probada (p. ej. una clave recreada temporalmente y con restricciones estrictas) para el caso de una caída inesperada, documentada y susceptible de auditoría.
Crear y eliminar de forma segura una clave de emergencia
Sólo en emergencias reales: genere la clave, guárdela cifrada y elimínela inmediatamente tras la RESTauración. Ejemplo:
# Generar clave SA temporal y guardar en Secret Manager
gcloud iam service-accounts keys create /tmp/temp-key.json
--iam-account=my-app-sa@PROJECT_ID.iam.gserviceaccount.com
# Subir a Secret Manager (cifrado mediante KMS)
gcloud secrets create emergency-sa-key --data-file=/tmp/temp-key.json --replication-policy="automatic"
# Tras la RESTauración: eliminar
rm /tmp/temp-key.json
gcloud secrets delete emergency-sa-key --quiet
Comprobaciones prácticas de resolución de problemas
Pasos de comprobación sistemáticos cuando falla el intercambio de tokens:
- Validación JWT: Issuer (iss), Audience (aud), exp/nbf. Utilice jwt‑inspektor o comprobaciones basadas en jq.
- Disponibilidad de JWKS: curl > estado, verifique las Key IDs (kid).
- Desincronización NTP: ntpq -p o chronyc tracking.
- IAM‑Binding: Verifique que el principalSet se referencia correctamente (PROJECT_NUMBER, Pool, Provider, Attribute).
- Cloud Audit Logs: Busque entradas Sts.Exchange y mensajes de error.
# JWKS Check
curl -s https://login.microsoftonline.com/TENANT_ID/discovery/v2.0/keys | jq '.keys[] | {kid, kty, use}'
# NTP check (chrony)
chronyc tracking
# Check Sts.Exchange failures in logs
gcloud logging read 'protoPayload.methodName:"Sts.Exchange" AND severity>=ERROR' --project=PROJECT_ID --limit=50
Estrategia de contingencia (técnica y organizativa)
Defina procedimientos de emergencia claros y probados: generación temporal de claves y gestión controlada de secretos (Secret Manager), proveedores secundarios en pools, así como rollbacks documentados a mecanismos de autenticación previos. Cada caso excepcional debe registrarse, estar limitado en el tiempo y auditarse al finalizar. A nivel organizativo debe nombrarse un Incident‑Owner y existir un plan de comunicaciones claro que informe a los equipos afectados y describa las medidas de revocación.
Tareas concretas para el despliegue en producción
- Pruebas de Exchange automatizadas en CI con alarmas.
- Monitoreo de JWKS y coordinación de rotaciones con los operadores del IdP.
- Exportación de todos los logs relevantes (Audit, STS, Impersonation) a un dataset de BigQuery asegurado.
- Revisiones periódicas de IAM y uso de Custom Roles en lugar de broad roles/editor.
- Documentar y probar el proceso de clave de emergencia.
Conclusión
GCP Workload Identity Federation es un método eficiente y seguro para permitir que workloads heterogéneos accedan a GCP sin claves. El esfuerzo operativo se concentra en atributos/conditions de grano fino, la estabilidad de JWKS, la monitorización de cuotas STS y un robusto despliegue de auditoría. Para integraciones con Zammad y runners de CI/CD fuera de GCP, WIF ofrece una alternativa mantenible frente a las claves —siempre que desde el inicio se planifiquen pruebas, monitorización y planes de contingencia. Con un plan de migración escalonado, roles claros y runbooks verificables, reduce riesgos y establece un proceso auditado y repetible para el acceso sin claves.
Resumen breve adicional: tareas imprescindibles
- Prueba: realizar el Token Exchange de forma automatizada desde el entorno objetivo.
- Monitorización: supervisar tasas de STS, eventos de Impersonation y disponibilidad de JWKS.
- Audit: exportar logs, preparar consultas en BigQuery, configurar alertas.
- Seguridad: roles IAM mínimos, RESTricciones de Audience/Claim, revisión periódica de IAM.
- Plan de contingencia: claves de cuenta de servicio de corta duración solo en casos de emergencia; después rotarlas y eliminarlas.
Operación & notas de arquitectura
En la práctica suele establecerse un proxy local de intercambio de tokens: reduce las llamadas directas al STS, centraliza las cachés JWKS, implementa lógica de backoff/circuit‑breaker y proporciona métricas centrales. Asegúrese de que el almacenamiento en caché respete estrictamente la TTL del token—los tokens locales prolongados generan ventanas de revocación incontrolables. Coloque el proxy en un segmento de red seguro con egress restringido y limite sus permisos de manera estricta. Registre la ID del principal original como un campo de trazado propio, de modo que las consultas de auditoría puedan correlacionar los exchanges con accesos API posteriores. Defina SLAs para la disponibilidad del Exchange y un fallback probado y con límite temporal (clave fuertemente restringida y rotatoria automática). De este modo se pueden operar las integraciones en software empresarial a medida de forma estable y con gestión de riesgos.
Para este tema también son importantes las credenciales de corta duración. El artículo contextualiza estos aspectos de forma comprensible y muestra en qué hay que fijarse en la práctica diaria.