Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 45 ยท Identity and Security

IAM: Principals, Roles and Policies

Understand Google Cloud IAM: principals, roles, permissions, allow policy bindings, inheritance and conditions, with a policy evaluator you can run.

Identity and Access Management (IAM) answers one question for every request to Google Cloud: who is allowed to do what on which resource? Every click in the console and every gcloud command passes through IAM before anything happens. Understanding it early saves you from both of the usual failures: "permission denied" on things you should be able to do, and far too much access given to people and programs.

The core idea is small. You never attach permissions directly to a person. You attach a role (a bundle of permissions) to a principal (a person, group or program) at a certain level of the hierarchy, and that attachment is called a binding. A list of bindings on a resource is its allow policy.

The three parts of a grant

Who, what, where

Principal The identity asking, such as a user, group or service account.
Role A named bundle of permissions.
Resource The organization, folder, project or single resource.

A binding connects them. This principal has this role here.

1 / 2

Principals

A principal is an identity. Common kinds are:

  • A Google Account such as user:[email protected].
  • A service account, an identity for a program: serviceAccount:[email protected] (see Service Accounts and Credentials).
  • A Google group: group:[email protected]. Granting roles to groups instead of individuals is the best habit you can build, because people join and leave groups without anyone editing policies.
  • A domain: domain:example.com for everyone in a Workspace or Cloud Identity domain.
  • The special values allUsers (anyone on the internet) and allAuthenticatedUsers (anyone signed in to any Google account). Treat these with great care: they are how public buckets happen.

Permissions and roles

A permission allows one narrow action. Names follow service.resource.verb, for example storage.objects.get or compute.instances.delete. You do not grant permissions directly. You grant roles, which hold lists of permissions. There are three kinds:

Kind Example Notes
Basic roles/viewer, roles/editor, roles/owner Very broad across all services. Fine for experiments, a poor choice for production.
Predefined roles/storage.objectViewer Maintained by Google for one product and a job. The normal choice.
Custom organizations/123/roles/auditReader You pick the permissions. Covered in Least Privilege and Organization Policies.

Role names tell you the product and the job: roles/storage.objectViewer reads objects, roles/storage.objectAdmin also writes and deletes them.

Allow policies and bindings

An allow policy is a list of bindings. In its JSON form it looks like this (shown read-only; you would fetch it with gcloud projects get-iam-policy):

JSON
{
  "bindings": [
    {
      "role": "roles/storage.objectViewer",
      "members": ["group:[email protected]", "user:[email protected]"]
    },
    {
      "role": "roles/compute.instanceAdmin.v1",
      "members": ["group:[email protected]"]
    }
  ],
  "etag": "BwYX...",
  "version": 3
}

Granting access from the command line adds one member to one role:

Terminal
gcloud projects add-iam-policy-binding my-project-id \
  --member="user:[email protected]" \
  --role="roles/storage.objectViewer"

Under the hood, IAM reads the current policy, adds the binding, and writes it back. The etag field prevents two people from overwriting each other's changes at the same moment. You can also set a policy on a single resource, such as one bucket, which is a much narrower grant than a whole project.

Inheritance: policies flow downward

Resources form a hierarchy (see Projects and the Resource Hierarchy): organization, then folders, then projects, then individual resources. An allow policy on a parent applies to everything below it. The effective access of a principal is the union of the bindings at every level.

flowchart TD
  O["Organization<br/>group:security: Security Reviewer"] --> F["Folder: Production"]
  F --> P["Project: shop-prod<br/>user:ana: Storage Object Viewer"]
  P --> B["Bucket: shop-prod-images"]

Ana can read objects in the bucket because of the project binding, and the security group can review it because of the organization binding.

Two consequences follow. First, an allow policy can only add access, never remove what a parent granted, so a broad role at the top cannot be cancelled further down. (Google Cloud also has separate deny policies for explicit exceptions, but the common case is allow only.) Second, grant at the lowest level that works: a role on one bucket beats the same role on the project, which beats the organization.

Conditions

A binding can carry a condition, an expression that must be true for the role to apply. Conditions use a small expression language called CEL and can look at the time, the resource name or its type. This is useful for temporary access or for limiting a role to resources with a certain name prefix:

JSON
{
  "role": "roles/storage.objectViewer",
  "members": ["user:[email protected]"],
  "condition": {
    "title": "expires-end-of-quarter",
    "expression": "request.time < timestamp(\"2027-01-01T00:00:00Z\")"
  }
}

If the condition is false, the binding behaves as if it were not there.

A stand-in policy evaluator

The model below checks a request against bindings at several levels. It has a tiny role table (invented for the demo, with a few real-looking permission names), inheritance by walking up a resource path, and one kind of condition (an expiry time). The real IAM engine does much more: groups are expanded for you, there are deny policies, and role contents are Google's.

JS Stand-in: does this request pass IAM?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that bob is allowed to read through a binding made at the organization level, and that nothing in the lower levels can take that away. Change the dates or add a binding to watch the result flip.

Next, a smaller drill: finding which roles contain a permission, which is what you do when you hit "permission denied".

JS Stand-in: which role gives this permission?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Sorting by size is a rough stand-in for least privilege: pick the smallest role that contains what you need. Real predefined roles are documented per product, and the console's IAM page shows what a role includes.

Practical habits

  • Grant to groups, not individual people.
  • Prefer predefined roles at the smallest scope that works. Avoid roles/owner and roles/editor in production.
  • When something fails with PERMISSION_DENIED, the error names the missing permission. Find a role that holds it and grant that, instead of reaching for Owner.
  • Review policies regularly: gcloud projects get-iam-policy PROJECT_ID shows who has what.
  • Changes can take a few minutes to take effect, so do not retry a hundred times in a loop.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a binding in an allow policy?

    A binding says which principals hold which role (optionally with a condition) at the level where the policy is attached.
  2. 2. A group has Storage Object Viewer on the organization. Can a project-level policy remove that access?

    Effective access is the union of bindings up the hierarchy. Removing inherited access needs a change at the parent, or a separate deny policy.
  3. 3. Why is granting roles to Google groups preferred over granting to individuals?

    When someone joins or leaves a team, you change the group's membership and every policy that uses the group updates automatically.
  4. 4. Which principal value means anyone on the internet?

    allUsers includes unauthenticated visitors. allAuthenticatedUsers is anyone with any Google account, which is also very broad.

Summary

  • IAM decides who can do what on which resource; you grant roles to principals through bindings.
  • Roles are bundles of permissions: basic (broad), predefined (the normal choice) or custom.
  • Policies inherit downward and add up; grant at the lowest useful level.
  • Conditions limit a binding by time, resource name or similar.
  • Prefer groups and predefined roles, and be careful with allUsers.

Next: Service Accounts and Credentials