GCP IAM Policies Explained: Bindings, Inheritance, ETags, and Safe Changes

The simple version

An IAM policy is the access document attached to a Google Cloud resource. It says who gets which role on that resource.

Every project has an IAM policy. Every Cloud Storage bucket has one. Every Secret Manager secret has one. When GCP receives an API request, it looks up the relevant policies and checks whether the caller has the required permission. If yes, the request succeeds. If no policy grants that permission, GCP returns a permission denied error.

That is the whole model. The rest of this page fills in the details that matter in practice.

What is an IAM policy in GCP?

An IAM policy is a structured document that controls access to a single GCP resource. Policies can be attached to:

• Organisations
• Folders
• Projects
• Cloud Storage buckets
• BigQuery datasets
• Pub/Sub topics and subscriptions
• Secret Manager secrets
• Cloud Run services
• And many other resource types

The policy is not a global list of all access across your account. It belongs to one resource and governs access to that resource only. For background on how GCP organises projects and resources, see the resource hierarchy guide. For a broader introduction to how IAM fits together, see IAM in GCP.

The three fields in every IAM policy

Every IAM policy document contains exactly three top-level fields. Understanding what each one does is the foundation of working with IAM safely.

• bindings: the access grants. An array of role-to-member mappings. This is the core of the policy.
• etag: a concurrency control token that prevents two simultaneous updates from overwriting each other.
• version: the policy schema version. Version 1 is standard. Version 3 is required when the policy contains IAM Conditions.

# A typical project IAM policy
bindings:
  - role: roles/storage.objectViewer
    members:
      - group:data-readers@example.com
  - role: roles/run.invoker
    members:
      - serviceAccount:api-gateway@my-app-prod.iam.gserviceaccount.com
  - role: roles/logging.viewer
    members:
      - group:platform-engineers@example.com
      - user:alice@example.com
etag: BwWWja0YfJA=
version: 1

Bindings

Each binding connects one role to a list of members. Members are prefixed by type to tell GCP what kind of identity it is:

• user: a Google Account belonging to a person
• serviceAccount: a service account used by an application or workload
• group: a Google Group containing many users
• domain: all users in a Google Workspace domain
• allAuthenticatedUsers any authenticated Google identity (use with caution)
• allUsers literally anyone, including unauthenticated requests

One binding can have many members, but it can only reference one role. To grant two roles to the same person, you need two separate bindings.

Etag

The etag is a hash of the current policy state. When you call get-iam-policy, the response includes the current etag. When you call set-iam-policy, GCP checks that the etag in your file matches the current etag on the resource.

If another change was made between your read and your write, the etags will not match and the operation fails. This prevents concurrent updates from silently overwriting each other, which is a common problem in team environments where multiple engineers might adjust IAM around the same time.

Version

Most policies use version 1. Version 3 is only required when a policy contains IAM Conditions: conditional bindings that restrict when or where access applies. If you read a version 3 policy and reapply it using an older tool that does not understand conditions, those conditions may be silently stripped. Always check the version field before writing back a policy file.

How IAM policies work

When you make a GCP API call, IAM evaluates access like this:

1. GCP identifies the resource you are trying to access.
2. GCP collects all applicable IAM policies: from the resource itself, plus its parent project, any folders, and the organisation.
3. GCP checks whether any binding in any of those policies grants the required permission to the caller.
4. If yes, the call succeeds. If no binding matches, the call fails with a permission denied error.

Access is the union of all applicable policies. A binding at the project level is just as effective as one at the resource level. They are evaluated together, not in priority order.

Policy levels and inheritance

Policies exist at four levels of the resource hierarchy:

• Organisation: applies to every folder, project, and resource in the organisation
• Folder: applies to all projects within that folder and everything inside them
• Project: applies to all resources within the project
• Individual resource: applies only to that specific resource. Buckets, secrets, topics, and datasets all support resource-level policies.

Inheritance flows downward and is additive. If a user has roles/viewer at the folder level, they have viewer access on every project and resource inside that folder. Nothing at the project or resource level can take that away.

Organisation (roles/viewer granted to alice)
  └── Folder: production
        └── Project: my-app-prod    ← alice has viewer here too
              └── Bucket: my-app-prod-data  ← and here

Project-level vs resource-level IAM policies

One of the most practical decisions in GCP IAM is where to set a binding. You usually have two realistic options: on the project, or on the specific resource.

Project-level policies

A binding on the project applies to every resource in that project. This works well for broad, team-wide access, such as giving an engineering team read-only access to monitor everything in a project.

The trade-off is scope. A service account with roles/storage.objectViewer at the project level can read every bucket in the project, not just the one you intended.

Resource-level policies

A binding on an individual resource applies only to that resource. This is the safer option when access should be narrow, and it directly supports the principle of least privilege by limiting what a compromised identity can reach.

When to use each

• Use project-level when giving a team broad read-only monitoring access to a project
• Use project-level when a CI/CD service account needs to deploy across multiple services in the same project
• Use resource-level when one service account needs access to one specific bucket for an ETL job
• Use resource-level when a workload needs to access one specific secret in Secret Manager
• Use resource-level when an external identity should be allowed to invoke only one specific Cloud Run service

IAM policy vs IAM role

These two terms are often confused. They are related but distinct:

• Role: a named set of permissions. For example, roles/storage.objectViewer includes permissions like storage.objects.get and storage.objects.list. Roles do not contain any information about who holds them.
• Binding: a single entry inside a policy that says “these members hold this role on this resource.”
• Policy: the full document attached to a resource, containing all bindings for that resource.

For a deeper look at the types of roles available, see IAM Roles Explained and Basic vs Predefined vs Custom Roles.

IAM policies and IAM Conditions

Standard IAM bindings apply unconditionally. If the member has the role on the resource, access is always active. IAM Conditions let you attach a conditional expression to a binding so that access only applies in specific circumstances.

Common uses include:

• Time-based expiry: access only during business hours or before a specific date
• Resource attribute conditions: access only to resources tagged a certain way
• Request attribute conditions: access only from a specific IP range

Using conditions requires policy version 3. When you add a condition via gcloud, the version upgrades automatically. For the full picture, see IAM Conditions.

How to read an IAM policy

Pull a policy with get-iam-policy like this:

# View the policy on a project
gcloud projects get-iam-policy my-app-prod

# View the policy on a specific resource
gcloud storage buckets get-iam-policy gs://my-app-prod-data
gcloud secrets get-iam-policy projects/my-app-prod/secrets/api-token

When reading the output, look for:

• The role: check it matches your intent. Prefer predefined roles over basic roles like roles/editor.
• The members: watch for allUsers or allAuthenticatedUsers, which grant public or near-public access.
• The scope: remember that project-level output does not show inherited bindings from parent folders.
• Conditions: if a binding has a condition block, check what it restricts. Conditions only work with version 3.
• The etag: save this before making any changes. It protects your write from overwriting a concurrent update.

# Filter to find all roles held by one specific member
gcloud projects get-iam-policy my-app-prod \
  --flatten="bindings[].members" \
  --filter="bindings.members:alice@example.com" \
  --format="table(bindings.role)"

How to modify policies safely

There are two approaches to modifying a policy. For a complete CLI walkthrough with more examples, see Managing IAM with gcloud. For infrastructure-as-code workflows, see Managing IAM with Terraform.

Incremental binding commands (use this by default)

These commands add or remove a single binding atomically. They handle the read-modify-write cycle internally and will not touch any other bindings.

# Add one binding to a project
gcloud projects add-iam-policy-binding my-app-prod \
  --member="group:platform-engineers@example.com" \
  --role="roles/logging.viewer"

# Remove the same binding
gcloud projects remove-iam-policy-binding my-app-prod \
  --member="group:platform-engineers@example.com" \
  --role="roles/logging.viewer"

# Resource-level binding on a bucket (narrower than project level)
gcloud storage buckets add-iam-policy-binding gs://my-app-prod-data \
  --member="serviceAccount:etl-job@my-app-prod.iam.gserviceaccount.com" \
  --role="roles/storage.objectCreator"

Read-modify-write (for controlled bulk changes)

When you need to make several changes at once, or manage IAM as code, export the current policy first, edit the exported file, and apply it back. The etag in the exported file is your safety net.

# Step 1: export the current policy
gcloud projects get-iam-policy my-app-prod --format=json > policy.json

# Step 2: edit policy.json (add, remove, or modify bindings)

# Step 3: apply the updated policy
gcloud projects set-iam-policy my-app-prod policy.json

When to use this

Working with IAM policies directly comes up in several common scenarios:

• Giving a team viewer access to a project: set one binding at the project level so every member of a Google Group can view resources without individual setup.
• Granting a workload access to one specific resource: set a resource-level binding so a service account can only reach the one bucket or secret it needs. See service accounts for how to set these up.
• Auditing who can access a secret or service: read the policy at every relevant level to get the full picture of who has access and why.
• Preparing to use IAM Conditions: understand the current policy structure and version before adding conditional bindings to avoid unintended changes.
• Debugging a permission denied error: read the policy on the resource, then check parent levels too. See Fixing IAM Access Denied errors for a step-by-step approach.
• Moving from basic roles to predefined roles: audit current project-level policies and replace overly broad bindings with narrower, resource-specific ones.