Workload Identity Federation: OIDC-based Access for External Workloads

You just rotated a service account key for the third time this month, and a developer accidentally committed the new one to a public repo. Sound familiar? Static keys are a ticking time bomb—they leak, expire, and require manual rotation. Workload Identity Federation (WIF) with OIDC is the kill switch. It lets external workloads (GitHub Actions, GitLab CI, AWS Lambda) impersonate a Google Cloud service account using a short-lived token from an external identity provider. No keys, no secrets, no rotation. In this article, we'll build a production-grade OIDC federation from scratch, covering token exchange, attribute mapping, and the gotchas that will bite you in production.

Why Static Keys Are a Security Anti-Pattern

Service account keys are long-lived secrets that grant powerful access to Google Cloud resources. They're often stored in CI/CD secrets, config files, or worse—committed to source control. A single leaked key can lead to data exfiltration, resource hijacking, or a massive cloud bill. Even with rotation policies, keys remain valid for hours or days, giving attackers a wide window. Workload Identity Federation replaces these static keys with ephemeral tokens that expire in minutes. The external workload presents an OIDC token from its identity provider (e.g., GitHub's OIDC issuer), and Google Cloud exchanges it for a short-lived access token. No secrets to manage, no rotation to schedule. This is the gold standard for cross-cloud and CI/CD access.

#!/bin/bash
# List all service account keys and their last used time
# Requires gcloud and jq
for sa in $(gcloud iam service-accounts list --format='value(email)'); do
  echo "Service Account: $sa"
  gcloud iam service-accounts keys list --iam-account="$sa" --format='json' | jq -r '.[] | "Key: \(.name) | Valid After: \(.validAfterTime) | Valid Before: \(.validBeforeTime)"'
done

OIDC Token Exchange: The Core Mechanism

Workload Identity Federation relies on the OIDC token exchange flow defined in RFC 8693. The external workload obtains an OIDC token from its identity provider (e.g., GitHub, GitLab, AWS STS). This token contains claims like sub, aud, and issuer. The workload then calls the Google Cloud Security Token Service (STS) endpoint https://sts.googleapis.com/v1/token to exchange the OIDC token for a Google Cloud access token. The STS validates the token against a workload identity pool and provider, applies attribute mappings, and returns a short-lived access token (typically 1 hour). The workload can then use this token to call Google Cloud APIs. The entire exchange happens without any static secrets—just the OIDC token itself.

#!/bin/bash
# Exchange GitHub OIDC token for GCP access token
# Requires: jq, curl, and GITHUB_TOKEN env var (OIDC token from GitHub Actions)

OIDC_TOKEN=${GITHUB_TOKEN}
STS_URL="https://sts.googleapis.com/v1/token"
POOL_PROVIDER="projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider"

RESPONSE=$(curl -s -X POST "$STS_URL" \
  -H "Content-Type: application/json" \
  -d "{
    \"grantType\": \"urn:ietf:params:oauth:grant-type:token-exchange\",
    \"subjectTokenType\": \"urn:ietf:params:oauth:token-type:jwt\",
    \"requestedTokenType\": \"urn:ietf:params:oauth:token-type:access_token\",
    \"audience\": \"//iam.googleapis.com/$POOL_PROVIDER\",
    \"scope\": \"https://www.googleapis.com/auth/cloud-platform\",
    \"subjectToken\": \"$OIDC_TOKEN\"
  }")

ACCESS_TOKEN=$(echo $RESPONSE | jq -r '.access_token')
echo "Access Token: $ACCESS_TOKEN"

Setting Up a Workload Identity Pool and Provider

A workload identity pool is a logical grouping of external identities. Within each pool, you define providers that map to specific OIDC issuers (e.g., https://token.actions.githubusercontent.com for GitHub Actions). The provider configuration includes attribute mappings that extract claims from the OIDC token and map them to Google Cloud attributes like google.subject and attribute.repository. These attributes are used in IAM policies to grant fine-grained access. For example, you can allow only workflows from a specific repository to impersonate a service account. The setup involves creating the pool, adding the provider, and configuring attribute conditions.

#!/bin/bash
# Create workload identity pool and GitHub provider
# Requires gcloud with appropriate permissions

PROJECT_ID="my-project"
POOL_ID="github-pool"
PROVIDER_ID="github-provider"

# Create pool
gcloud iam workload-identity-pools create "$POOL_ID" \
  --project="$PROJECT_ID" \
  --location="global" \
  --display-name="GitHub Actions Pool"

# Create provider
gcloud iam workload-identity-pools providers create-oidc "$PROVIDER_ID" \
  --project="$PROJECT_ID" \
  --location="global" \
  --workload-identity-pool="$POOL_ID" \
  --display-name="GitHub Actions Provider" \
  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository,attribute.ref=assertion.ref" \
  --attribute-condition="assertion.repository_owner == 'my-org'" \
  --issuer-uri="https://token.actions.githubusercontent.com"

Granting IAM Permissions to External Identities

Once the pool and provider are set up, you grant IAM roles to the external identities using the principal identifier principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.repository/REPO. This binds the external identity to a service account via the roles/iam.workloadIdentityUser role. The service account then has its own IAM roles (e.g., roles/storage.objectAdmin). The external workload impersonates the service account, inheriting its permissions. This two-step delegation ensures that the external identity never directly holds GCP roles—only the service account does.

#!/bin/bash
# Grant workload identity user role to a GitHub repository
# Requires: PROJECT_NUMBER, POOL_ID, REPO (e.g., my-org/my-repo)

PROJECT_NUMBER="123456789"
POOL_ID="github-pool"
REPO="my-org/my-repo"
SERVICE_ACCOUNT="ci-deploy@my-project.iam.gserviceaccount.com"

PRINCIPAL="principalSet://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/attribute.repository/$REPO"

gcloud iam service-accounts add-iam-policy-binding "$SERVICE_ACCOUNT" \
  --project="my-project" \
  --role="roles/iam.workloadIdentityUser" \
  --member="$PRINCIPAL"

Configuring GitHub Actions for OIDC Federation

To use WIF from GitHub Actions, you need to configure the workflow to request an OIDC token from GitHub and exchange it for GCP credentials. The google-github-actions/auth action handles the token exchange automatically. You must set permissions: id-token: write in the workflow to allow the job to request the OIDC token. The action uses the workload identity provider and service account you configured. No secrets are stored—the OIDC token is generated by GitHub and validated by GCP.

name: Deploy to GCP
on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - id: auth
        name: Authenticate to GCP
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider'
          service_account: 'ci-deploy@my-project.iam.gserviceaccount.com'

      - name: Set up Cloud SDK
        uses: google-github-actions/setup-gcloud@v2

      - name: Deploy to Cloud Run
        run: gcloud run deploy my-service --image gcr.io/my-project/my-image --region us-central1

Attribute Mapping and Conditions: Fine-Grained Access Control

Attribute mappings translate OIDC claims into Google Cloud attributes. For example, attribute.repository=assertion.repository maps the GitHub repository to a custom attribute. You can then use attribute conditions to restrict access based on these attributes. Conditions are CEL (Common Expression Language) expressions evaluated against the OIDC token claims. For instance, assertion.ref == 'refs/heads/main' ensures only pushes to main branch can impersonate the service account. This enables environment-specific access without managing multiple pools.

#!/bin/bash
# Update provider with attribute condition for main branch only

gcloud iam workload-identity-pools providers update-oidc "github-provider" \
  --project="my-project" \
  --location="global" \
  --workload-identity-pool="github-pool" \
  --attribute-condition="assertion.ref == 'refs/heads/main' && assertion.repository_owner == 'my-org'"

Auditing and Monitoring OIDC Token Exchanges

Every OIDC token exchange is logged in Cloud Audit Logs under the sts.googleapis.com service. You can view who exchanged a token, which pool and provider were used, and the resulting access token's scope. This is critical for security incident response. Set up log-based metrics and alerts for failed exchanges (e.g., invalid token, expired token, or attribute condition mismatch). Additionally, monitor the iam.googleapis.com/impersonation logs to see which service account was impersonated and by which external identity.

#!/bin/bash
# Query audit logs for STS token exchanges in the last hour

gcloud logging read 'resource.type=sts_service AND protoPayload.methodName="google.identity.sts.v1.TokenService.ExchangeToken"' \
  --project=my-project \
  --freshness=1h \
  --format=json | jq '.[].protoPayload | {caller: .authenticationInfo.principalEmail, method: .methodName, status: .status}'

Handling Token Expiry and Refresh

The access token obtained from STS is valid for 1 hour by default. For long-running jobs, you need to refresh the token before it expires. The google-github-actions/auth action handles this automatically by caching the token and refreshing it when needed. For custom scripts, you can implement a refresh loop that calls the STS endpoint again with a new OIDC token. Note that the OIDC token itself is short-lived (typically 5-10 minutes for GitHub Actions), so you must request a new one if the job runs longer. In GitHub Actions, the OIDC token is available only during the job; for longer runs, consider splitting into multiple jobs.

import os
import requests
import time

def get_access_token(oidc_token, pool_provider):
    sts_url = "https://sts.googleapis.com/v1/token"
    payload = {
        "grantType": "urn:ietf:params:oauth:grant-type:token-exchange",
        "subjectTokenType": "urn:ietf:params:oauth:token-type:jwt",
        "requestedTokenType": "urn:ietf:params:oauth:token-type:access_token",
        "audience": f"//iam.googleapis.com/{pool_provider}",
        "scope": "https://www.googleapis.com/auth/cloud-platform",
        "subjectToken": oidc_token
    }
    resp = requests.post(sts_url, json=payload)
    resp.raise_for_status()
    return resp.json()["access_token"], resp.json()["expires_in"]

# Usage in a long-running job
pool_provider = "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider"
oidc_token = os.environ["ACTIONS_ID_TOKEN_REQUEST_TOKEN"]
token, expires_in = get_access_token(oidc_token, pool_provider)
print(f"Token expires in {expires_in} seconds")
# Refresh after 50 minutes
while True:
    time.sleep(3000)  # 50 minutes
    oidc_token = os.environ["ACTIONS_ID_TOKEN_REQUEST_TOKEN"]  # May need to re-fetch
    token, _ = get_access_token(oidc_token, pool_provider)

Troubleshooting Common OIDC Federation Issues

Common issues include: (1) OIDC token not having the correct aud claim—ensure your workflow sets audience in the auth action. (2) Attribute condition mismatch—test conditions with gcloud iam workload-identity-pools providers test-iam-conditions. (3) Service account not having roles/iam.workloadIdentityUser—verify the IAM binding. (4) Token expired—check the OIDC token expiry (GitHub tokens last 5 minutes). (5) Wrong pool provider audience—ensure the audience matches exactly. Use the gcloud auth print-access-token command to test the exchange manually.

#!/bin/bash
# Test OIDC token exchange manually
# Requires a valid OIDC token in OIDC_TOKEN env var

POOL_PROVIDER="projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider"
STS_URL="https://sts.googleapis.com/v1/token"

curl -s -X POST "$STS_URL" \
  -H "Content-Type: application/json" \
  -d "{
    \"grantType\": \"urn:ietf:params:oauth:grant-type:token-exchange\",
    \"subjectTokenType\": \"urn:ietf:params:oauth:token-type:jwt\",
    \"requestedTokenType\": \"urn:ietf:params:oauth:token-type:access_token\",
    \"audience\": \"//iam.googleapis.com/$POOL_PROVIDER\",
    \"scope\": \"https://www.googleapis.com/auth/cloud-platform\",
    \"subjectToken\": \"$OIDC_TOKEN\"
  }" | jq .

Migrating from Service Account Keys to OIDC Federation

Migrating existing workflows from static keys to OIDC federation involves: (1) Creating the workload identity pool and provider. (2) Granting the roles/iam.workloadIdentityUser role to the external identity. (3) Updating CI/CD configuration to use the auth action instead of gcloud auth activate-service-account --key-file. (4) Removing the key file from secrets. (5) Rotating and deleting the old service account key. Test the migration with a non-production workflow first. Monitor audit logs to ensure no workflows are still using the old key.

name: Migrate to WIF
on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Old method (remove after migration)
      # - id: auth-old
      #   uses: google-github-actions/auth@v2
      #   with:
      #     credentials_json: ${{ secrets.GCP_SA_KEY }}

      # New method
      - id: auth
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider'
          service_account: 'ci-deploy@my-project.iam.gserviceaccount.com'

      - name: Deploy
        run: gcloud run deploy my-service --image gcr.io/my-project/my-image --region us-central1

Advanced: Custom OIDC Providers (e.g., AWS, GitLab, Custom IdP)

Workload Identity Federation supports any OIDC-compliant identity provider. For AWS, you can use the AWS STS GetCallerIdentity endpoint to obtain an OIDC token. For GitLab, the issuer is https://gitlab.com. For custom IdPs, you need to provide the issuer URI and configure attribute mappings accordingly. The setup is similar to GitHub: create a pool, add a provider with the issuer URI, and map claims. The key difference is the token format and claims available. Always validate the iss and aud claims in the provider configuration.

#!/bin/bash
# Create AWS workload identity provider
# Requires AWS CLI and gcloud

POOL_ID="aws-pool"
PROVIDER_ID="aws-provider"

gcloud iam workload-identity-pools create "$POOL_ID" \
  --project="my-project" \
  --location="global" \
  --display-name="AWS Pool"

gcloud iam workload-identity-pools providers create-oidc "$PROVIDER_ID" \
  --project="my-project" \
  --location="global" \
  --workload-identity-pool="$POOL_ID" \
  --display-name="AWS Provider" \
  --attribute-mapping="google.subject=assertion.sub,attribute.role=assertion.arn" \
  --attribute-condition="assertion.arn.startsWith('arn:aws:sts::123456789012:assumed-role/my-role')" \
  --issuer-uri="https://sts.amazonaws.com"

Production Best Practices and Gotchas

1. Least privilege: Grant only the roles needed. Use separate service accounts for different workloads. 2. Attribute conditions: Always restrict by repository and branch. 3. Audit: Enable audit logs and set up alerts for failed exchanges. 4. Token lifetime: Set the STS token lifetime to the minimum required (e.g., 30 minutes). 5. Provider hardening: Use attribute-condition to validate iss and aud claims. 6. Key deletion: After migration, delete all service account keys. 7. Testing: Use gcloud iam workload-identity-pools providers test-iam-conditions to validate conditions. 8. Monitoring: Monitor for iam.googleapis.com/impersonation logs to detect unusual impersonation patterns.

#!/bin/bash
# Delete all user-managed keys for a service account
# Use with caution!

SA_EMAIL="ci-deploy@my-project.iam.gserviceaccount.com"
KEYS=$(gcloud iam service-accounts keys list --iam-account="$SA_EMAIL" --format='value(name)' --managed-by-user)
for key in $KEYS; do
  gcloud iam service-accounts keys delete "$key" --iam-account="$SA_EMAIL" --quiet
done

GKE Workload Identity vs External WIF: Don't Confuse Them

There are two distinct Workload Identity Federation features in GCP—and confusing them causes real problems. External WIF (what this article covers) is for workloads outside GCP: GitHub Actions, GitLab CI, AWS Lambda, Azure VMs. It uses google_iam_workload_identity_pool and google_iam_workload_identity_pool_provider Terraform resources. GKE Workload Identity is a separate feature that lets Kubernetes service accounts (KSAs) in GKE clusters impersonate Google service accounts. It uses an automatically managed pool at PROJECT_ID.svc.id.goog. The mechanisms differ: GKE WIF uses the cluster's metadata server, external WIF uses the STS API. You can use both in the same project for different use cases. Production insight: we once had an engineer spend two days debugging an external WIF setup that was actually a GKE cluster—they were using the wrong pool type. The pool in GKE is automatic; external pools are manually created. Know which one you need.

External WIF (this guide):
  - For: GitHub Actions, GitLab, AWS, Azure, on-prem
  - Pool: Manual (google_iam_workload_identity_pool)
  - Provider: OIDC or SAML
  - Uses: STS API (sts.googleapis.com)
  - Cost: Free

GKE Workload Identity:
  - For: GKE clusters only
  - Pool: Automatic (PROJECT_ID.svc.id.goog)
  - Provider: Built-in GKE provider
  - Uses: GKE metadata server
  - Cost: Free

Do not mix them up. They use different Terraform resources and configuration steps.

Cost: Workload Identity Federation Is Free

Workload Identity Federation itself incurs no additional cost. There is no charge for creating workload identity pools, providers, or performing token exchanges via the STS API. You only pay for the Google Cloud APIs and services that the federated identity calls. This makes WIF a strictly better choice than service account keys from a cost perspective—keys have no direct cost either, but the operational overhead of rotation, auditing, and breach remediation is significant. Production insight: the only cost consideration is the additional Cloud Audit Log volume from STS token exchanges, which is negligible for most workloads. At scale (millions of exchanges per day), you might see a small increase in logging costs. But this is far outweighed by the security benefits.

Workload Identity Federation:
  - Pool creation: Free
  - Provider creation: Free
  - Token exchanges (STS): Free
  - Audit logging: Standard Cloud Logging costs apply
  - Total: $0 additional

Service Account Keys:
  - Key creation: Free
  - Key rotation: Operational cost
  - Key breach remediation: Potentially very expensive
  - Security audit: Ongoing compliance cost
  - Total: Indirect costs can be significant

Cross-Project Access with WIF

A workload identity pool in project A can grant access to resources in project B. The IAM binding is on the target resource (or project), not on the pool. For example, a GitHub Actions workflow authenticates to project A's pool, gets a token, and can access Cloud Storage in project B if the service account has the necessary IAM roles in project B. This enables centralized identity management across multiple projects. The pool is tied to the project where it's created, but the federated identity can be granted access anywhere in the organization. Production insight: use a dedicated 'identity project' for your workload identity pools. Grant the federated identities access to resource projects via cross-project IAM bindings. This keeps identity management centralized and resource access decentralized.

# Grant access to a service account in project B
# The pool is in project A, but the SA is in project B

gcloud iam service-accounts add-iam-policy-binding \
  sa-in-project-b@project-b.iam.gserviceaccount.com \
  --project=project-b \
  --role=roles/iam.workloadIdentityUser \
  --member="principalSet://iam.googleapis.com/projects/PROJECT_A_NUMBER/locations/global/workloadIdentityPools/github-pool/attribute.repository/my-org/my-repo"