GCP Service Account Impersonation Explained: Keyless Access Without JSON Keys

Simple explanation

Think of a hotel key card that has been programmed for one room, for one night. It works perfectly for that window of time. When it expires, it stops working and the hotel has no permanent copy to worry about. Nobody needs to track it down or revoke it.

Service account impersonation works the same way. You are Alice, a developer. You want to test your application as a specific service account. Instead of downloading a JSON key file (a permanent copy of its credentials that you now have to store, rotate, and never accidentally commit), you ask GCP to issue a temporary token that acts as that service account. GCP checks that you are allowed to do this, hands you a token valid for up to one hour, records the event in audit logs, and lets you proceed. When the token expires, there is nothing left to clean up.

What service account impersonation is

Service accounts are GCP identities used by workloads rather than humans. When you need to act as a service account to test it, debug it, or run a one-off admin task, you have two options.

Option 1: Service account key file. Download a JSON credential that permanently authenticates as that service account. The file is valid until you manually revoke it and carries significant security risk if mishandled, committed to a repo, or forgotten in a CI environment.

Option 2: Service account impersonation. Generate a short-lived token on the fly using your own authenticated identity. No file is created. The token expires automatically. Audit logs record both you and the target service account.

Impersonation is the preferred pattern for developers testing locally, CI/CD pipelines, and any workflow where a human or GCP-hosted system needs to temporarily act as a different service account. It eliminates the long-lived credential risk that makes service account keys problematic at scale.

How it works

Impersonation is handled by the IAM Service Account Credentials API. Here is what happens when you run a gcloud command with —impersonate-service-account:

1. Source identity authenticates. Your own identity (a user account or the attached service account of a VM) authenticates with GCP as normal.

2. Token request is made. gcloud (or your code) calls the generateAccessToken method on the IAM Service Account Credentials API, specifying the target service account.

3. IAM checks the policy. GCP verifies that the source identity has roles/iam.serviceAccountTokenCreator on the target service account.

4. Short-lived token is issued. A token is returned, valid for up to one hour. It cannot be extended or refreshed. Request a new token after it expires.

5. Audit log is written. The Cloud Audit Log records the event, including both the source identity and the target service account. This is the key audit advantage over key files, which only log the service account, not who used it.

The token carries the target service account’s permissions for the duration of its lifetime. GCP has no record of a key file, no secret stored outside of memory, and nothing to rotate.

When to use this

Impersonation is the right tool in the following situations:

• Local developer testing. A developer wants to test their application locally as a specific service account. Instead of downloading a key file, they impersonate the account using their own identity. This is the primary use case and the one that eliminates most accidental key leaks.

• CI/CD deployment pipelines. A deployer service account in a CI pipeline needs to act as a different service account to deploy to a specific environment. Rather than storing keys, the CI pipeline impersonates the target account at deploy time. See Secure CI/CD Pipelines for the full pattern.

• Temporary administrative tasks. A security engineer needs to run a one-off audit or remediation using a high-privilege service account. Impersonation gives them temporary access without permanently granting the account’s permissions to their user identity.

• Cross-project automation. An automation service account in one project needs to briefly act as a service account in another project to read or write a resource. Impersonation avoids creating a persistent trust relationship via a shared key.

• Migrating away from service account keys. Teams already using key files can incrementally replace them with impersonation. Each migrated use case reduces the attack surface without requiring a big-bang architecture change.

When not to use this

Impersonation is not the right tool in every scenario.

• Runtime workloads attached to GCP compute. If a Cloud Run service, GKE pod, or Compute Engine VM is running as a service account, the service account is attached to the resource. That is not impersonation. The workload natively uses the attached identity without any token request. Impersonation would add unnecessary complexity in this case.

• External workloads outside GCP. If the caller is a GitHub Actions workflow, a Jenkins agent, or an on-premises system, consider Workload Identity Federation instead. It federates external identity providers (GitHub OIDC, HashiCorp Vault, AWS, and others) directly with GCP IAM, removing the need for any GCP credential at the pipeline level.

• When the caller has no established GCP identity. Impersonation requires the source identity to already be authenticated with GCP. It is not a way to bootstrap authentication from scratch. External systems without a GCP identity need Workload Identity Federation, not impersonation.

• When access should be permanent. If a service genuinely needs long-term access to another resource, grant the service account that access directly. Do not grant impersonation rights and generate tokens continuously as a workaround.

Key permissions and roles

Two IAM roles relate to service accounts and they are frequently confused. Getting this wrong either breaks your workflow or silently grants the wrong level of access. Read this section carefully before configuring anything.

If you grant serviceAccountUser thinking it enables impersonation, the token request fails with a permission denied error. If you grant serviceAccountTokenCreator thinking it is needed for deployment, you may inadvertently allow the grantee to impersonate production accounts when they only needed deployment rights. See Permission Denied Errors for help diagnosing these misconfigurations.

Service account impersonation vs other approaches

Impersonation vs service account key files

Service account keys are dangerous because they create long-lived, file-based credentials that can be leaked, committed to a repository by accident, or left unrotated for months. Impersonation solves all of these problems: there is no file, tokens expire automatically in one hour, and audit logs record both the caller and the target. For any use case where a human or GCP-hosted system needs to act as a service account, impersonation is the safer choice.

Impersonation vs serviceAccountUser

These two roles are not alternatives to each other. They serve entirely different purposes. serviceAccountTokenCreator is for generating short-lived tokens (impersonation). serviceAccountUser is for attaching a service account to a compute resource at deployment time.

A quick way to remember the difference: if you are running commands as a service account, you need Token Creator. If you are deploying a service that will run as a service account, you need Service Account User. Granting one when you need the other will not work and may create unintended access in the wrong direction.

Impersonation vs Workload Identity Federation

Workload Identity Federation is the preferred solution for external workloads. It allows a GitHub Actions runner, an AWS Lambda, or any system with an OIDC or SAML identity to authenticate directly to GCP without any GCP credentials. The external system exchanges its own identity token for a short-lived GCP access token.

Impersonation requires the source identity to already have a GCP identity. If your pipeline runs inside GCP (on a VM, in Cloud Build, in Cloud Run), impersonation is simpler. If your pipeline runs outside GCP, Workload Identity Federation is typically cleaner and removes more credential risk.

The two approaches can be combined: an external pipeline uses Workload Identity Federation to get a GCP identity, then uses impersonation to assume a specific deployer service account. This is a common pattern in teams managing multiple environments.

Practical usage

Granting impersonation rights

Grant roles/iam.serviceAccountTokenCreator on the target service account as a resource, not on the project. The command below uses add-iam-policy-binding targeting the service account’s own IAM policy. See Managing IAM with gcloud for more on resource-level IAM bindings.

# Grant alice permission to impersonate one specific service account.
# The binding is set ON the service account resource, not on the project.
gcloud iam service-accounts add-iam-policy-binding \
  backend-api@my-app-prod.iam.gserviceaccount.com \
  --member="user:alice@example.com" \
  --role="roles/iam.serviceAccountTokenCreator" \
  --project=my-app-prod

After running this, Alice can generate short-lived tokens for backend-api@my-app-prod.iam.gserviceaccount.com only. She cannot impersonate any other service account in the project unless explicitly granted.

Using impersonation with gcloud

Add —impersonate-service-account to any gcloud command to run it as the target service account. You can also set a session-level default so you do not need to repeat the flag on every command.

# Run a single gcloud command as a specific service account
gcloud projects get-iam-policy my-app-prod \
  --impersonate-service-account=backend-api@my-app-prod.iam.gserviceaccount.com

# List Cloud Storage objects as the service account
gcloud storage ls gs://my-app-prod-data \
  --impersonate-service-account=backend-api@my-app-prod.iam.gserviceaccount.com

# Set a session-level default to avoid repeating the flag
gcloud config set auth/impersonate_service_account \
  backend-api@my-app-prod.iam.gserviceaccount.com

# Clear the default when your testing session is finished
gcloud config unset auth/impersonate_service_account

Using impersonation in application code

The Google Cloud client libraries support impersonated credentials directly. The example below shows Python, but the same pattern exists in Go, Java, and Node.js via the respective client libraries.

# Python: Application Default Credentials with impersonation
from google.auth import impersonated_credentials
from google.auth import default as google_auth_default
from google.cloud import storage

# Load the source credentials (the developer's own identity via ADC)
source_credentials, _ = google_auth_default()

# Wrap them with impersonated credentials for the target service account
target_credentials = impersonated_credentials.Credentials(
    source_credentials=source_credentials,
    target_principal="backend-api@my-app-prod.iam.gserviceaccount.com",
    target_scopes=["https://www.googleapis.com/auth/cloud-platform"],
    lifetime=3600,  # maximum is 3600 seconds (one hour)
)

# Pass the impersonated credentials to the client
# All API calls now run as the service account
storage_client = storage.Client(credentials=target_credentials)

The source credentials come from Application Default Credentials, which means the developer does not need a key file at any point in this flow. See Troubleshooting Authentication Errors if ADC is not finding credentials correctly.

Generating tokens via the REST API

For CI systems, shell scripts, or any tooling that makes authenticated HTTPS requests but does not use the Google client libraries, call the IAM Service Account Credentials API directly.

# Step 1: Get an access token for your own identity
MY_TOKEN=$(gcloud auth print-access-token)

# Step 2: Call generateAccessToken for the target service account
curl -s -X POST \
  "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/backend-api@my-app-prod.iam.gserviceaccount.com:generateAccessToken" \
  -H "Authorization: Bearer $MY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scope": ["https://www.googleapis.com/auth/cloud-platform"], "lifetime": "3600s"}'

The response contains an accessToken and an expireTime. Use the token as a Bearer token in subsequent GCP API calls. It cannot be refreshed after expiry: request a new one. For background on storing secrets safely in CI environments, see Secrets in CI/CD Pipelines.

Delegation chains

GCP supports delegation chains where service account A impersonates B, which then impersonates C. Each step requires serviceAccountTokenCreator on the next account in the chain.

Security best practices

• Grant Token Creator on the service account resource, not the project. This is the single most important configuration choice. A project-level grant is almost never what you actually want.

• Apply least privilege to the source identity. The source identity should only have Token Creator on the specific service accounts it genuinely needs to impersonate. Review these grants regularly. See Least Privilege in GCP for the broader framework.

• Delete old key files after migrating to impersonation. A service account with both active keys and impersonation configured still carries the full risk of the key. Migration is only complete when the keys are revoked and deleted.

• Monitor GenerateAccessToken activity. Create log-based alerts on this method in Cloud Audit Logs, especially for service accounts with high-privilege access. Alert on unexpected caller identities and unusual times of day.

• Separate CI deployer identities from production workload identities. The service account used by a CI pipeline to deploy should be different from the service account the deployed workload runs as. If a CI deployer is compromised, it should not have direct access to production data, only deployment rights. This separation is explained in Secure CI/CD Pipelines.

• Do not store short-lived tokens. Tokens should be used within the same pipeline run or shell session that generated them. Writing a token to a file or environment variable that outlasts the session reintroduces the credential storage risk that impersonation was meant to eliminate.

• Use Terraform for consistent, auditable IAM grant management. Managing impersonation grants via Terraform ensures they are version-controlled and reviewed before being applied. See Managing IAM with Terraform for the pattern.