Using resource hierarchy for access control

Google Cloud resources are organized hierarchically, where the organization node is the root node in the hierarchy, the projects are the children of the organization, and the other resources are descendants of projects. You can set allow policies at different levels of the resource hierarchy. Resources inherit the allow policies of the parent resource. The effective allow policy for a resource is the union of the allow policy set at that resource and the allow policy inherited from its parent.

This page describes some examples of how allow policy inheritance works and explains the best practices that you must take into consideration when you create resources during Identity and Access Management (IAM) deployment.

Prerequisites

Background

The following diagram shows an example of a Google Cloud resource hierarchy.

From top to bottom, the hierarchy includes organizations, folders, projects, and service-specific resources.

IAM lets you set allow policies at the following levels of the resource hierarchy:

  • Organization level. The organization resource represents your company. IAM roles granted at this level are inherited by all resources under the organization. For more information, see Access control for organizations using IAM.

  • Folder level. Folders can contain projects, other folders, or a combination of both. Roles granted at the highest folder level will be inherited by projects or other folders that are contained in that parent folder. For more information, see Access control for folders using IAM.

  • Project level. Projects represent a trust boundary within your company. Services within the same project have a default level of trust. IAM roles granted at the project level are inherited by resources within that project. For more information, see Access control for projects using IAM.

  • Resource level. In addition to the existing Cloud Storage and BigQuery ACL systems, additional resources such as Pub/Sub topics and Compute Engine instances support lower-level roles so that you can grant certain users permission to a single resource within a project.

Allow policies are hierarchical and propagate down the structure. The effective allow policy for a resource is the union of the allow policy set at that resource and the allow policy inherited from its parent.

The following examples explain how allow policy inheritance works in practice.

Example: Pub/Sub

In Pub/Sub, topics and subscriptions are resources that live under a project. Assume that project_1 has a topic topic_a under it. If you set an allow policy on project_1 that grants the Editor role to Kalani, and set an allow policy on topic_a that grants the Publisher role to Nur, you effectively grant the Editor role to Kalani and the Publisher role to Nur for topic_a.

The following diagram illustrates the preceding example.

Pub/Sub example.

If an inherited role already gives a principal all of the permissions that they need, then you don't need to grant them additional roles on the resource itself. Granting another role that contains the same or fewer permissions is redundant, and doesn't have any effect.

For example, consider the basic roles Owner, Editor, and Viewer. These roles are concentric; that is, the Owner role includes the permissions in the Editor role, and the Editor role includes the permissions of the Viewer role. As a result, if you grant Kalani the Editor role at the project level, then granting them the Viewer role on topic_a is redundant. This is because Kalani already has all of the permissions in the Viewer role through the Editor role, which is inherited from the project's allow policy.

The following diagram illustrates the preceding example.

Pub/Sub example.

Example: Cloud Storage

In Cloud Storage, buckets and objects are resources, and objects are located in buckets. An example of using IAM with Cloud Storage is to allow read access to files that are uploaded.

Consider a scenario where many users upload files to a bucket, but they shouldn't be able to read or delete any of the files uploaded by other users. Your data processing expert should be able to read and delete uploaded files, but they shouldn't be able to delete buckets because others are using the bucket location to upload their files. In this scenario, you would set allow policies on the project as follows:

  • Grant the Storage Object Admin role (roles/storage.objectAdmin) to your data processing expert, Nur. This role lets Nur read, add, and delete any object in any bucket in the project.
  • Grant the Storage Object Creator role (roles/storage.objectCreator) to the data-uploaders group. This role lets group members upload files to the bucket, but doesn't let them read or delete any files that other users upload.

The following diagram illustrates the preceding example.

Cloud Storage example.

Example: Compute Engine

In larger companies, the management of network and security resources such as firewalls are typically managed by a dedicated team, which is different from the development team. The development teams might want the flexibility to launch instances and carry out other actions related to instances in their projects.

In a situation like this, you could configure your allow policies as follows:

  • Grant the Compute Network Admin role (roles/compute.networkAdmin) to your network and security administrator, Kalani, at the organization level. This role lets Kalani make changes to the network resources in the organization and in any projects under that organization.
  • Grant the Compute Instance Admin role (roles/compute.instanceAdmin) to a development team lead, Nur, on their project project_2. This role lets Nur carry out any actions on their instances while preventing them from making any changes to the network resources associated with their project. However, it doesn't let them make changes to network resources in other projects.

Compute Engine example.

Permissions for viewing inherited policies

To view IAM policies that are inherited from a parent resource, you need permission to view the parent resource's IAM policy. For example, to view all inherited IAM policies for a project, you need permission to view the IAM policy of the project's parent organization and to view the IAM policies of any parent folders.

To get the permissions that you need to view IAM policies that are inherited from parent resources, ask your administrator to grant you the following IAM roles:

  • View an IAM policy that is inherited from an organization: Organization Administrator (roles/resourcemanager.organizationAdmin) on the organization
  • View an IAM policy that is inherited from a folder: Folder Admin (roles/resourcemanager.folderAdmin) on the folder
  • View an IAM policy that is inherited from a project: Project IAM Admin (roles/resourcemanager.projectIamAdmin) on the project

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to view IAM policies that are inherited from parent resources. To see the exact permissions that are required, expand the Required permissions section: