Workload Identity Federation — pools, providers, principal strings, direct resource access, and the GKE form
The keyless path onto Google Cloud from outside it and from inside a GKE cluster. The two objects you create, the two protocols, the resource-name and principal-string formats, the choice between direct resource access and impersonation, the GKE pool name shape, and the limitation the vendor states.
markdownreferencev1Y7CS-792Zstage: buildtrust: officialfamily: identityservice: iaminterface: cliworkload identity federationworkload identity poolworkload identity pool providerOIDCSAMLprincipal://principalSet://direct resource accessPROJECT_ID.svc.id.googSecurity Token Service
Workload Identity Federation
1. What it replaces
An external workload — a CI runner, another cloud, an on-premises job — proves its own identity to Google Cloud and receives Google credentials in exchange. The point is that no service account key leaves Google Cloud, which is the alternative the service-account overview calls a security risk.
2. Two objects, and nothing else to create
| Object | What it holds |
|---|---|
| workload identity pool | the namespace. Resource name: projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID — note **project number**, not project id |
| workload identity pool provider | the trust: the external issuer, the attribute mapping, and the attribute condition |
Supported protocols, verbatim: "OpenID Connect (OIDC) or Security Assertion Markup Language (SAML) V2.0".
The exchange runs through the Security Token Service, which returns a federated access token. *The federation page states no lifetime for that token.* The IAM quotas page's related fixed limit is a maximum access token lifetime of 3,600 seconds, extendable to 12 hours by an organization policy — recorded here because an agent planning a long job needs the number and the page that owns it.
3. Direct resource access, or impersonation — pick deliberately
Both are supported and the federation page presents direct resource access as the recommended path:
bind the federated principal straight onto the resource's allow policy, with no service account in the middle.
Impersonation — the federated principal holding roles/iam.workloadIdentityUser on a service account — is the
alternative, and it is still what you want when something downstream can only be reached by a service account
(an attached identity, a database IAM user, a tool that takes only an account address).
The estimate consequence, which matters for migration work: direct resource access means one fewer object per workload, and impersonation means one service account per workload plus a binding on it.
4. The principal strings
Two shapes, and using the wrong one is a silent no-op rather than an error:
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/.../attribute.ATTRIBUTE_NAME/VALUEprincipal:// names exactly one external identity by its mapped subject. principalSet:// names every
identity whose mapped attribute has that value — one binding for every workflow in a repository, for example.
5. The GKE form
Workload Identity Federation for GKE "lets you use IAM policies to grant Kubernetes workloads in your GKE cluster access to specific Google Cloud APIs" without key files. Two shapes to know:
- the cluster's pool is named
PROJECT_ID.svc.id.goog— the only pool id that is not an id you chose; - a Kubernetes ServiceAccount is named to IAM as
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/SERVICEACCOUNTThe page also documents the ServiceAccount annotation iam.gke.io/return-principal-id-as-email: "true" as an
alternative route. The page does not say whether the feature is on by default on Autopilot clusters — that
claim is not made here; check the cluster-modes page (reference/compute/gke-cluster-modes.md) and the
cluster's own configuration.
6. The limitation the vendor states, verbatim
"Although most Google Cloud APIs support Workload Identity Federation, some APIs have limitations."
So a federation design is not finished until the specific API the workload calls has been checked. This is the single most common reason a keyless design is abandoned halfway and a key is reintroduced.
Next: the worked setup in guides/identity/github-actions-without-keys.md; the cross-cloud equivalents
(AWS IAM Roles Anywhere / OIDC roles, Microsoft Entra workload identity federation) in
guides/parity/identity.md.