Managing Cloud IAM: Roles, Policies, and Inheritance

Cloud IAM answers one question, who can do what on which resource, with three building blocks. A principal (also called a member) is the identity requesting access. A role is a named bundle of permissions, where each permission is a verb on a service resource such as compute.instances.start or storage.objects.get. You never grant a permission directly to a principal: permissions travel only inside roles.

A role binding ties one role to a list of principals, and an allow policy (often just called the IAM policy) is the set of bindings attached to a single resource. Policies can attach at the organization, a folder, a project, or an individual resource that supports its own policy, such as a Cloud Storage bucket, a Pub/Sub topic or a service account. A binding can also carry an optional IAM condition that limits when the grant applies (covered below).

Principal identifiers and what each one covers

Because allAuthenticatedUsers includes every Google Account in the world, it is not a staff-only setting: for company-only access use domain: or, better, a group:. Because domain: covers user accounts only, a service account that also needs the access must be granted with its own serviceAccount: member.

The member value must carry the right prefix and the right form. Common mistakes are a bare email with no prefix, user: in front of a service account's email, and a service account's resource name (projects/PROJECT_ID/serviceAccounts/EMAIL) where the member format serviceAccount:EMAIL is required. Roles are named in full too: predefined roles as roles/NAME, custom roles as projects/PROJECT_ID/roles/ROLE_ID or organizations/ORG_ID/roles/ROLE_ID.

Two consequences of the model come up constantly. Because permissions only travel inside roles, the fix for one missing permission is finding (or building) a role that carries it. Because the policy lives on the resource rather than on the person, working out what someone can do means examining policies across the hierarchy and through their group memberships, which is why the inheritance rules and Policy Troubleshooter matter.

You view an allow policy with get-iam-policy on the node you care about: gcloud projects get-iam-policy PROJECT_ID, gcloud resource-manager folders get-iam-policy FOLDER_ID, gcloud organizations get-iam-policy ORG_ID, or per-resource commands such as gcloud storage buckets get-iam-policy gs://my-bucket. Each prints the bindings set on that one node only (roles, principals, conditions) plus an etag. It does not show grants inherited from ancestors, and it shows groups, not the people inside them. To see a project's own policy and every ancestor's policy in one call, use gcloud projects get-ancestors-iam-policy PROJECT_ID. The Console IAM page also labels inherited grants with the level they come from.

Granting and revoking one binding

To grant a role, add a binding: gcloud projects add-iam-policy-binding PROJECT_ID --member=group:devs@example.com --role=roles/compute.instanceAdmin.v1. To revoke, use remove-iam-policy-binding with the same flags. These helpers read the current policy, change one binding and write it back, so they are the safe day-to-day tool. Equivalent commands exist for folders, organizations and individual resources.

When the same member and role appear in conditional bindings, you must say which binding to remove: --condition=None removes only the unconditional binding, --condition=EXPRESSION (with its title and description) removes the binding that matches exactly, and --all removes every binding of that role for that member regardless of condition.

Replacing the whole policy: set-iam-policy and the etag

gcloud projects set-iam-policy PROJECT_ID policy.json writes the file as the entire allow policy: any binding missing from the file is removed. The safe pattern is read-modify-write: export with get-iam-policy --format=json > policy.json, edit, then set. The exported etag identifies the version you read. If someone else changed the policy in between, the etag no longer matches and the write fails; you re-read, re-apply your edit and retry. If you delete the etag from the file, the write is unconditional and silently overwrites any concurrent change.

Who may edit a policy, and how to diagnose access

Changing a policy needs the setIamPolicy permission on that resource, which comes from Owner or an IAM-administration role (compared in a later section). To answer "why can (or can't) this person do X here?", use Policy Troubleshooter: give it a principal email, a full resource name and a permission (in the Console, or gcloud policy-troubleshoot iam RESOURCE --principal-email=EMAIL --permission=PERMISSION). It evaluates the bindings that actually apply, including grants inherited from folders and the organization and grants that reach the person through group membership. Searching get-iam-policy output for the person's email misses both. IAM Recommender complements it by suggesting tighter roles based on permissions actually used.

An IAM condition is a Common Expression Language (CEL) expression on a role binding; the binding grants its role only while the expression is true. You add one with --condition='expression=EXPR,title=TITLE' on add-iam-policy-binding. The two patterns you meet most are time limits and resource scoping.

• Expiring access: request.time < timestamp("2027-12-31T00:00:00Z"). timestamp() is a point in time; duration() (for example duration("86400s")) is a length of time used in arithmetic with a timestamp, so an expiry is compared against a timestamp, not a bare duration.
• Timestamps are RFC 3339 with an offset. Z means UTC. A non-zero offset moves the cutoff: 2027-12-31T00:00:00+05:00 is 19:00 UTC on 30 December.
• Resource scoping: resource.name.startsWith("...") limits a grant to matching resources. For Cloud Storage objects the resource name has the form projects/_/buckets/BUCKET/objects/OBJECT, so a prefix condition for a folder of objects must include objects/, for example resource.name.startsWith("projects/_/buckets/reports/objects/finance/"). Two prefixes fail in practice: one that leaves out objects/, such as projects/_/buckets/reports/finance/, matches no object at all; and a bucket-only prefix with no trailing slash, such as projects/_/buckets/reports, also matches other buckets whose names start the same way, such as reports-archive. Conditions on Cloud Storage resources also require uniform bucket-level access on the bucket; a bucket that still uses fine-grained ACLs cannot carry conditional bindings.

An expired time condition is not deleted from the policy: the binding stays until someone removes it, it simply grants nothing. It switches off only its own binding; if the same person still holds the role another way, for example through a group binding without a condition, that access continues.

The three role types differ in who defines them, how broad they are, and when you should reach for each.

The basic roles predate modern IAM, and their reach is wider than people expect: Editor grants modify access to nearly all services in the project (but not management of IAM policies), and Owner adds managing IAM and granting roles to others. Billing management is handled separately through billing account roles. Handing a person or a service account Editor to solve a narrow task is the classic least-privilege violation when a predefined role covers the job.

Predefined roles carry a maintenance advantage custom roles never get: when a service launches new permissions, Google updates its predefined roles so holders keep working. A custom role is frozen at the permissions you listed, and you own its upkeep. Reach for a custom role only when least privilege genuinely demands a combination no predefined role offers. To see exactly what a role contains (rather than who holds it), run gcloud iam roles describe roles/storage.objectViewer.

Least privilege usually comes down to choosing between predefined roles with similar names. The deciding question is which resources the job touches and whether it reads, creates or administers them.

Compute Engine

Cloud Storage, Cloud SQL and BigQuery

Each role also has a lowest level it can be granted at. BigQuery is the standard example: data access can be granted on the dataset (or a single table), but the right to run query jobs is granted on the project whose jobs are billed, so an analyst querying one dataset typically needs both grants at their two different levels.

IAM administration roles

Allow policies inherit down the resource hierarchy: a binding on the organization applies to every folder, project and resource beneath it; a binding on a folder applies to all projects inside it; a binding on a project applies to every resource in the project. The effective policy on any resource is the union of the policy set directly on it and every policy inherited from its ancestors.

Inheritance is additive. An allow policy only ever grants, so a lower level cannot narrow what an ancestor granted. If devs@example.com holds roles/editor on the folder, granting the same group roles/viewer on one project inside it changes nothing: the group still holds Editor there. Editing the child project's allow policy can never remove inherited access. The fixes are to change the grant where it was made (for example, replace the folder binding with bindings on only the projects that need it), to change the membership that carries it (move one person out of the group that holds the folder grant and grant them directly where they still need access), or to block specific permissions with a deny policy, described next.

Moving a project to another folder changes what it inherits: bindings on the old folder stop applying the moment the move completes, and the new parent's bindings start applying. The project's own policy travels with it unchanged. Before a move, check that no one depended on the old folder's grants and that the new folder does not grant more than intended.

Every grant has two axes, and both must be right: pick the narrowest role and bind it at the lowest node whose subtree matches the requirement. A correct role on the wrong node still over-grants: a folder binding reaches every current and future project in the folder. Grant high only when the whole subtree needs the access; an organization-wide audit team might hold roles/iam.securityReviewer on the organization, while a contractor auditing one bucket gets roles/storage.objectViewer on that bucket. When a department's twelve projects all need the same access, one binding on the department's folder beats twelve project bindings kept in sync by hand.

An IAM deny policy is a set of deny rules that stop named principals from using specific permissions, whatever their allow policies grant. It is the standard way to take away specific permissions that are granted higher up the hierarchy without changing that grant. (Principal access boundary policies can also limit access, but they work differently: they restrict which resources a set of principals can reach, not which permissions they can use.)

• Permissions, not roles. A deny rule lists the permissions it denies (written in a fully qualified form such as cloudresourcemanager.googleapis.com/projects.delete), the principals it applies to, and optional exception principals.
• Attach points: the organization, a folder or a project only, not individual resources such as buckets. Like allow policies, deny policies are inherited by everything below.
• Evaluated first. IAM checks deny policies before allow policies. If a deny rule applies, the request is refused even for a principal holding Owner; no allow grant overrides a deny.
• Exceptions win within the rule. A principal listed as an exception is not denied by that rule, even if it is also a member of a denied group. That is how you block a permission for "all engineers except the break-glass group".
• Who manages them: creating and editing deny policies needs roles/iam.denyAdmin (Deny Admin), granted on the organization. Project or folder IAM admin roles do not include it.

Use allow-policy design for ordinary least privilege, and keep deny policies for guardrails: blocking a dangerous permission across a folder, or carving one team out of an inherited grant you cannot change.

A custom role is a permission bundle you define when least privilege requires a combination no predefined role offers, for example operators who may start and stop VMs but never create or delete them. Custom roles are created at the project level or the organization level, never at the folder level. A project-level custom role can only be used in bindings within that project; an organization-level role can be used anywhere in the organization, so define shared roles once there rather than cloning them per project. A project-level role also cannot grant permissions that act only at the folder or organization level (for example resourcemanager.organizations.get), because a project has nothing for them to act on.

Create one with gcloud iam roles create vmOperator --project=PROJECT_ID --title="VM Operator" --permissions=compute.instances.start,compute.instances.stop --stage=GA, or from a YAML file with --file; use --organization=ORG_ID for an organization role. Because custom role IDs are scoped, other commands also need the scope: gcloud iam roles describe vmOperator --project=PROJECT_ID. Useful companions: gcloud iam list-testable-permissions RESOURCE lists permissions usable on a resource with their support level, and gcloud iam roles copy clones a role you can then trim.

Permission support levels

Every permission has a custom-role support level. SUPPORTED permissions are fully supported in custom roles. TESTING permissions can be included but are being tested for compatibility and may behave unexpectedly, so avoid them in production roles. NOT_SUPPORTED permissions cannot be included in a custom role at all; they are only available through predefined roles.

Launch stages, disabling and deletion

So DISABLED is the only launch stage that changes enforcement. Update roles with gcloud iam roles update, and remember that Google never adds new permissions to your custom roles: when a service evolves, your role stays as you wrote it.

Scenario: your company has an organization with a retail folder containing the projects retail-prod, retail-staging and retail-dev. The deployment team must manage Compute Engine instances in all three projects; the data science group needs read-only access to one Cloud Storage bucket in retail-prod; and a new platform admin must be able to grant roles across the whole retail estate. How do you set this up without basic roles?

The deployment team needs the same service-specific power in every project under the folder, so bind once at the folder: gcloud resource-manager folders add-iam-policy-binding FOLDER_ID --member=group:deploy@example.com --role=roles/compute.instanceAdmin.v1. Inheritance carries it into all three projects and any future project in the folder. The data science group's need is the narrowest, so bind at the resource itself: roles/storage.objectViewer on the single bucket, not on retail-prod, where it would expose every bucket in the project. The platform admin must edit IAM at two kinds of node: roles/resourcemanager.folderIamAdmin on the folder covers the folder's own policy, and roles/resourcemanager.projectIamAdmin granted on the folder is inherited by every project inside, covering their policies. Neither role grants access to the resources themselves.

The habits embedded here: every grant went to a group, so team changes are membership edits rather than IAM edits; every grant used a predefined role scoped to one job; and every grant landed at the lowest node that satisfies the whole requirement. If the deployment team later needed start/stop only, that is the trigger to define an organization-level custom role and swap the folder binding to it. If one person must lose the folder-wide access but keep it in retail-dev, remove them from deploy@ and grant them directly on retail-dev.

Use this reference to compress the lesson into the facts that decide most IAM scenarios.

A reliable triage for any IAM scenario: identify the principal (prefer a group, use the right prefix), identify the narrowest role that carries the needed permissions (predefined before custom, custom before basic), then identify the lowest attachment point whose subtree matches the requirement. If someone has more access than a project's policy suggests, look for inheritance or a group, and confirm with Policy Troubleshooter. If inherited access must be blocked without changing the grant, that is a deny policy.