Service Accounts, Impersonation, and Workload Identity Federation

A service account is a non-human identity that applications, VMs and pipelines use to authenticate to Google Cloud APIs. It is a principal like any other (you bind roles to it with serviceAccount:EMAIL members), but it belongs to a project, is identified by an email address and never signs in with a password. Three kinds appear in projects, and you need to tell them apart.

Google-managed service accounts (service agents) let Google services act on resources in your project. Their email usually has the form service-PROJECT_NUMBER@gcp-sa-SERVICE.iam.gserviceaccount.com (for example gcp-sa-pubsub for Pub/Sub); a few older services use their own domains, such as the Cloud Storage service agent service-PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com. Google creates them as you enable and use services, you never hold their credentials, and they appear on your project's IAM page holding a service agent role. Seeing one that nobody on your team created is normal.

Default service accounts are created in your project when you enable certain services: the Compute Engine default service account (PROJECT_NUMBER-compute@developer.gserviceaccount.com), which VMs and, unless you choose otherwise, Cloud Run services run as; and the App Engine default service account (PROJECT_ID@appspot.gserviceaccount.com). They live in your project and you can change their grants, but historically they were automatically granted the project-wide Editor role. Attached by default and broadly privileged is exactly what least privilege forbids, so do not use them for real workloads (the organization policy that now stops that Editor grant is covered below).

User-managed service accounts are the ones you create deliberately, one per workload, with an email of the form ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com. You decide their roles, which resources carry them and who may act as them.

A service agent needs IAM roles on the resources a Google service touches on your behalf, and sometimes you must grant them yourself. When Google creates an agent automatically as a service is enabled, it normally also grants that agent its service agent role on the project. Some features, though, need the agent to reach a resource that the default role does not cover.

The classic case is customer-managed encryption keys (CMEK). When you set a Cloud KMS key as a Cloud Storage bucket's default key, it is the Cloud Storage service agent of the bucket's project, not you, that encrypts and decrypts objects with the key. That agent therefore needs roles/cloudkms.cryptoKeyEncrypterDecrypter on the key; without it, writes and reads that use the key fail with a permission error, however many roles you hold yourself. Grant the combined Encrypter/Decrypter role because the service must do both: roles/cloudkms.cryptoKeyDecrypter alone cannot write new objects and roles/cloudkms.cryptoKeyEncrypter alone cannot read them back. gcloud storage service-agent --project=PROJECT_ID prints the agent's address.

You can also create a service agent before first use, for example in automation that must grant it access before the service runs: gcloud workload-identity service-agents generate (older material uses gcloud beta services identity create --service=SERVICE). Agents created at your request are not granted any roles automatically, so you must grant the roles the service's documentation lists for its agent; otherwise the service fails with permission errors that do not occur in projects where Google created the agent itself.

Create a service account with gcloud iam service-accounts create app-backend --display-name="Backend API" in the target project; the account ID becomes the email prefix, so the account is app-backend@PROJECT_ID.iam.gserviceaccount.com. List accounts with gcloud iam service-accounts list.

Granting the account access works exactly like granting a user: bind a role with the service account as the member. gcloud projects add-iam-policy-binding PROJECT_ID --member=serviceAccount:app-backend@PROJECT_ID.iam.gserviceaccount.com --role=roles/pubsub.publisher lets the workload publish to Pub/Sub topics in the project. Least privilege is stricter in practice for workloads because their needs are predictable: an application that publishes to one topic and writes to one bucket needs roles/pubsub.publisher and roles/storage.objectCreator, bound on that topic and that bucket rather than the project where the service supports resource-level policies. Never give a workload Editor because listing its needs feels tedious; that list is the security work.

Plan for one service account per workload, not one shared account. Separate accounts keep the blast radius small, make Cloud Audit Logs attributable to the right application, and let you revoke one workload's access without touching the others. A scenario where several applications share one powerful account is describing the problem; splitting it per workload is the fix.

Using an account in another project. A service account is a principal anywhere in the organization: to let it read a bucket in project B, grant it a role on that bucket in project B; nothing changes in its home project. Attaching an account to a resource in another project (a VM in one project running as an account that lives in a central identity project) is different: it needs Service Account User on the account and is blocked when the organization policy constraints/iam.disableCrossProjectServiceAccountUsage is enforced on the service account's project. Google enforces that constraint by default, which is why cross-project attachment fails out of the box; teams that centralise workload identities in one project must stop enforcing it there. Some services also need their service agent in the resource's project (for example the Compute Engine service agent) to hold Token Creator on the account.

Disable before you delete. gcloud iam service-accounts disable EMAIL stops the account authenticating but keeps its identity and role bindings, and gcloud iam service-accounts enable EMAIL reverses it instantly. That makes disabling the safe first step when retiring an account: if something breaks, you re-enable it.

Deletion (gcloud iam service-accounts delete EMAIL) is harder to undo. A deleted account can be undeleted within 30 days with gcloud beta iam service-accounts undelete ACCOUNT_UNIQUE_ID, using the account's numeric unique ID (the email no longer resolves; find the ID in the audit log entry for the deletion). Undeleting restores the same identity, and its existing role bindings work again. Undelete is not possible once 30 days have passed. While a new account with the same name exists, it also blocks undeleting the original; delete the new account first, then undelete.

Do not try to "recreate" a deleted account under the same name. IAM bindings refer to the account's unique ID, so a new account with the same email is a different identity: it inherits none of the old roles (the old bindings show as deleted:serviceAccount:...), and while it exists it blocks undeleting the original until you delete it.

Attaching a service account to a resource gives the code running there credentials without any secret in your code. The attached account becomes the resource's identity: Google issues short-lived access tokens for it on demand, client libraries pick them up through Application Default Credentials, and nothing sensitive is written to disk. To attach an account, the caller needs roles/iam.serviceAccountUser on that account as well as permission to create the resource.

Compute Engine. Attach at creation with gcloud compute instances create web-1 --service-account=app-backend@PROJECT_ID.iam.gserviceaccount.com --scopes=cloud-platform. To change the attached account or the scopes of an existing VM, stop the VM, then run gcloud compute instances set-service-account web-1 --service-account=EMAIL --scopes=cloud-platform, then start it.

Access scopes are a legacy, per-VM limit on what the VM's tokens may be used for; effective access is the intersection of the scopes and the account's IAM roles. The default scopes allow read-only Cloud Storage, Logging write, Monitoring write, Service Control, Service Management read-only and Trace append, and nothing else (no Pub/Sub, no Storage writes). If you run gcloud compute instances create without --scopes, it applies these defaults, even when you pass a user-managed --service-account; the console, by contrast, selects the full cloud-platform scope when you pick a user-managed account. Two different errors follow from this:

• An insufficient authentication scopes error means the token's scopes do not cover the API. Granting more IAM roles will not help; change the scopes (stop the VM, set-service-account --scopes).
• A permission denied error with a missing IAM permission means the account lacks a role; grant the role.

Google's recommended pattern is to give VMs a dedicated service account with the cloud-platform scope and let IAM roles be the only place access is decided.

Cloud Run. Set the service identity at deploy time with gcloud run deploy my-service --image=IMAGE --service-account=app-backend@PROJECT_ID.iam.gserviceaccount.com. If you omit --service-account, the service runs as the Compute Engine default service account, which in older projects holds Editor, so an unexpectedly over-privileged Cloud Run service usually traces back to a missing --service-account. Whoever deploys also acts as the runtime identity, so the deployer (a person or a CI/CD pipeline's own service account) needs roles/iam.serviceAccountUser on the runtime account in addition to its Cloud Run role. The deploying identity and the runtime identity are two different accounts with two different jobs.

GKE. Do not give your application's powers to the node service account: it is shared by every pod on the node. Per-workload identity on GKE uses Workload Identity Federation for GKE, covered below.

A service account is both a principal and a resource. As a principal it appears as a serviceAccount: member in other resources' policies; that is what the account can do. As a resource it has its own IAM policy saying who can use, impersonate or administer it; that is what can be done to the account. View that policy with gcloud iam service-accounts get-iam-policy EMAIL and edit it with gcloud iam service-accounts add-iam-policy-binding EMAIL --member=user:alice@example.com --role=roles/iam.serviceAccountUser.

Note that Key Admin can create keys, and a key is a credential: a Key Admin can mint a key and authenticate as the account unless constraints/iam.disableServiceAccountKeyCreation is enforced. Grant it as rarely as Token Creator.

These roles follow normal IAM inheritance: granted on one service account they cover that account; granted on the project they cover every service account in it. That makes project-level grants an escalation path. Anyone who can create a resource and holds Service Account User on the whole project can attach any account in it, including the most privileged one, and then use that account's access from inside the resource. The same applies to Token Creator, and to delegation chains, where a low-privilege account that may impersonate a higher-privilege one gains its access for that step. The rule: grant these roles on the specific accounts a person or pipeline genuinely needs, never on the project, and review who holds them on highly privileged accounts. Whoever can act as an identity effectively holds that identity's access.

A service account key is a downloadable JSON credential containing a private key that authenticates as the account from anywhere, so it is the option of last resort. Keys are long-lived: a user-managed key has no expiry by default and stays valid until it is disabled or deleted. They are bearer credentials: anyone holding the file is the service account, from any machine. They leak easily through repositories, container images and CI logs. And use by a thief looks the same as legitimate use.

If you must create one, typically for third-party software that only accepts a key file, use gcloud iam service-accounts keys create key.json --iam-account=EMAIL; audit with keys list; revoke with keys disable or keys delete. Deleting a leaked key invalidates it immediately. Rotation means creating a new key, moving the consumer to it, then deleting the old one.

Organization policies enforce avoidance instead of trusting discipline:

• constraints/iam.disableServiceAccountKeyCreation blocks creating keys.
• constraints/iam.disableServiceAccountKeyUpload blocks uploading your own public keys to service accounts.
• constraints/iam.serviceAccountKeyExpiryHours gives keys a fixed lifetime counted from creation. It applies only to keys created after it is enforced (existing keys keep no expiry), and it is not an inactivity timeout.
• constraints/iam.serviceAccountKeyExposureResponse controls what happens when Google detects a key exposed publicly, for example pushed to a public repository. Since 16 June 2024, if you have not set it, Google disables the exposed key and notifies you, so a job using it starts failing with an authentication error. The response is to move the workload to a keyless method (or, if unavoidable, a new key) and investigate how it leaked.

Organizations created on or after 3 May 2024 are secure by default: key creation and key upload are blocked, and constraints/iam.automaticIamGrantsForDefaultServiceAccounts is enforced, so default service accounts are no longer automatically granted Editor. In such an organization, a VM created with every default runs as a default account with no project role, which is why reads that worked in an older organization fail with 403 there; grant a dedicated account the specific roles it needs. Older organizations can enforce the same constraints themselves.

The decision rule: workloads on Google Cloud use attached service accounts; humans and automation with a Google identity use impersonation; GKE pods use Workload Identity Federation for GKE; external workloads use Workload Identity Federation. A key is justified only when none of those paths exist.

Service account impersonation lets an authenticated principal obtain short-lived credentials as a service account without any key. The authorisation is split in two. The caller needs roles/iam.serviceAccountTokenCreator on the target account. The service account, not the caller, needs the roles on the resources being changed. So a team can run infrastructure tooling through a deployer service account while its members hold no direct permissions on the target project: the team's group gets Token Creator on the deployer account, and the deployer account gets the resource roles. If either half is missing, the call fails.

In gcloud, --impersonate-service-account=EMAIL runs one command as the account, and gcloud config set auth/impersonate_service_account EMAIL makes every following command use it until you unset it. Client libraries support impersonated credentials too.

The Service Account Credentials API issues three kinds of short-lived credential:

A private Cloud Run service checks that the identity in the ID token holds Cloud Run Invoker (roles/run.invoker). An ID token for your own user is rejected if your user lacks that role; when only a service account holds it, mint the ID token as that account with impersonation, which needs Token Creator on it. An access token is the wrong credential here, because it is meant for Google APIs, not for proving identity to your service.

Lifetimes. Access tokens last one hour by default, and one hour is also the maximum unless the organization policy constraints/iam.allowServiceAccountCredentialLifetimeExtension lists the service account; listed accounts can get access tokens of up to 12 hours (43,200 seconds). Short-lived credentials are not revoked like keys; they simply expire, so a stolen token is useful for minutes or hours, not months.

Why this replaces keys: instead of giving five engineers a JSON key each, grant their group Token Creator on the deployer account. They authenticate as themselves, mint hour-long tokens on demand, Cloud Audit Logs attribute every action to the human who impersonated, and offboarding is a group-membership change.

Workload Identity Federation for GKE (formerly called simply Workload Identity) is Google's recommended way for GKE applications to get Google Cloud credentials without keys. Each pod runs as a Kubernetes service account (KSA), and GKE exchanges that KSA's token for short-lived Google Cloud credentials. The node's service account is shared by every pod on the node, and key files in pods bring back every key risk, so both are the wrong answer.

Enable it. Autopilot clusters always have it. On Standard, enable it on the cluster with gcloud container clusters update CLUSTER --workload-pool=PROJECT_ID.svc.id.goog, which gives the cluster the project's workload identity pool. Existing node pools are not converted: update each one with gcloud container node-pools update POOL --cluster=CLUSTER --workload-metadata=GKE_METADATA (new node pools get it automatically). Until you do, pods on the old pool keep calling Google APIs as the node's service account.

Grant access: the recommended method. Grant IAM roles directly to the KSA's principal identifier:

principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME

Note the two different project identifiers: the projects/ segment takes the project number, while the pool name is the project ID followed by .svc.id.goog. No Google service account is involved.

Alternative: link to an IAM service account. Where a Google Cloud API does not yet accept federated principals, or you want to reuse an existing service account, create an IAM service account with the roles, grant roles/iam.workloadIdentityUser on it to serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME], and annotate the KSA with iam.gke.io/gcp-service-account=GSA_EMAIL. Pods using that KSA then act as the Google service account.

Either way, application code uses Application Default Credentials exactly as it would on a VM, credentials are short-lived and per workload, and audit logs name the right identity.

Workload Identity Federation extends the keyless model to workloads outside Google Cloud: CI/CD pipelines, on-premises services and applications on other clouds. Instead of exporting a key, you configure Google Cloud to trust tokens the external environment already issues.

• Workload identity pool (gcloud iam workload-identity-pools create): a project-level container for external identities.
• Provider: describes the external issuer: OIDC (which also covers Azure workloads through Microsoft Entra ID), SAML 2.0, AWS or X.509 certificates, and which audiences its tokens must carry.
• Attribute mapping: translates token claims into Google attributes, such as google.subject=assertion.sub and attribute.repository=assertion.repository. It shapes identities; it does not reject anyone.
• Attribute condition: a CEL expression every token must satisfy, such as assertion.repository == 'ORG/REPO'. This is what restricts which external workloads can federate. A shared issuer like GitHub Actions signs tokens for every GitHub user, so Google requires an attribute condition when you create a GitHub provider, and a narrower condition (a single repository or branch rather than a whole organization's owner claim) narrows trust.

The external workload exchanges its token through the Security Token Service for a federated token. It then either uses that token directly, with roles granted to principal:// or principalSet:// identifiers from the pool, or impersonates a service account you allow it to use.

Workload versus workforce pools. Workload identity pools are for software (a CI system, a service on another cloud). Workforce identity pools, created at the organization level, are for human users from an external identity provider who sign in to the console or gcloud. An external CI pipeline needs a workload identity pool. Workforce Identity Federation belongs to identity management for users rather than service accounts.

Example: a CI system outside Google Cloud must deploy to Cloud Run on every merge. The old answer was a service account key stored in the CI platform's secrets, a long-lived production credential in a third-party system. The federated answer creates a pool and an OIDC provider for the CI platform's issuer, with an attribute condition so only your pipeline qualifies, and lets the pipeline impersonate the deployer service account for minutes at a time.