Google Cloud Workload Identity Federation: Enterprise Implementation Guide

Overview

Google Cloud Workload Identity Federation (WIF) allows workloads running outside Google Cloud to exchange external identity tokens for short-lived Google credentials. Instead of distributing service account keys to GitHub Actions, Azure DevOps, AWS workloads, Kubernetes clusters, or on-premises applications, enterprises establish trust between Google Cloud IAM and an external identity provider.

Its core purpose is to eliminate static credentials, reduce secret sprawl, and enforce attribute-based access control. Enterprises adopt WIF to support zero-trust access for non-Google workloads, simplify credential rotation, and improve auditability because access is tied to external identities and short-lived tokens rather than unmanaged JSON keys.

Architecture

Core components

• Workload Identity Pool: Logical container for trusted external identities.
• Workload Identity Provider: Defines the external issuer, token type, and attribute mapping.
• Service Account: Google Cloud identity that external workloads can impersonate.
• Security Token Service (STS): Exchanges external tokens for Google federated tokens.
• IAM policy bindings: Authorize external principals to impersonate specific service accounts.

Deployment models

• OIDC federation for GitHub Actions, GitLab, Azure AD, Okta, or custom IdPs.
• AWS federation using AWS STS signed requests and account attributes.
• X.509 or SAML-adjacent enterprise patterns typically fronted by an OIDC broker.

Data flow

1. External workload obtains an OIDC or AWS identity token from its native platform.
2. The workload calls Google STS using a credential configuration file.
3. STS validates issuer, audience, and mapped attributes against the provider.
4. The federated principal impersonates a Google service account if IAM allows it.
5. The workload receives short-lived access tokens for Google APIs.

Implementation Guide

1. Create a workload identity pool

gcloud iam workload-identity-pools create corp-pool --location="global" --display-name="Corporate Federation Pool" --description="Federation for CI/CD and multicloud workloads"

2. Create an OIDC provider

gcloud iam workload-identity-pools providers create-oidc github-provider --location="global" --workload-identity-pool="corp-pool" --display-name="GitHub OIDC Provider" --issuer-uri="https://token.actions.githubusercontent.com" --allowed-audiences="https://iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/corp-pool/providers/github-provider" --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner,attribute.ref=assertion.ref"

3. Create a service account

gcloud iam service-accounts create gha-deploy --display-name="GitHub Deployment Service Account"

4. Allow federated principals to impersonate the service account

gcloud iam service-accounts add-iam-policy-binding gha-deploy@PROJECT_ID.iam.gserviceaccount.com --role="roles/iam.workloadIdentityUser" --member="principalSet://iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/corp-pool/attribute.repository/myorg/myrepo"

5. Grant least-privilege target permissions

gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:gha-deploy@PROJECT_ID.iam.gserviceaccount.com" --role="roles/storage.objectAdmin"

6. Generate a credential configuration file

gcloud iam workload-identity-pools create-cred-config projects/123456789/locations/global/workloadIdentityPools/corp-pool/providers/github-provider --service-account="gha-deploy@PROJECT_ID.iam.gserviceaccount.com" --output-file="wif-cred.json" --credential-source-file="/var/run/secrets/oidc/token"

7. Use Application Default Credentials

Set GOOGLE_APPLICATION_CREDENTIALS=/path/to/wif-cred.json and call Google APIs normally from supported SDKs.

Code Examples

export GOOGLE_APPLICATION_CREDENTIALS="$PWD/wif-cred.json"
gcloud auth login --cred-file="$GOOGLE_APPLICATION_CREDENTIALS"
gcloud storage buckets list --project=PROJECT_ID

name: deploy
on:
  push:
    branches: [ main ]
permissions:
  id-token: write
  contents: read
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/corp-pool/providers/github-provider
          service_account: gha-deploy@PROJECT_ID.iam.gserviceaccount.com
      - uses: google-github-actions/setup-gcloud@v2
      - run: gcloud run services list --region=us-central1

from google.cloud import storage
client = storage.Client()
buckets = list(client.list_buckets())
for bucket in buckets:
    print(bucket.name)

Security Hardening

• Prefer attribute conditions over broad principal sets. Example: bind only attribute.repository/myorg/prod-repo instead of the whole pool.
• Use short-lived tokens only and disable service account key creation with org policy: constraints/iam.disableServiceAccountKeyCreation.
• Restrict audiences and issuer URIs to exact expected values.
• Separate providers by trust domain such as GitHub, AWS, and on-prem to reduce blast radius.
• Monitor Cloud Audit Logs for google.iam.credentials.v1.GenerateAccessToken and STS exchanges.
• Protect token sources on runners and nodes with OS hardening, encrypted disks, and minimal filesystem permissions.

Comparison

Troubleshooting

Error 1: invalid audience

Log sample:

ERROR: (gcloud.auth.login) invalid_grant: Error connecting to the given credential's issuer.
{"error":"invalid_target","error_description":"The audience in the credential does not match the provider."}

Fix: Verify --allowed-audiences on the provider and ensure the token aud claim matches exactly.

Error 2: permission denied on impersonation

Log sample:

PERMISSION_DENIED: Permission 'iam.serviceAccounts.getAccessToken' denied on resource 'projects/-/serviceAccounts/gha-deploy@PROJECT_ID.iam.gserviceaccount.com'

Fix: Add roles/iam.workloadIdentityUser on the target service account for the exact principalSet or principal identity.

Error 3: attribute mapping mismatch

Log sample:

google.api_core.exceptions.PermissionDenied: 403 Principal set does not match any identities bound to the service account.
assertion.repository=myorg/platform-infra assertion.ref=refs/heads/dev

Fix: Align IAM binding conditions with mapped attributes and repository branch claims.

Best Practices

Do

• Create one provider per external platform with explicit mappings.
• Bind to attributes, not entire pools, for example repository, branch, or AWS account ID.
• Use dedicated service accounts per application to isolate permissions.
• Test with gcloud auth login --cred-file before integrating into pipelines.

Don't

• Do not reuse one highly privileged service account across all pipelines.
• Do not allow wildcard trust for all repositories in a GitHub organization unless required.
• Do not keep fallback JSON keys in CI/CD secrets after federation is deployed.
• Do not skip audit review; validate token exchange and impersonation events in logs regularly.