GCP - IAM

Principals, Roles, Permissions

a role can have multiple permissions
a role can be granted to a principal
a principal can be a user, a service account, a group, etc

Service account impersonation

What is Service account impersonation?

Impersonating the service account =

A user gains permissions of a service account, or
A service account A gains permissions of service account B.

When to impersonate a service account?

change a user's permissions without changing your IAM policies.
temporarily grant a user elevated access.
test whether a specific set of permissions is sufficient for a task.
locally develop applications that can only run as a service account.
authenticate applications that run outside of Google Cloud.

How does impersonation work?

Technically "impersonation" means granting the principal (a user or another service account) the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) on the service account. So that the authenticated principal gets a token for the service account, then uses that token to authenticate as the service account.

How to impersonate a service account?

using gcloud command with --impersonate-service-account, the CLI creates short-lived credentials for the service account and runs the command with those credentials.
The Cloud Client Libraries use Application Default Credentials (ADC) to obtain short-lived credentials for the service account.

What's the equivelant concept in AWS?

Google Cloud service account impersonation is similar to Amazon Web Services (AWS) Security Token Service API methods like AssumeRole.

What is Workload Identity Federation?

Workload Identity Federation: workload running in AWS/Azure can access Google Cloud resources
- e.g. a VM running on AWS writes result to a GCS bucket.
Workload Identity Federation for GKE: workload running in GKE can access Google Cloud resources.
- Kubernetes service accounts (which is different from GCP service account) in the GKE cluster can access Google Cloud resources directly.

How does Application Default Credentials work?

Application Default Credentials (ADC) is a strategy used by Google authentication libraries to automatically find credentials without you having to hardcode paths or secrets into your source code.

It follows a "Write Once, Run Anywhere" philosophy: your code looks for credentials in a specific order, allowing it to run on your local laptop, a GCE VM, or a Cloud Run container without changing a single line of authentication logic.

The "Search Order" (How ADC finds an identity)

When your code calls a Google Cloud library (like the Storage or BigQuery client), ADC looks for a credential in this exact order. As soon as it finds one, it stops searching.

1. The Environment Variable (`GOOGLE_APPLICATION_CREDENTIALS`)

ADC first checks if you have defined a specific file path in your environment.

Usage: Mostly for local development or when using a Service Account JSON key.
Setup: export GOOGLE_APPLICATION_CREDENTIALS="/home/user/downloads/service-account-file.json"
Note: In production, using JSON keys is discouraged for security reasons.

2. User Credentials (via gcloud CLI)

If the environment variable isn't set, ADC looks for credentials created by the Google Cloud CLI.

Usage: The standard for local development.
Setup: You run gcloud auth application-default login.
Location: It saves a small JSON file in a well-known hidden folder on your machine (e.g., ~/.config/gcloud/application_default_credentials.json).
Benefit: Your code now acts as you (your developer identity) when talking to GCP.

3. The Metadata Server (Attached Service Accounts)

If the code is running inside Google Cloud (GCE, GKE, Cloud Run, Cloud Functions), ADC queries the internal Metadata Server.

Usage: The most secure method for production.
How it works: Every GCP compute resource has access to a local, internal-only URL (http://metadata.google.internal). ADC hits this URL to ask: "What service account is attached to this VM/Container? Give me a temporary token for it."
Benefit: No keys are stored on disk. If the VM is compromised, there is no JSON file for a hacker to steal.

4. The Fail State

If none of the above are found, the library throws an error: "Could not automatically determine credentials."

Why is ADC important?

1. Security: No Hardcoded Keys

Because ADC handles the lookup, you never have to put a key.json file inside your Git repository. You simply tell the environment (the VM or the CLI) who it is, and the code figures it out at runtime.

2. Portability (The "Dev-to-Prod" Pipeline)

On your laptop: You run gcloud auth application-default login. The code uses your permissions to test a BigQuery query.
In Jenkins/CI: You set the GOOGLE_APPLICATION_CREDENTIALS variable to a service account for testing.
In Production (GKE): You attach a Service Account to the Pod (via Workload Identity). The code automatically switches to using the Metadata Server.
Result: The code remains storage.Client() in all three environments.

Common Gotchas

gcloud auth login vs gcloud auth application-default login:
- gcloud auth login authenticates the CLI tool itself (so you can run gcloud compute instances list).
- gcloud auth application-default login authenticates your code (so your Python/Go/Node script can find your identity). You usually need to run both on a new machine.
Scopes:
- When using the Metadata Server (especially on older GCE instances), you must ensure the "Cloud API Access Scopes" on the VM are set to cloud-platform. Even if your IAM is correct, an "Access Scope" can block ADC from getting a token.
Impacting Performance:
- ADC lookup is extremely fast because the libraries cache the token in memory once it is found. It doesn't re-scan the whole list for every single API call.

Summary Table

Environment	ADC Source	Setup Command / Action
Local Development	User Identity	`gcloud auth application-default login`
Custom / On-Prem	JSON Key File	`export GOOGLE_APPLICATION_CREDENTIALS=...`
Google Cloud (VM/Serverless)	Service Account	Attach SA to the resource (GCE, Cloud Run, etc.)