Note: You can now usedeny 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, wherethe organization node is the root node in the hierarchy, the projects are thechildren of the organization, and the other resources are descendants ofprojects. You can set allow policies at different levels of the resourcehierarchy. Resources inherit the allow policies of the parent resource. Theeffective allow policy for a resource is the union of the allow policy set atthat resource and the allow policy inherited from its parent.

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

Prerequisites

• Understand thebasic conceptsof IAM, in particular theGoogle Cloud resource hierarchy.

Background

The following diagram shows an example of a Google Cloud resourcehierarchy.

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

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

• Folder level. Folders can contain projects, other folders, or acombination of both. Roles granted at the highest folder level will beinherited by projects or other folders that are contained in that parentfolder. For more information, seeAccess 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 byresources within that project. For more information, seeAccess control forprojects usingIAM.

• Resource level. In addition to the existing Cloud Storage andBigQuery ACL systems, additional resources such as Pub/Subtopics and Compute Engine instances support lower-levelroles so that you can grant certain users permission to a single resourcewithin a project.

Allow policies are hierarchical and propagate down the structure. The effectiveallow policy for a resource is the union of the allow policy set at thatresource 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 undera project. Assume thatproject_1 has a topictopic_a under it. If you set anallow policy onproject_1 that grants the Editor role to Kalani, and set anallow policy ontopic_a that grants the Publisher role to Nur, you effectivelygrant the Editor role to Kalani and the Publisher role to Nur fortopic_a.

The following diagram illustrates the preceding example.

If an inherited role already gives a principal all of the permissions that theyneed, 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 areconcentric; 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, ifyou grant Kalani the Editor role at the project level, then granting them theViewer role ontopic_a is redundant. This is because Kalani already has all ofthe permissions in the Viewer role through the Editor role, which is inheritedfrom the project's allow policy.

The following diagram illustrates the preceding example.

Example: Cloud Storage

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

Consider a scenario where many users upload files to a bucket, but theyshouldn'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 bucketlocation to upload their files. In this scenario, you would set allow policieson the project as follows:

• Grant theStorage Object Adminrole(roles/storage.objectAdmin) to your data processing expert, Nur. This rolelets Nur read, add, and delete any object in any bucket in the project.
• Grant theStorage Object Creatorrole(roles/storage.objectCreator) to thedata-uploaders group. This rolelets group members upload files to the bucket, but doesn't let them read ordelete 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 asfirewalls are typically managed by a dedicated team, which is different from thedevelopment team. The development teams might want the flexibility to launchinstances 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 theCompute Network Adminrole(roles/compute.networkAdmin) to your network and security administrator,Kalani, at the organization level. This role lets Kalani make changes to thenetwork resources in the organization and in any projects under thatorganization.
• Grant theCompute Instance Adminrole(roles/compute.instanceAdmin) to a development team lead, Nur, on theirprojectproject_2. This role lets Nur carry out any actions on theirinstances while preventing them from making any changes to the networkresources associated with their project. However, it doesn't let them makechanges to network resources in other projects.

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. Forexample, to view all inherited IAM policies for a project, youneed permission to view the IAM policy of the project's parentorganization and to view the IAM policies of any parent folders.

To get the permissions that you need to view IAM policies that are inherited fromparent 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, seeManage access to projects, folders, and organizations.

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

Required permissions

The following permissions are required to view IAM policies that are inherited fromparent 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 withcustom roles or otherpredefined roles.

Note: In the Google Cloud console, a resource's IAM page onlyshows inherited roles if the roles aregrantable on theresource.

Best practices

• Mirror your Google Cloud resource hierarchy structure to yourorganization structure. The Google Cloud resource hierarchy shouldreflect how your company is organized, whether it's a startup, a SME, or alarge corporation. A startup may start out with a flat resource hierarchy withno organization resource. When more people start collaborating on projects andthe number of projects increase, getting an organization resource might makesense. An organization resource is recommended for larger companies withmultiple departments and teams where each team is responsible for their ownset of applications and services.

• Use projects to group resources that share the same trust boundary. Forexample, resources for the same product or microservice can belong to the sameproject.

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

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

• Use the security principle ofleast privilegeto grant IAM roles; that is, only give the least amount ofaccess necessary to your resources.

  To find the appropriate predefined role,see thepredefined roles reference. If there are noappropriate predefined roles, you can also create your owncustom roles.

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

• Remember that the allow policies for child resources inherit from the allowpolicies for their parent resources. For example, if the allow policy for aproject grants a user the ability to administer Compute Engine virtualmachine (VM) instances, then the user can administer anyCompute Engine VM in that project, regardless of the allow policy youset 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 group thatcontains at least two principals.

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

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

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

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

• Audit the ownership and the membership of the groups used inallow policies.

• If you want to limit project creation in your organization, change theorganization access policyto grant theProject Creator roleto a group that you manage.