GCP Workload Identity Federation: implementazione pratica — accesso senza chiavi, credenziali di breve durata e audit

GCP Workload Identity Federation consente di autorizzare identità esterne (ad esempio dall’identity provider aziendale, da un runner CI/CD o da AWS) per risorse GCP senza chiavi permanenti di Google Service‑Account. Il risultato è Keyless Access con token a breve termine scambiati automaticamente. In questo contributo spiego in modo pratico prerequisiti, architettura, errori tipici, passaggi di verifica, passaggi concreti di implementazione nonché misure di audit e monitoring, affinché l’operatività rimanga sicura e verificabile.

Perché Workload Identity Federation?

Workload Identity Federation (WIF) è un meccanismo di scambio token: un token emesso esternamente (spesso un OIDC‑JWT; OIDC sta per OpenID Connect, uno strato di identità su OAuth 2.0) viene scambiato tramite il Google Security Token Service (STS) con un Google‑Access‑Token temporaneo. Credenziali a vita breve riducono il rischio di perdite permanenti di chiavi, poiché i token scadono automaticamente. Allo stesso tempo semplificano la rotazione e garantiscono che le autorizzazioni siano gestite centralmente tramite ruoli IAM.

Componenti essenziali, spiegazione breve

Una panoramica rapida sui termini centrali:

• Workload Identity Pool: raccolta di identità esterne attendibili. Tecnicamente una risorsa GCP che raggruppa i provider.
• Provider: definisce una fonte di identità esterna come un OIDC‑issuer o un endpoint AWS STS. Contiene l’issuer URI e le allowed‑audiences.
• Service Account: identità interna GCP con ruoli; principal esterni possono, tramite impersonazione, assumere l’identità di questo Service Account.
• STS (Security Token Service): l’endpoint Google per il token‑exchange (subject_token → access_token).
• JWKS (JSON Web Key Set): chiavi pubbliche dell’IdP utilizzate per la verifica dei JWT. Le rotazioni spesso causano interruzioni se non gestite correttamente.

Prerequisiti e prima decisione architetturale

Verifichi preventivamente requisiti organizzativi e tecnici: permessi IAM adeguati per creare pool e provider, un IdP stabile con endpoint JWKS disponibile, sistemi sincronizzati tramite NTP (l’orario è fondamentale per la validità dei token) e un progetto di audit per la conservazione a lungo termine dei log. Decida inoltre se consentire per provider solo determinate audience e quali claim utilizzare come attributi (es. repo‑ID, subject, email).

Guida di implementazione concreta

L’ordine è importante: Pool → Provider → Service Account → Binding → Test. Di seguito trova i passaggi basati su comandi da eseguire in progetti di test.

1) Identity Pool anlegen

gcloud iam workload-identity-pools create my-pool 
  --project=PROJECT_ID 
  --location="global" 
  --display-name="My Identity Pool"

2) OIDC Provider anlegen

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"

Perché questo è importante: l’issuer‑URI e le allowed‑audiences impediscono che vengano accettati token arbitrari. Le audience sono gli ID client di destinazione, cioè l’audience attesa (aud) nel JWT.

3) Service Account anlegen und Binding mit Attributbedingung

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"

Buona pratica: utilizzare attributi precisi (qui attribute.repository) o condizioni IAM (conditions) per limitare l’accesso in modo granulare.

4) Testare lo scambio di token

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"

Se lo scambio fallisce, verificate: JWT valido, audience, issuer, raggiungibilità del JWKS e deriva NTP.

Operationalizzare GCP Workload Identity Federation

Il passaggio dal Proof‑of‑Concept alla produzione richiede politiche per il lifecycle, il testing e l’observability. L’operationalizzazione comprende test automatici, monitoraggio dei tassi STS, sorveglianza del JWKS e revisioni periodiche dell’IAM.

Test automatizzati

Programmate job CI che eseguono regolarmente un token‑exchange completo e svolgono un’operazione API minimalista (ad es. leggere i metadati di un bucket). Definite soglie per i tempi di risposta e i tassi di errore. Esempio di un semplice script BASH che testa lo exchange e l’accesso:

#!/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 .

Monitoring, Quotas und STS‑Rate Limits

Tenete conto delle quote dell’API STS: alte frequenze di exchange (p.es. molti piccoli job CI) possono raggiungere i limiti. Monitorate le quote di errore delle Google API e configurate backoff/retry nei client. Inoltre dovreste impostare allarmi per aumenti anomali di impersonazioni o scambi di token.

# Beispiel: einfache Log‑Abfrage nach STS Exchanges
gcloud logging read 'protoPayload.methodName="google.iam.sts.v1.Sts.Exchange"' --project=PROJECT_ID --limit=50

Rotazione JWKS e stabilità dell’IdP

Le rotazioni JWKS presso l’IdP sono una causa frequente di guasti: viene pubblicata una nuova coppia di chiavi, ma i client memorizzano in cache le chiavi vecchie. Verificate la disponibilità dell’endpoint JWKS, il TTL della cache dei vostri client e coordinate le rotazioni. Una fase di test prima della messa in produzione evita interruzioni impreviste.

Pratiche di audit e forense

L’audit è particolarmente importante con WIF, perché i token a breve durata non sono visibili negli inventari. Abilitate almeno:

• Cloud Audit Logs: Admin Activity (modifiche), Data Access (accessi API, da attivare opzionalmente), System Event Logs.
• STS e eventi di impersonazione: mostrano gli scambi di token e chi si è presentato come Service Account.
• Esportazione in BigQuery per analisi a lungo termine e query forensi.

Esempio: query BigQuery per eventi di Exchange

-- Suche nach Token Exchanges und Impersonation Events
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;

Usate queste query anche per alert automatici (es. principals inattesi o tassi elevati).

Specifico per l’operatività di Zammad

Per le installazioni Zammad che utilizzano GCS o Pub/Sub, consigliamo i seguenti punti: limitare i ruoli alle azioni strettamente necessarie (es. roles/storage.objectCreator invece di permessi di amministratore completi), strumentare i flussi di upload in modo che ogni upload generi un evento di Audit Log, ed eseguire controlli di integrità periodici della lista degli oggetti confrontandola con gli Audit Logs per rilevare upload persi o non autorizzati. Le configurazioni Zammad con backend di storage esterni dovrebbero avere viste di monitoring dedicate in modo che errori di upload, errori di autenticazione o risposte Permission Denied siano immediatamente evidenti.

Progettazione dei permessi: privilegi minimi e modello di ruoli

Una introduzione stabile di WIF spesso fallisce a causa di ruoli troppo ampi. Adottate un modello di ruoli che supporti i seguenti principi: Least Privilege (privilegi minimi), Segregation (ruoli separati per lettura/scrittura/audit) e Contextual Binding (accesso solo con claim corretti). Esempi:

• roles/storage.objectViewer: per funzioni di lettura
• roles/storage.objectCreator: per job di upload
• Ruolo personalizzato con esattamente le API necessarie, quando i ruoli predefiniti sono troppo ampi

Verificate ogni ruolo tramite una revisione dei permessi IAM: quali API sono veramente necessarie? Rimuovete tutto ciò che non è strettamente richiesto.

Migrazione delle chiavi dei Service Account: piano di sostituzione graduale

Sviluppate un percorso di migrazione graduale invece di un cutover brusco. Fasi tipiche:

1. Inventario: quali servizi utilizzano le chiavi dei Service Account? Usate logging e scansione dei sistemi di gestione dei segreti.
2. Esercizio parallelo: implementate l’accesso WIF in parallelo alle chiavi esistenti; usate feature flag o config override.
3. Esecuzione di test: test in condizioni prossime alla produzione con shadow traffic o progetti di test.
4. Decommissioning graduale: ruotate & revocate le chiavi dopo test riusciti, eliminate le chiavi nel Secret Manager.

Importante: mantenete un’opzione di ripristino verificata (es. una chiave temporaneamente ricreata e strettamente limitata) per il caso di un guasto imprevisto, documentata e soggetta ad audit.

Creazione sicura della chiave di emergenza e successiva cancellazione

Solo in caso di reale emergenza: create la chiave, salvatela cifrata e cancellatela immediatamente dopo il ripristino. Esempio:

# Erzeuge temporären SA‑Key und speichere in Secret Manager
gcloud iam service-accounts keys create /tmp/temp-key.json 
  --iam-account=my-app-sa@PROJECT_ID.iam.gserviceaccount.com

# Upload in Secret Manager (verschlüsselt durch KMS)
gcloud secrets create emergency-sa-key --data-file=/tmp/temp-key.json --replication-policy="automatic"

# Nach Wiederherstellung: löschen
rm /tmp/temp-key.json
gcloud secrets delete emergency-sa-key --quiet

Verifiche pratiche per la risoluzione dei problemi

Passaggi di controllo sistematici se lo scambio del token fallisce:

1. Validazione JWT: Issuer (iss), Audience (aud), exp/nbf. Utilizzi jwt‑inspektor o verifiche basate su jq.
2. Raggiungibilità JWKS: curl > status, verificare gli ID delle chiavi (kid).
3. Deriva NTP: ntpq -p o chronyc tracking.
4. IAM binding: verificare che il principalSet sia referenziato correttamente (PROJECT_NUMBER, Pool, Provider, Attribute).
5. Cloud Audit Logs: cercare voci Sts.Exchange ed eventuali messaggi di errore.

# 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

Strategia di fallback (tecnica e organizzativa)

Definire procedure di emergenza chiare e testate: generazione temporanea di chiavi e gestione controllata dei segreti (Secret Manager), provider secondari nei Pool, nonché rollback documentati ai meccanismi di autenticazione precedenti. Ogni eccezione deve essere registrata, limitata nel tempo e sottoposta ad audit al termine. A livello organizzativo dovrebbe essere nominato un responsabile dell’incidente e deve esistere un piano di comunicazione chiaro che informi i team interessati e descriva le azioni di revoca.

Attività concrete per il rollout in produzione

• Test automatizzati di Exchange nella CI con allarmi.
• Monitoraggio JWKS e coordinamento delle rotazioni con gli operatori IdP.
• Esportazione di tutti i log rilevanti (Audit, STS, Impersonation) in un dataset BigQuery protetto.
• Revisioni periodiche dell’IAM e utilizzo di Custom Roles invece di ruoli ampi come roles/editor.
• Documentare e testare il processo per la chiave di emergenza.

Conclusione

GCP Workload Identity Federation è un metodo efficiente e sicuro per consentire a workload eterogenei l’accesso keyless a GCP. L’onere operativo si concentra su attributi/conditions a grana fine, stabilità JWKS, monitoraggio delle quote STS e un solido setup di audit. Per integrazioni Zammad e runner CI/CD esterni a GCP, WIF offre un’alternativa manutenibile alle chiavi — a condizione che test, monitoring e piani di fallback siano pianificati fin dall’inizio. Con un piano di migrazione graduale, ruoli definiti e runbook verificabili, si riducono i rischi e si crea un processo auditabile e ripetibile per l’accesso senza chiavi.

Panoramica rapida: attività indispensabili

• Test: eseguire automaticamente il Token Exchange dall’ambiente di destinazione.
• Monitoring: sorvegliare i tassi STS, gli eventi di Impersonation e la disponibilità JWKS.
• Audit: esportare i log, preparare query BigQuery, configurare gli alert.
• Sicurezza: ruoli IAM minimi, RESTrizioni su audience/claim, revisioni IAM periodiche.
• Fallback: chiavi per Service Account a breve durata solo in casi di emergenza; successivamente ruotare e cancellare.

Betrieb & Architekturhinweise

Nella pratica si stabilisce spesso un proxy locale per lo scambio di token: riduce le chiamate dirette a STS, aggrega le cache JWKS, implementa logica di backoff/circuit breaker e fornisce metriche centralizzate. Assicuratevi che il caching rispetti rigidamente la TTL del token—token locali prolungati generano finestre di revoca incontrollabili. Collocate il proxy in un segmento di rete sicuro con egress limitato e riducete fortemente i suoi privilegi. Registrate l’ID del principal originale come campo Trace separato, in modo che le query di audit possano correlare gli exchange con i successivi accessi API. Definite SLA per la disponibilità dell’exchange e un fallback testato e limitato nel tempo (chiave fortemente limitata, che ruota automaticamente). In questo modo le integrazioni nel software aziendale personalizzato possono essere gestite in modo stabile e con consapevolezza del rischio.

Per questo ambito sono importanti anche le credenziali a breve durata. Il contributo contestualizza questi aspetti in modo chiaro e mostra su cosa occorre concentrarsi nella pratica quotidiana.