Managing IAM in GCP with gcloud: Grant, Remove, and Audit Access Safely

What you will learn

By the end of this page you will be able to:

• Read and understand an IAM policy from the command line
• Grant and remove roles at both project and resource scope
• Understand when to prefer resource-level bindings over project-level
• Audit who has access to what using get-iam-policy queries
• Avoid the most dangerous IAM command for routine changes: set-iam-policy
• Script repeatable access changes for onboarding, offboarding, and automation
• Understand the two distinct IAM roles that service accounts play

If you are new to IAM concepts, start with IAM in GCP and IAM Roles Explained before continuing here.

What it means to manage IAM with gcloud

IAM in GCP controls who can do what on which resource. Every permission flows through a binding. A binding says: this principal holds this role on this resource. The Console lets you manage bindings visually. gcloud lets you do the same thing from a terminal.

The reason teams use the CLI alongside the Console comes down to three properties:

• Repeatability. A script you run today can be run again tomorrow, in another project, or by another team member, and will produce the same result.
• Reviewability. CLI commands can live in a runbook or pull request. Anyone can read exactly what changed and why. Console clicks leave no written record.
• Scriptability. You can loop over a list of users, projects, or resources and apply access changes programmatically. You cannot do that in the Console.

The right workflow for every IAM change

Before touching any IAM policy, follow this sequence:

1. Read first. Run get-iam-policy before making any change. Know what is already in place.
2. Make the smallest possible change. Use add-iam-policy-binding or remove-iam-policy-binding, not set-iam-policy. One command, one binding.
3. Prefer narrow scope. If the service supports resource-level bindings (buckets, secrets, Pub/Sub topics), bind there rather than at project level.
4. Verify the result. Read the policy back after every change. Confirm the binding you intended is present and nothing else changed.
5. Prefer groups over users. Bind a Google Group rather than an individual user account. Update group membership centrally instead of hunting down bindings across projects.

Common gcloud IAM commands

These are the commands you will use for almost every IAM task. Each one is shown with a working example and a short explanation of what it does.

get-iam-policy: read the current policy

Use this before and after every change. It returns the full list of bindings set directly on the resource. For projects, folders, organisations, and most individual resources, the pattern is the same.

# View the full IAM policy on a project
gcloud projects get-iam-policy PROJECT_ID

# Output as JSON for scripting or export
gcloud projects get-iam-policy PROJECT_ID --format=json

# Find all roles held by a specific member
gcloud projects get-iam-policy PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:alice@example.com" \
  --format="table(bindings.role)"

# Policy on a specific resource
gcloud storage buckets get-iam-policy gs://BUCKET_NAME
gcloud secrets get-iam-policy projects/PROJECT_ID/secrets/SECRET_NAME

add-iam-policy-binding: grant a role safely

This is the safe way to grant access. It adds exactly one binding without affecting any other. Internally it performs a read-modify-write on your behalf, so you never have to handle the full policy JSON yourself.

# Grant a role at project level
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="group:platform-engineers@example.com" \
  --role="roles/logging.viewer"

# Grant at resource scope (preferred when available)
gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
  --member="serviceAccount:etl-job@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/storage.objectCreator"

# Grant with an expiry condition (auto-revokes after the date)
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="user:contractor@external.com" \
  --role="roles/logging.viewer" \
  --condition="expression=request.time < timestamp('2026-12-01T00:00:00Z'),\
title=expires-december-2026,description=Temporary audit access"

The —role flag takes a fully qualified role name such as roles/logging.viewer or a custom role path like projects/PROJECT_ID/roles/ROLE_ID. See IAM Roles Explained for a guide to role naming. For time-limited access using conditions, see IAM Conditions.

remove-iam-policy-binding: revoke a role safely

Removes exactly one binding. The same safety guarantee applies: all other bindings are left untouched.

# Remove a project-level binding
gcloud projects remove-iam-policy-binding PROJECT_ID \
  --member="group:platform-engineers@example.com" \
  --role="roles/logging.viewer"

# Remove a resource-level binding
gcloud storage buckets remove-iam-policy-binding gs://BUCKET_NAME \
  --member="serviceAccount:etl-job@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/storage.objectCreator"

Service account IAM policy binding

Service accounts have their own add-iam-policy-binding command because they are both principals (identities that act on resources) and resources (objects that other principals can manage or impersonate). The full explanation is in the service accounts section below.

# Grant a user permission to impersonate a service account
gcloud iam service-accounts add-iam-policy-binding \
  SA_EMAIL \
  --member="user:alice@example.com" \
  --role="roles/iam.serviceAccountTokenCreator" \
  --project=PROJECT_ID

# Remove impersonation permission
gcloud iam service-accounts remove-iam-policy-binding \
  SA_EMAIL \
  --member="user:alice@example.com" \
  --role="roles/iam.serviceAccountTokenCreator" \
  --project=PROJECT_ID

Reading policies before making changes

The first rule of IAM changes: read the current state before modifying it. You need to know what is already in place so you can verify that your change had exactly the intended effect and nothing else was affected.

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

# Output as JSON for scripting
gcloud projects get-iam-policy my-app-prod --format=json

# Find all bindings for a specific member
gcloud projects get-iam-policy my-app-prod \
  --flatten="bindings[].members" \
  --filter="bindings.members:alice@example.com" \
  --format="table(bindings.role)"

# View 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/db-password

Granting and removing access safely

Use add-iam-policy-binding and remove-iam-policy-binding for all routine access changes. These commands change exactly one binding and leave everything else alone.

Project-level bindings

A project-level binding applies to everything inside that project. A roles/storage.objectViewer grant at project level gives read access to every bucket in the project. Use this only when broad access is genuinely required.

# Grant read access to logs across the whole project
gcloud projects add-iam-policy-binding my-app-prod \
  --member="group:platform-engineers@example.com" \
  --role="roles/logging.viewer"

# Revoke when no longer needed
gcloud projects remove-iam-policy-binding my-app-prod \
  --member="group:platform-engineers@example.com" \
  --role="roles/logging.viewer"

Resource-level bindings

Resource-level bindings apply to a single resource. This is almost always the better choice. A roles/storage.objectCreator grant on one bucket means the principal can only write to that bucket, not to any other bucket, secret, or resource in the project. Prefer the narrowest scope the service supports.

# Grant write access to one specific bucket
gcloud storage buckets add-iam-policy-binding gs://my-app-prod-reports \
  --member="serviceAccount:etl-job@my-app-prod.iam.gserviceaccount.com" \
  --role="roles/storage.objectCreator"

# Grant access to one secret only
gcloud secrets add-iam-policy-binding db-password \
  --project=my-app-prod \
  --member="serviceAccount:api-server@my-app-prod.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

Temporary access with IAM Conditions

Use —condition to add a time-based expiry to any binding. The binding is automatically denied after the date you specify, with no manual cleanup required. This is useful for contractor access, incident response, or any situation where access should not be permanent. See IAM Conditions for the full syntax and other condition types.

gcloud projects add-iam-policy-binding my-app-prod \
  --member="user:contractor@external.com" \
  --role="roles/logging.viewer" \
  --condition="expression=request.time < timestamp('2026-12-01T00:00:00Z'),\
title=expires-december-2026,description=Temporary audit access"

When to use gcloud for IAM changes

Not every IAM change needs to go through gcloud, but these are the situations where it clearly earns its place:

• One-off access changes where you want a clear record of exactly what you ran and why.
• Debugging permission issues: quickly read the policy on a resource to see who has access. Pair this with Permission Denied Errors when access is unexpectedly blocked.
• Onboarding and offboarding: a short script that grants or revokes a standard set of roles is faster and less error-prone than clicking through the Console for every team change.
• Scripting repeatable access changes: loop over a list of service accounts or environments and apply bindings consistently.
• Environments where Console access is restricted: many production environments restrict Console access for compliance reasons. CLI and automation are the only paths available.
• Periodic access reviews: query and filter bindings directly from the terminal to verify who holds what at a point in time.

gcloud vs Console vs Terraform

All three tools can manage GCP IAM bindings. The right choice depends on what you are trying to accomplish:

A common pattern in mature teams: use gcloud for day-to-day operational access and Terraform for baseline access that defines what every team or service account should always have.

See Managing IAM with Terraform for a full guide, including how google_project_iam_member and google_project_iam_binding differ and when to use each.

Never use set-iam-policy for routine changes

set-iam-policy is not a broken command. It is the right tool for bulk, controlled operations where you explicitly intend to define the full desired state of a policy. The safe way to use it is to start from a freshly exported policy, make your edits, and then apply:

# SAFE: export first, edit the file, then apply
gcloud projects get-iam-policy my-app-prod --format=json > policy.json
# Edit policy.json carefully to add or remove the bindings you intend
gcloud projects set-iam-policy my-app-prod policy.json

# RISKY: building a policy.json from scratch and applying it
# Any binding you omit will be deleted immediately and silently

Verifying changes after applying them

After every IAM change, read the policy back. Do not assume the command worked as intended. This 30-second habit prevents a class of IAM mistakes that are hard to diagnose after the fact.

Verification checklist:

• Run get-iam-policy and confirm your new binding is present
• Confirm no other bindings changed unexpectedly
• For resource-level changes, query the resource policy directly, not just the project policy
• If the access is needed urgently, test it by running a command as the principal

# Confirm the binding you just added is present
gcloud projects get-iam-policy my-app-prod \
  --flatten="bindings[].members" \
  --filter="bindings.members:group:platform-engineers@example.com" \
  --format="table(bindings.role)"

# For resource-level bindings, query the resource directly
gcloud storage buckets get-iam-policy gs://my-app-prod-reports \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:etl-job@my-app-prod.iam.gserviceaccount.com"

Service accounts have two IAM angles

Service accounts appear in two completely different contexts in IAM, and both are managed with gcloud. Understanding the difference prevents a common source of confusion.

Service account as a principal

When a service account needs to access a resource, such as reading from a Cloud Storage bucket or accessing a secret, you bind a role to the service account on that resource. The service account is the principal being granted access.

# The service account is being granted access to a resource
gcloud storage buckets add-iam-policy-binding gs://my-app-prod-data \
  --member="serviceAccount:api-server@my-app-prod.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

Service account as a resource

When a human user or another service account needs to act as a service account, you bind a role on the service account itself. Here the service account is the resource, not the principal. You are granting someone the ability to use that service account’s identity.

# A user is being granted permission to impersonate the service account
# The service account is the resource here
gcloud iam service-accounts add-iam-policy-binding \
  ci-deployer@my-app-prod.iam.gserviceaccount.com \
  --member="user:alice@example.com" \
  --role="roles/iam.serviceAccountTokenCreator" \
  --project=my-app-prod

For a full explanation of impersonation, how it works, and how to use it securely without key files, see Service Account Impersonation. For background on service accounts themselves, see Service Accounts.

Auditing access with gcloud

These queries answer the most common questions during access reviews, all from the CLI. Combine get-iam-policy with —flatten, —filter, and —format to extract exactly the view you need.

# All roles and members in the project as a flat list
gcloud projects get-iam-policy my-app-prod \
  --flatten="bindings[].members" \
  --format="table(bindings.role,bindings.members)"

# Every role held by a specific group
gcloud projects get-iam-policy my-app-prod \
  --flatten="bindings[].members" \
  --filter="bindings.members:group:on-call-engineers@example.com" \
  --format="table(bindings.role)"

# All direct user: bindings (should be rare in a well-managed project)
gcloud projects get-iam-policy my-app-prod \
  --flatten="bindings[].members" \
  --filter="bindings.members:user:" \
  --format="table(bindings.role,bindings.members)"

Direct user bindings should be rare. Most access should flow through Google Groups so membership can be managed centrally. Any user: binding is a candidate for migration to a group or removal.

For longer-term audit workflows, including who changed what and when, see Cloud Audit Logs. For debugging active permission failures, see Fixing IAM AccessDenied Errors.

Scripting IAM changes for onboarding and offboarding

Scripted IAM changes are repeatable, reviewable, and auditable. Treat IAM scripts the same as infrastructure code: test in a non-production project first and store them in version control.

# Onboarding: grant a new engineer read access to logs and monitoring
NEW_USER="new.hire@example.com"
PROJECT="my-app-prod"

gcloud projects add-iam-policy-binding "$PROJECT" \
  --member="user:$NEW_USER" \
  --role="roles/logging.viewer"

gcloud projects add-iam-policy-binding "$PROJECT" \
  --member="user:$NEW_USER" \
  --role="roles/monitoring.viewer"

echo "Verifying bindings for $NEW_USER:"
gcloud projects get-iam-policy "$PROJECT" \
  --flatten="bindings[].members" \
  --filter="bindings.members:$NEW_USER" \
  --format="table(bindings.role)"