Using resource hierarchy for access control

Note: You can now use deny policies to prevent principals from using some permissions. Using deny policies might cause the features described on this page to work differently.

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

• Understand the basic concepts of IAM, in particular the Google Cloud resource hierarchy.

Background

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

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. 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. 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 Genomics Datasets, 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 [e-mail], and set an allow policy on topic_a that grants the Publisher role to [e-mail], you effectively grant the Editor role to [e-mail] and the Publisher role to [e-mail] for topic_a.

The following diagram illustrates the preceding 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 [e-mail] at the project level and grant the Viewer role to [e-mail] 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 allow policy set on project_a.

The following diagram illustrates the preceding 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 to your data processing expert, Alice at [e-mail].
  • Alice has object admin rights at the project level and can read, add, and delete any object in any bucket in the project.
• Grant Storage Object Creator to a group of users, [e-mail].
  • This allow policy means that anyone who is a member of the group [e-mail] can upload files to the bucket.
  • A group member owns files that they upload, but they can't read or delete any files that other users upload.

The following diagram illustrates the preceding 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 [e-mail] the Compute Network Admin role at the organization level and [e-mail] the Compute Instance Admin role on her project project_2 lets Alice 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.

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:

Required permissions

The following permissions are required to view IAM policies that are inherited from parent resources:

• View an IAM policy that is inherited from an organization: resourcemanager.organizations.getIamPolicy on the organization
• View an IAM policy that is inherited from a folder: resourcemanager.folders.getIamPolicy on the folder
• View an IAM policy that is inherited from a project: resourcemanager.projects.getIamPolicy on the project

You might also be able to get these permissions with custom roles or other predefined roles.

Note: In the Google Cloud console, a resource's IAM page only shows inherited roles if the roles are grantable on the resource.

Best practices

• Mirror your Google Cloud resource hierarchy structure to your organization structure. The Google Cloud resource hierarchy should reflect how your company is organized, whether it's a startup, a SME, or a large corporation. A startup may start out with a flat resource 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 projects to group resources that share the same trust boundary. For example, resources for the same product or microservice can belong to the same project.

• Grant roles to a Google group instead of to individual users when possible. It is easier to manage members in a Google group than to update an allow policy. Make sure to control the ownership of the Google group used in allow policies.

  For more information about how to manage Google groups, see Google Groups help.

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

  To find the appropriate predefined role, see the predefined roles reference. If there are no appropriate predefined roles, you can also create your own custom roles.

• 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 the allow policies for child resources inherit from the allow policies for their parent resources. For example, if the allow policy for a project grants a user the ability to administer Compute Engine virtual machine (VM) instances, then the user can administer any Compute Engine VM in that project, regardless of the allow policy you set on each VM.

• On every project, ensure that at least two principals have the Owner role (roles/owner). Alternatively, grant the Owner role to a Google group that contains at least two principals.

  This practice helps ensure that if one of the principals leaves your company, you still have a way to manage your project.

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

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

• Audit your allow policies to ensure compliance. Audit logs contain all setIamPolicy() calls, so you can trace when an allow policy has been created or modified.

• Audit the ownership and the membership of the Google groups used in allow 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.