GCP Workload Identity Federation praktisch einführen: Keyless‑Access, Short‑Lived‑Credentials und Audit

GCP Workload Identity Federation erlaubt es, externe Identitäten (zum Beispiel vom Unternehmens‑Identity‑Provider, einem CI/CD‑Runner oder AWS) ohne dauerhafte Google Service‑Account‑Keys für GCP‑Ressourcen zu autorisieren. Das Ergebnis ist Keyless Access mit kurzfristigen, automatisch ausgetauschten Tokens. In diesem Beitrag erkläre ich praxisnah Voraussetzungen, Architektur, typische Stolperfallen, Prüfschritte, konkrete Implementierungsschritte sowie Audit‑ und Monitoring‑Maßnahmen, damit der Betrieb sicher und auditfähig bleibt.

Warum Workload Identity Federation?

Workload Identity Federation (WIF) ist ein Token‑Austausch‑Mechanismus: Ein extern ausgestelltes Token (häufig ein OIDC‑JWT; OIDC steht für OpenID Connect, eine Identitätsschicht auf OAuth 2.0) wird über das Google Security Token Service (STS) gegen ein temporäres Google‑Access‑Token getauscht. Kurzlebige Credentials verringern die Gefahr dauerhafter Key‑Lecks, weil Tokens automatisch ablaufen. Gleichzeitig vereinfachen sie Rotation und stellen sicher, dass Berechtigungen zentral über IAM‑Rollen gesteuert werden.

Wesentliche Komponenten kurz erklärt

Ein schneller Überblick über zentrale Begriffe:

• Workload Identity Pool: Sammlung vertrauenswürdiger externer Identitäten. Technisch eine GCP‑Ressource, die Provider gruppiert.
• Provider: Definiert eine externe Identitätsquelle wie ein OIDC‑Issuer oder AWS STS Endpoint. Enthält issuer URI und erlaubte Audiences.
• Service Account: GCP‑Interne Identität mit Rollen; externe Principals dürfen sich via Impersonation als dieser Service Account ausgeben.
• STS (Security Token Service): Der Google Endpoint für Token‑Exchange (subject_token → access_token).
• JWKS (JSON Web Key Set): Öffentliche Schlüssel des IdP, die zur Verifikation von JWTs genutzt werden. Rotationen verursachen oft Ausfälle, wenn sie nicht korrekt gehandhabt werden.

Voraussetzungen und erste Architekturentscheidung

Prüfen Sie vorab organisatorische und technische Voraussetzungen: passende IAM‑Rechte zum Erstellen von Pools und Providern, einen stabilen IdP mit verfügbarer JWKS‑Endpoint, NTP‑synchronisierte Systeme (Uhrzeit ist zentral für Token‑Gültigkeiten) und ein Audit‑Projekt zur langfristigen Log‑Aufbewahrung. Entscheiden Sie außerdem, ob Sie per Provider nur bestimmte Audiences erlauben und welche Claims als Attribute genutzt werden sollen (z. B. repo‑ID, subject, email).

Konkreter Implementierungsleitfaden

Die Reihenfolge ist wichtig: Pool → Provider → Service Account → Binding → Test. Unten finden Sie kommandobasierte Schritte, die Sie in Testprojekten durchspielen sollten.

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"

Warum das wichtig ist: Issuer‑URI und allowed‑audiences verhindern, dass beliebige Tokens akzeptiert werden. Audiences sind die Ziel‑Klienten‑IDs, also die erwartete Audience (aud) im 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"

Gute Praxis: Nutzen Sie präzise Attribute (hier attribute.repository) oder IAM‑Bedingungen (conditions), um Zugriff granular zu beschränken.

4) Token Exchange testen

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"

Scheitert der Exchange, prüfen Sie: gültiges JWT, audience, issuer, JWKS‑Erreichbarkeit und NTP‑Skew.

GCP Workload Identity Federation operationalisieren

Der Sprung vom Proof‑of‑Concept zum produktiven Betrieb erfordert Policies für Lifecycle, Testing und Observability. Operationalisierung umfasst automatische Tests, Monitoring von STS‑Raten, JWKS‑Überwachung und regelmäßige IAM‑Reviews.

Automatisierte Tests

Planen Sie CI‑Jobs, die regelmäßig einen vollständigen Token‑Exchange durchführen und eine minimalistische API‑Operation ausführen (z. B. Bucket‑Metadaten lesen). Legen Sie Grenzwerte für Antwortzeiten und Fehlerraten fest. Beispiel für ein einfaches BASH‑Testskript, das Exchange und Zugriff testet:

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

Beachten Sie STS‑API‑Quotas: Hohe Exchange‑Raten (z. B. viele kleine CI‑Jobs) können an Grenzen stoßen. Überwachen Sie Google‑API Fehlerquoten und konfigurieren Sie Backoff/Retry in Clients. Zusätzlich sollten Sie Alarme für ungewöhnliche Anstiege an Impersonations oder Token Exchanges einrichten.

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

JWKS‑Rotation und IdP‑Stabilität

JWKS‑Rotationen beim IdP sind ein häufiger Ausfallgrund: Ein neues Schlüsselpaar wird veröffentlicht, Clients jedoch cachen alte Schlüssel. Prüfen Sie die JWKS‑Endpoint‑Verfügbarkeit, den Cache‑TTL Ihrer Clients und koordinieren Sie Rotationen. Eine Testphase vor Produktivschaltung vermeidet überraschende Ausfälle.

Audit‑ und Forensik‑Praktiken

Audit ist bei WIF besonders wichtig, weil kurzlebige Tokens in Inventaren nicht sichtbar sind. Aktivieren Sie mindestens:

• Cloud Audit Logs: Admin Activity (Änderungen), Data Access (API Zugriffe, optional aktivieren), System Event Logs.
• STS und Impersonation Events: Diese zeigen Token Exchanges und wer sich als Service Account ausgegeben hat.
• Export in BigQuery für langfristige Analyse und forensische Queries.

Beispiel: BigQuery‑Query für Exchange‑Events

-- 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;

Nutzen Sie diese Queries auch für automatische Alerts (z. B. unerwartete Principals oder hohe Raten).

Speziell für Zammad‑Betrieb

Bei Zammad‑Installationen, die GCS oder Pub/Sub nutzen, empfehlen sich folgende Punkte: begrenzen Sie Rollen auf genau benötigte Aktionen (z. B. roles/storage.objectCreator statt full admin), instrumentieren Sie Upload‑Flows so, dass jeder Upload ein Audit‑Log‑Ereignis besitzt, und führen Sie regelmäßige Integritätschecks der Objektliste gegen Audit Logs durch, um verlorene oder unautorisierte Uploads zu erkennen. Zammad‑Konfigurationen mit externen Storage‑Backends sollten eigene Monitoring‑Sichten erhalten, damit Upload‑Fehler, Auth‑Fehler oder Permission‑Denied‑Antworten sofort auffallen.

Permission Design: Minimalrechte und Rollenmodell

Eine stabile WIF‑Einführung scheitert oft an zu groben Rollen. Arbeiten Sie mit einem Rollenmodell, das folgende Prinzipien unterstützt: Least Privilege (Minimalrechte), Segregation (separate Rollen für Lese/Schreib/Audit), und Contextual Binding (Zugriff nur bei korrekten Claims). Beispiele:

• roles/storage.objectViewer: für Lesefunktionen
• roles/storage.objectCreator: für Upload‑Jobs
• Custom role mit genau den erforderlichen API‑Methoden, wenn vordefinierte Rollen zu breit sind

Prüfen Sie jede Rolle per IAM‑Rechte‑Review: welche API‑Methoden werden wirklich benötigt? Entfernen Sie alles, was nicht strikt erforderlich ist.

Migration von Service‑Account‑Keys: schrittweiser Ablöseplan

Entwickeln Sie einen abgestuften Migrationspfad statt eines harten Cutovers. Typische Phasen:

1. Inventarisieren: Welche Services nutzen Service‑Account‑Keys? Nutzen Sie Logging und Secret‑Management‑Scans.
2. Parallelbetrieb: Implementieren Sie WIF‑Zugriff parallel zu bestehenden Keys; nutzen Sie Feature‑Flags oder Config‑Overrides.
3. Testlauf: Produktionsnahe Tests mit Shadow‑Traffic oder Testprojekten.
4. Schrittweises Decommissioning: Rotate & Revoke Keys nach erfolgreichen Testläufen, delete Keys in Secret Manager.

Wichtig: Behalten Sie eine nachgewiesene Wiederherstellungsoption (z. B. kurzzeitig neu erstellter, streng begrenzter Key) für den Fall eines unerwarteten Ausfalls ein, dokumentiert und auditfähig.

Notfall‑Key sicher erstellen und wieder löschen

Nur in echten Notfällen: Erstellen Sie Key, speichern Sie verschlüsselt und löschen Sie ihn sofort nach Wiederherstellung. Beispiel:

# 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

Praktische Troubleshooting‑Checks

Systematische Prüfungsschritte, wenn Token‑Exchange fehlschlägt:

1. JWT‑Validierung: Issuer (iss), Audience (aud), exp/nbf. Verwenden Sie jwt‑inspektor oder jq‑gestützte Prüfungen.
2. JWKS‑Reachability: curl > status, prüfe Key IDs (kid).
3. NTP‑Skew: ntpq -p oder chronyc tracking.
4. IAM‑Binding: Prüfen Sie, ob das principalSet korrekt referenziert wird (PROJECT_NUMBER, Pool, Provider, Attribute).
5. Cloud Audit Logs: Suche nach Sts.Exchange Einträgen und Fehlermeldungen.

# 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

Rückfallstrategie (Technisch und organisatorisch)

Definieren Sie klare, getestete Notfallverfahren: temporäre Key‑Erzeugung und kontrollierte Geheimnisverwaltung (Secret Manager), sekundäre Provider in Pools, sowie dokumentierte Rollbacks auf vorherige Auth‑Mechanismen. Jeder Ausnahmefall muss protokolliert, zeitlich befristet und nach Abschluss auditiert werden. Organisatorisch sollte ein Incident‑Owner benannt und ein klarer Kommunikationsplan existieren, der betroffene Teams informiert und Maßnahmen zur Revocation beschreibt.

Konkrete To‑Dos für den produktiven Rollout

• Automatisierte Exchange‑Tests in CI mit Alarming.
• JWKS‑Monitoring und Koordination von Rotationen mit IdP‑Betreibern.
• Export aller relevanten Logs (Audit, STS, Impersonation) in ein gesichertes BigQuery‑Dataset.
• Regelmäßige IAM‑Reviews und Nutzung von Custom Roles statt broad roles/editor.
• Notfall‑Key‑Prozess dokumentieren und testen.

Fazit

GCP Workload Identity Federation ist eine effiziente, sichere Methode, um heterogene Workloads keyless auf GCP zugreifen zu lassen. Der operative Aufwand konzentriert sich auf feingranulare Attribute/Conditions, JWKS‑Stabilität, STS‑Quota‑Überwachung und ein robustes Audit‑Setup. Für Zammad‑Integrationen und CI/CD‑Runner außerhalb von GCP bietet WIF eine wartbare Alternative zu Keys — vorausgesetzt, Tests, Monitoring und Rückfallpläne sind von Anfang an eingeplant. Mit einem abgestuften Migrationsplan, klaren Rollen und überprüfbaren Runbooks reduzieren Sie Risiken und schaffen einen auditfähigen, wiederholbaren Prozess für Keyless Access.

Weiterführende Kurzübersicht: unverzichtbare To‑Dos

• Test: Token Exchange automatisiert aus Zielumgebung ausführen.
• Monitoring: STS‑Raten, Impersonation‑Events und JWKS‑Verfügbarkeit überwachen.
• Audit: Logs exportieren, BigQuery‑Queries vorbereiten, Alerts einrichten.
• Security: Minimale IAM‑Rollen, Audience/Claim‑Restriktionen, regelmäßiger IAM‑Review.
• Fallback: Kurzzeitige Service‑Account‑Keys nur in Notfällen, danach rotieren und löschen.

Betrieb & Architekturhinweise

Praktisch etabliert sich häufig ein lokaler Token‑Exchange‑Proxy: Er reduziert direkte STS‑Aufrufe, bündelt JWKS‑Caches, implementiert Backoff/Circuit‑Breaker‑Logik und liefert zentrale Metriken. Achten Sie darauf, dass Caching strikt die Token‑TTL respektiert—verlängerte lokale Tokens erzeugen unkontrollierbare Revocation‑Fenster. Platzieren Sie den Proxy in einem sicheren Netzwerksegment mit eingeschränktem Egress und schränken Sie seine Rechte stark ein. Loggen Sie die Original‑Principal‑ID als eigenes Trace‑Feld, damit Audit‑Queries Exchanges mit späteren API‑Zugriffen korrelieren können. Definieren Sie SLAs für Exchange‑Verfügbarkeit und einen getesteten, zeitlich befristeten Fallback (stark eingeschränkter, automatisch rotierender Key). So lassen sich Integrationen in individuelle Unternehmenssoftware stabil und risikobewusst betreiben.

Für dieses Thema sind auch Short-Lived Credentials wichtig. Der Beitrag ordnet diese Aspekte verständlich ein und zeigt, worauf es im Alltag ankommt.