--- cuppy_hub: gcp cuppy_path: reference/identity/workload-identity-federation.md cuppy_section: docs cuppy_doc: Y7CS-792Z cuppy_doc_uuid: 0f2bcc3e-1a4e-4c8a-9564-e16370d405cd cuppy_permalink: https://cuppy.io/gcp/d/Y7CS-792Z cuppy_version: 1 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/gcp/docs/reference/identity/workload-identity-federation cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: 526dce2ece79f6e1d08b1e60f29fec09ca0575ba9c951b734400dd000acc29d1 # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # 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/VALUE ``` `principal://` 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/SERVICEACCOUNT ``` The 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`. --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 91 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/gcp/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.