Workload Identity Federation in GCP Explained for Beginners
Workload Identity Federation is GCP’s solution for letting workloads outside Google Cloud authenticate without storing a service account key file anywhere. Instead of downloading a long-lived JSON credential and trusting everyone who might one day access it, you configure GCP to trust the identity that your CI/CD platform, cloud provider, or external system already issues for each run.
The problem it solves is real and common. When a GitHub Actions pipeline needs to deploy to Cloud Run, or a GitLab job needs to push an image to Artifact Registry, the pipeline needs some kind of credential. Before federation existed, the only option was a service account key file: a permanent, downloadable private key that never expires unless you manually revoke it. Federation replaces that with a token exchange. The external system proves who it is using its own token, GCP validates it, and issues short-lived access that expires automatically.
The result is keyless authentication. No file to download, no secret to rotate, no credential to accidentally commit to source control. If a token is ever exposed, it has already expired before anyone can use it.
Simple explanation
Think of it like a visitor pass system
Imagine two companies share an office building. Each company issues its own security badges to its own employees. When someone from Company A needs temporary access to Company B’s floor, they do not get a permanent Company B badge. They show their Company A badge at a reception desk, the desk verifies their identity, and issues a visitor pass that expires at the end of the day.
Workload Identity Federation works the same way. Your external workload (a GitHub Actions job, a GitLab pipeline, or an AWS service) already has its own identity issued by its own provider. GCP acts as the reception desk. It checks the incoming token, verifies the signature and the claims inside it, applies any conditions you have configured, and issues short-lived GCP credentials in return.
The key thing to understand is that this is designed for workloads outside GCP. If your workload is already running inside GCP (for example, a Cloud Run service or a GKE pod), there are simpler built-in options that do not require federation at all. More on that below.
Why Workload Identity Federation exists
Service account keys are one of the most common sources of credential exposure in GCP environments. They are JSON files containing an RSA private key tied to a service account. Once downloaded, that key is valid indefinitely until someone explicitly deletes it. You cannot tell at a glance who has a copy. You cannot set an expiry date. You cannot revoke access at a granular level without deleting the key entirely and updating anything that depends on it.
In practice, service account keys get stored as CI secrets, copied into Docker images, committed to Git repositories by accident, and forgotten in long-dead projects. The risk compounds over time. Read why service account keys are dangerous for the full picture.
A leaked service account key remains valid indefinitely. An attacker who finds one in a public repository, a Docker image layer, or a leaked backup has unrestricted time to use it. Federation tokens, by contrast, expire in under an hour and cannot be reused even if intercepted.
Federation eliminates all of that. The external system never receives a GCP key file. It receives a short-lived token scoped to a specific pipeline run that expires in under an hour. There is nothing to leak in a way that causes lasting damage.
How it works
The authentication flow has three stages. Each stage matters, and understanding it helps you configure federation correctly.
The external identity provider issues a signed token. Your CI platform or external system generates a short-lived token that describes the current workload. For GitHub Actions this is an OIDC token containing claims like the repository name, branch, workflow name, and run ID. OIDC (OpenID Connect) is the most common protocol, though SAML 2.0 is also supported. The token is cryptographically signed so GCP can verify it without contacting the provider again.
GCP validates the token against your provider configuration. Your Workload Identity Pool has a provider configured with the issuer URL for the external identity provider. GCP’s Security Token Service (STS) receives the token, fetches the provider’s public keys, verifies the signature, and checks the claims against any attribute mappings and attribute conditions you have defined. If anything fails, the exchange is rejected immediately.
GCP issues short-lived credentials via service account impersonation. If validation succeeds, GCP uses service account impersonation internally to issue temporary access tokens for the target service account. These credentials typically expire within one hour. The external workload uses them just like any other GCP credential, but they cannot be reused after expiry and are scoped to exactly the permissions on the target service account.
GCP never trusts the external token unconditionally. It validates the issuer, signature, claims, mappings, and conditions before issuing anything. Each of those is a layer of control you define at setup time. The more specific your conditions, the tighter the access.
When to use this
Workload Identity Federation is the right choice when you have a workload running outside GCP that needs to access GCP resources. Common scenarios include:
GitHub Actions deploying to Cloud Run or GKE. This is the most common use case. Federation lets your CI pipeline authenticate to GCP without storing a key file as a repository secret. See GitHub Actions for GCP for a full walkthrough.
GitLab CI/CD pipelines. GitLab issues OIDC tokens for pipeline jobs, which can be mapped to GCP identities using the same federation mechanism as GitHub Actions.
Workloads running in AWS or Azure that need GCP access. Federation supports AWS STS credentials and Azure AD workload identities as external providers, letting cross-cloud service communication happen without storing GCP keys in another cloud environment.
External Kubernetes clusters (not GKE). Kubernetes issues service account tokens that can be mapped through federation. This is distinct from Workload Identity for GKE, which handles GKE clusters directly using the metadata server.
Any OIDC-compatible identity provider. If an external system can issue a signed OIDC token, it can be configured as a federation provider. This includes custom identity systems and on-premises environments.
As a rule of thumb: if you would otherwise download a key file and store it as a secret in an external system, federation is almost certainly the better option.
When not to use this
Workload Identity Federation is not the right tool for workloads already running inside GCP. If your service is running as a Cloud Run instance, a GCE VM, an App Engine service, or a Cloud Function, it can already authenticate using its attached service account through the metadata server. No federation is needed and no key file is required.
For workloads running inside GKE specifically, Workload Identity for GKE is the purpose-built solution. It binds Kubernetes service accounts to GCP service accounts using GKE’s own metadata server integration. It is simpler to configure for in-cluster workloads and is the recommended approach for anything running inside a GKE cluster.
Using federation for in-GCP workloads when a simpler built-in mechanism exists adds unnecessary complexity without any security benefit. Pick the right tool for where your workload actually runs.
Workload Identity Federation vs Workload Identity for GKE
These two features have similar names and both eliminate service account key files, but they solve different problems for different environments. Confusing them is extremely common.
| Workload Identity Federation | Workload Identity for GKE | |
|---|---|---|
| Designed for | Workloads outside GCP (GitHub, GitLab, AWS, Azure, external K8s) | Pods running inside a GKE cluster |
| How it works | External token is exchanged via GCP Security Token Service | GKE metadata server handles credential issuance automatically |
| Setup complexity | Create pool, provider, attribute mappings, and IAM binding | Enable on cluster, annotate Kubernetes service account, bind IAM |
| Eliminates key files? | Yes | Yes |
| Works for CI/CD pipelines? | Yes, this is the primary use case | No, only for in-cluster workloads |
The short answer: use Workload Identity for GKE if your workload runs inside GKE. Use Workload Identity Federation for everything else that runs outside GCP.
Workload Identity Federation vs service account keys
Credential lifetime. Service account keys are permanent until deleted. Federation credentials expire in under an hour.
Secret storage burden. Key files must be stored securely in each external system that uses them. Federation requires no secret storage at all. The external system’s own token is the only credential involved in the exchange.
Blast radius. A leaked key file gives indefinite access until manually revoked. A leaked federation token becomes useless within the hour it expires, and is tied to specific claims that may not match an attacker’s context anyway.
Revocation. Revoking a key file requires tracking down every place it was distributed, deleting it, and updating all dependents. Federation tokens expire automatically. The pool or provider can be disabled immediately if something goes wrong.
Operational overhead. Key files require active rotation management, regular audit, and tracking across systems. Federation requires initial setup and has no ongoing key management burden.
Audit trail. Both leave Cloud Audit Log entries, but federation tokens carry richer context about the originating workload (repository name, branch, job ID). This makes post-incident investigation significantly easier.
Setup example: GitHub Actions
This walkthrough shows one concrete implementation of federation. GitHub Actions is the most common case, but the same three-step pattern applies to any supported provider. See GitHub Actions for GCP for a deeper walkthrough including Terraform configuration.
# Step 1: Create a Workload Identity Pool
# Pools group providers. Use one pool per environment (staging, production).
gcloud iam workload-identity-pools create github-pool \
--project=my-app-prod \
--location=global \
--display-name="GitHub Actions Pool"
# Step 2: Configure an OIDC provider pointing at GitHub's token endpoint
# The attribute-mapping exposes GitHub claims as GCP attributes.
# The attribute-condition restricts which repositories are trusted.
gcloud iam workload-identity-pools providers create-oidc github-provider \
--project=my-app-prod \
--location=global \
--workload-identity-pool=github-pool \
--display-name="GitHub Provider" \
--issuer-uri="https://token.actions.githubusercontent.com" \
--attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
--attribute-condition="assertion.repository=='my-org/my-app'"
# Step 3: Bind the federated identity to a service account
# The principalSet identifies which external identities can impersonate this SA.
PROJECT_NUMBER=$(gcloud projects describe my-app-prod --format='value(projectNumber)')
gcloud iam service-accounts add-iam-policy-binding \
ci-deployer@my-app-prod.iam.gserviceaccount.com \
--project=my-app-prod \
--role="roles/iam.workloadIdentityUser" \
--member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/github-pool/attribute.repository/my-org/my-app"The —attribute-condition in step 2 is not optional. Without
it, any GitHub Actions job in any repository (public or private) could
authenticate to your GCP project using this provider. The condition in
this example restricts to a specific repository. You can also restrict by
branch, environment, or organisation. Never skip this step.
Attribute mapping controls which claims from the GitHub
token become usable attributes in GCP. The mapping above exposes the
repository claim so it can be referenced in the condition. You can map
additional claims like assertion.ref (branch) or
assertion.environment (deployment environment) to restrict
access even further.
In your GitHub Actions workflow, add
permissions: id-token: write at the job level. This grants
the workflow permission to request an OIDC token from GitHub. Then call
the google-github-actions/auth action with your
workload_identity_provider and service_account
inputs. The action handles the token request and exchange automatically.
Subsequent steps in the workflow can use GCP tools without any additional
credential setup.
After confirming federation works, delete any existing service account keys that were used by the same workloads. An old key left in a CI secrets store continues to be a live credential even after you have set up federation. The migration is only complete when the key is gone.
Common mistakes
No attribute condition on the provider. An OIDC provider without an
—attribute-conditiontrusts any token from that issuer. For GitHub, that means every GitHub Actions job everywhere could authenticate to your project. Always restrict by repository at minimum. Ideally also restrict by branch or environment for production workloads.Overly broad IAM roles on the target service account. Federation removes the key file risk, but it does not remove the need for least privilege on the target service account. A deploy pipeline that pushes to Cloud Run needs
roles/run.developer, notroles/editororroles/owner. Review IAM roles to understand the right level of access for each use case.Leaving old key-based auth in place after migrating. After federation is configured, the old service account key still works until you delete it. The migration is not complete until the key is gone. An old key left in a CI secrets store is still a risk regardless of whether you have set up federation alongside it.
Sharing pools and providers across staging and production. Staging pipelines should not be able to authenticate to production resources even if misconfigured. Use separate pools and separate service accounts per environment. This limits blast radius if something goes wrong in a lower environment.
Trusting too many repositories or branches. A condition that allows all repositories in an organisation, or all branches in a repository, is much weaker than one tied to a specific repository and a protected branch. Think carefully about what the condition actually permits and whether a compromised fork or feature branch could satisfy it.
Treating federation as a replacement for IAM least privilege. Keyless auth is not the same as safe auth. A federated identity with
roles/editoron a project is still dangerous. Federation solves the credential storage problem. IAM policy controls what that credential can actually do. Both matter.
Security best practices
Restrict attribute conditions as tightly as practical. Repository, branch, and environment conditions can all be combined. The more specific the condition, the smaller the set of workloads that can successfully authenticate.
Use separate pools for separate environments. Staging, production, and any other isolated environment should each have their own Workload Identity Pool. This prevents a misconfiguration in one environment from affecting another. See secure CI/CD pipelines for more on environment separation strategy.
Grant least privilege to the service account being impersonated. The service account a federated identity impersonates should have only the permissions required for its specific job. Review these regularly and remove anything that is no longer needed.
Delete old service account keys after migration. Do not run key-based and federation-based auth in parallel any longer than necessary for testing. Once federation is confirmed working, remove the keys immediately.
Audit who can modify pool and provider configuration. The ability to change attribute conditions or add new providers to a pool is effectively the ability to grant GCP access to arbitrary external identities. Restrict this to a small set of trusted administrators.
Test denied conditions explicitly. Before going to production, verify that identities outside your allowed conditions are correctly rejected. A misconfigured provider that should deny access will not alert you unless you test the denial path directly.
Review Cloud Audit Logs for federation activity. Token exchange events are logged. Regular review of these logs helps catch unexpected authentication patterns early.
Summary
- Workload Identity Federation lets workloads outside GCP authenticate using short-lived tokens from their own identity provider. No service account key files involved.
- It solves the service account key problem: no file to download, store, rotate, or accidentally leak.
- Setup involves three steps: create a Workload Identity Pool, configure an OIDC or SAML provider, and bind the external identity to a service account with the workloadIdentityUser role.
- The attribute condition on the provider is critical. Omitting it means any token from that issuer is trusted without restriction.
- Use this for workloads outside GCP such as GitHub Actions, GitLab, AWS, and Azure. For GKE workloads, use Workload Identity for GKE instead.
- After migrating to federation, delete the old key files. Leaving them active defeats the security benefit entirely.
- Federation eliminates the key storage problem but does not replace least privilege on the service account being impersonated.
Frequently asked questions
What is Workload Identity Federation in GCP?
Workload Identity Federation lets external workloads authenticate to GCP without storing a service account key file anywhere. This includes GitHub Actions, GitLab CI/CD, and services running in AWS or Azure. The external system presents a short-lived token from its own identity provider. GCP validates that token and exchanges it for temporary GCP credentials scoped to a specific service account. No long-lived key is created or stored.
How is Workload Identity Federation different from Workload Identity for GKE?
Workload Identity Federation is for workloads running outside GCP, such as GitHub Actions, GitLab pipelines, or services on AWS. Workload Identity for GKE is a GKE-specific feature that lets Kubernetes service accounts authenticate as GCP service accounts using the GKE metadata server. Both eliminate service account key files, but they solve different problems for different environments.
Does Workload Identity Federation replace service account impersonation?
No. Service account impersonation is part of how federation works under the hood. After GCP validates the external token, it uses impersonation internally to issue short-lived credentials for the target service account. Federation is the mechanism that initiates the trust exchange; impersonation is one of the credential delivery mechanisms it relies on.
Can GitHub Actions use Workload Identity Federation?
Yes, and it is the recommended approach. GitHub Actions automatically issues a signed OIDC token for each workflow run. You configure a GCP Workload Identity Pool with a GitHub OIDC provider, add an attribute condition to restrict which repositories are trusted, and bind the federated identity to a service account with the workloadIdentityUser role. In your workflow you add permissions: id-token: write and use the google-github-actions/auth action to complete the exchange.
Is Workload Identity Federation more secure than service account keys?
Yes, significantly. Service account keys are long-lived JSON files that stay valid until explicitly deleted and can be leaked, cloned, or forgotten. Federation issues credentials that expire within an hour and are tied to a specific pipeline run. There is nothing to steal and store. The blast radius of any exposure is far smaller because the token is scoped, short-lived, and non-transferable.