Service Account Impersonation

Service-account impersonation lets your human identity borrow a service account's permissions through short-lived tokens — without ever holding a key file. You authenticate as yourself through ADC, prove you hold roles/iam.serviceAccountTokenCreator on the target account, and the provider mints an hour-long token to act as it.

This is the recommended way for engineers and pipelines to act as a service account on GCP. The static key file it replaces is the single credential most likely to leak; impersonation gives the same power with nothing on disk, an expiry measured in minutes, and an audit trail showing exactly who borrowed which identity.

The Problem It Solves

Engineers need to apply infrastructure as a privileged service account — Hatch's Terraform runs as tf-admin@hatch-pipeline-dev.iam.gserviceaccount.com, which has the roles to create buckets, datasets, and service accounts. The naive way to let a human act as that account is to hand them its key file. That key is a leak waiting to happen: it lives in dotfiles, gets pasted into Slack, ends up in a git history.

Impersonation gives the same power with no static secret. The engineer never sees a key — they authenticate as themselves and borrow the service account on demand. Revoking access is removing one IAM binding, not rotating a key that may already have been copied a dozen places.

How It Works

You set impersonate_service_account on the provider block (or configure ADC impersonation through gcloud). When Terraform runs, it exchanges your own identity for a short-lived access token on the target service account, calling the IAM Credentials API. That exchange is gated: it only succeeds if your identity holds roles/iam.serviceAccountTokenCreator on the target.

provider "google" {
  project = "hatch-pipeline-dev"
  region  = "us-central1"

  # You authenticate as yourself; the provider borrows this SA:
  impersonate_service_account = "tf-admin@hatch-pipeline-dev.iam.gserviceaccount.com"
}

Every API call this provider makes now runs as tf-admin, using a token minted from your identity. Your own login needs almost no permissions — only the right to impersonate. All the privileged roles live on the service account, and you borrow them for an hour at a time.

Granting the Right

Impersonation is itself an IAM grant. A user or group gets roles/iam.serviceAccountTokenCreator on the specific service account they are allowed to borrow — not at the project level, which would let them impersonate every account in the project. The grant scopes precisely who may act as which identity.

resource "google_service_account_iam_member" "impersonate" {
  service_account_id = google_service_account.tf_admin.name
  role               = "roles/iam.serviceAccountTokenCreator"
  member             = "group:gcp-developers@hatch.io"
}

The grant is on service_account_id — the target account itself — so it authorizes gcp-developers@hatch.io to borrow only tf-admin, nothing else. Granting serviceAccountTokenCreator at the project level instead would let that group impersonate every service account in hatch-pipeline-dev, which is far too broad.

Impersonation Chains

Impersonation can chain: identity A impersonates B, which impersonates C. This is useful for delegation across project boundaries — a CI identity in one project borrows a deploy account in another, which borrows a narrowly-scoped account in a third. Each hop is a separate serviceAccountTokenCreator grant on the next link.

Chains are also where impersonation produces its most confusing errors. Miss one grant in the middle and you get an opaque token-creation failure that names neither the missing link nor the role. Keep chains short and reserve them for genuine cross-boundary delegation — every extra hop is another place a missing grant can break the whole path.

Why This Beats Keys

Three properties make impersonation strictly better than a key file. Tokens expire in roughly an hour, so a leaked token is useless by lunch — a leaked key is useful until someone notices and rotates it. Nothing is stored on disk, so there is no file to exfiltrate. And the audit log records both identities: the real human who initiated, and the service account they impersonated.

That audit property is the one teams underrate. With a shared key file, the logs show only the service account, so "who actually ran this destroy?" has no answer. With impersonation, the log shows the real engineer behind the borrowed identity — accountability a key file cannot provide. Prefer impersonation in every case where it is possible.