Using Resource Hierarchy for Access Control

Cloud Platform 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 the children of Projects. You can set IAM policies at different levels of the resource hierarchy. Resources inherit the policies of the parent resource. The effective policy for a resource is the union of the policy set at that resource and the policy inherited from its parent.

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

Prerequisites

Background

The following diagram shows an example of a Cloud Platform resource hierarchy:

Resource Hierarchy

IAM allows you to set 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.

  • Project level. Projects represent a trust boundary within your company. Services within the same project have a default level of trust. For example, App Engine instances can access Cloud storage buckets within the same project. IAM roles granted at the project level are inherited by resources within that project.

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

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

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

Example: Cloud Pub/Sub

In Cloud Pub/Sub, topics and subscriptions are resources that live under a project. Assume that project_a has a topic topic_a under it. If you set a policy on project_a that grants the editor role to bob@gmail.com, and set a policy on topic_a that grants the publisher role to alice@gmail.com, you effectively grant the editor role to bob@gmail.com and the publisher role to alice@gmail.com for topic_a.

The following diagram illustrates the example above:

Pub/Sub example

The owner, editor, and viewer 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. If you grant both the broader and limited role (such as editor and the viewer) to the same person, only the broader role is granted to them. For example, if you grant the editor role to bob@gmail.com at the project level and grant the viewer role to bob@gmail.com for topic_a, Bob is granted the editor role for topic_a. This is because you’ve already granted Bob the editor role for topic_a, which is inherited from the policy set on project_a.

The following diagram illustrates the example above:

Pub/Sub example

Example: Google Cloud Storage

In Google Cloud Storage, buckets and objects are resources, where buckets are the containers that hold the objects. A use case for using IAM with Cloud storage is to allow read access to files that have been uploaded.

Consider a scenario where you have a number of people who upload files to a bucket, but they must not be able to read or delete any of the files uploaded by other people. Your data processing expert must be able to read and delete any of the uploaded data but not be able to delete buckets because others might have the bucket location as a target to upload their data files.

Assume that project_a has a bucket called upload_here. If you set a policy on project_a that grants Storage Object Admin to alice@example.com and grants Storage Object Creator to the group data_uploaders@example.com. This effectively means that anyone who is a member of the group data_uploaders@example.com can upload files to the bucket but not read or delete any files uploaded. Alice has object admin rights at the project level and can read, add and delete any object in any bucket in project_a.

The following diagram illustrates the example above:

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 may want the flexibility to launch instances and carry out other actions related to instances in their projects. Granting bob@example.com the Compute Network Admin role at the organization level and alice@example.com the Compute Instance Admin role on her project project_2 allows Alice to carry out any actions on instances while preventing her from making any changes to the network resources associated with her project. Only Bob can make changes to the network resources in the organization and to any projects under that organization.

Cloud Storage example

Best practices

  • Mirror your IAM policy hierarchy structure to your organization structure. The IAM policy hierarchy should reflect how your company is organized, be it a startup, a SME, or a large corporation. A startup may start out with a flat policy hierarchy with no Organization resource . When more people start collaborating on projects and the number of projects increase, getting an Organization resource might make sense. An Organization resource is recommended for larger companies with multiple departments and teams where each team is responsible for their own set of applications and services.

  • Use Cloud Platform projects to group resources that share the same trust boundary. For example, resources for the same product or microservice can belong to the same Cloud Platform project.

  • Set policies at the Organization level and at the Project level rather than at the resource level. This is because as new resources gets added, you may want them to automatically inherit policies from their parent resource. For example, as new Virtual Machines gets added to the project through auto scaling, they automatically inherit the policy on the project.

  • Use the security principle of least privilege to grant IAM roles, that is, only give the least amount of access necessary to your resources.

  • Grant roles to a Google group instead of to individual users when possible. It is easier to add members to and remove members from a Google group instead of updating a Cloud IAM policy to add or remove users.

  • Control the ownership of the Google group used in IAM policies.

  • Grant roles at the smallest scope needed. For example, if a user only needs access to publish messages to a Pub/Sub topic, grant the Publisher role to the user for that topic.

  • Remember that a policy set on a child resource cannot restrict access granted on its parent. Check the policy granted on every resource and understand the hierarchical inheritance.

  • If you need to grant a role to a user or group that spans across multiple projects, set that role at the organization level instead of setting it at the project level.

  • Use labels to annotate, group, and filter resources.

  • Audit your policies to ensure compliance. Cloud audit logs contain all the calls to setiampolicy so you are able to trace when a policy has been enacted.

  • Audit the ownership and the membership of the Google groups used in policies.

  • If you want to limit project creation in your Organization, change the Organization access policy to grant the Project Creator role to a group that you manage.

Send feedback about...

Cloud Identity and Access Management Documentation