Resources in Google Cloud are organized into ahierarchy, with each node (Organizations,Folders, Projects, and so forth) having a reference to its parent. You can usethat reference as a key filter term for scans to improve the consistency ofresource searches.
You can grant users permissions usingcustom roles. These roles operate on theprinciple of least privilege, and generally provide only the minimum necessarypermissions required to do a particular task.
This scheme can be useful for isolating different user groups. For example:
- A large company with departments that shouldn't be able to inspect theresources of their peers.
- Contractors who are given permissions to a specific Project, but no otherresources.
As a result of their restricted permissions, however, custom roles may causemany resources in your hierarchy to be omitted when executing a list operation.When performing searches as a user that has been granted a custom role, it canbe difficult to tell why certain resources are not appearing.
To avoid this scenario, this page discusses the best practices for listing allof the resources managed by the Cloud Resource Manager API in your resource hierarchy. Youcan use this guidance to configure custom audit checks, or to create your ownuser experience on top of the Cloud Resource Manager API.
List all resource nodes
When you scan your resource hierarchy to list every resource, you need stronglyconsistent results. If your scan misses resources or provides outdated results,it can be hard to tell that something has gone wrong. To make sure that youalways get the most accurate and complete results, use a service account andperform a scan in the following way:
- Grant a service account the
listandgetpermissions for Organizations,Folders, and Projects on the Organization resource. - If you are listing Project and Folder resources, specify the parent resourcein the filter string.
- Run theprojects.list() methodwith this service account for each type of resource you want to find, andfor any intermediate resources such as Folders.
Example to list all resource nodes
The following pseudocode demonstrates how to list every resource node in yourOrganizations:
organizations = organizations.search()projects = emptyList()parentsToList = queueOf(organizations)while (parent = parentsToList.pop()) { // TODO: Iterate over paginated results as needed. // TODO: Handle PERMISSION_DENIED appropriately. projects.addAll(projects.list(parent.type, parent.id)) parentsToList.addAll(folders.list(parent))}When building a custom user experience, you may also want to mix in searchresults and load the parent resources as needed (while also catching thePERMISSION_DENIED exception).
Reduce latency on gcloud projects list
If your gcloud projects list query fails or takes too long, the number ofGoogle Cloud projects to return might be too large. To fix this, apply thefilter and page-size flags to your gcloud projects list command.
To learn more about the flags you can add to your gcloud projects list command,see gcloud projects list.
Exclude Apps Script projects example
The most common cause of query failures or latency is a high number of AppsScript projects within an organization. The following command shows how to excludeApps Script projects from the projects list and limit the number of resourcesreturned per page.
gcloud projects list --filter="NOT parent.id: 'APPS_SCRIPT_FOLDER_ID' "--page-size='30'Get the Apps Script folder ID
To find your Apps Script folder ID, take the following steps.
In the toolbar of the Google Cloud console, clickSearch for resources, docs, products, and more and type
apps-script.Go to Google Cloud console
Under Resources select the apps-script folder.
Under Folder ID copy the folder ID.
Search resources
If your scan is intended to search for a resource that was created some timeago, you can perform a faster scan that has eventual consistency rather thanstrong consistency. Note that this search method may omit some resources fromthe search result, particularly any resources that have been changed recently.To search for resources:
- Use a service account that has the
getpermission for the resource you aresearching for. - Run theprojects.search()method with this service account.
Troubleshooting omitted resources
If you are developing a scanning tool, we recommend that you use list andget permissions granted at the Organization level. This avoids issues causedby the user having partial permissions, which results in some resources beingomitted from the list.
If you are designing a custom user experience that checks user permissions,there is no easy solution. If a user does not have Organization-levelpermissions, they will need certain permissions on every resource for it toappear. If a user is missing permissions on a resource somewhere in thehierarchy, some resources may not appear.
If a user has the list permission but not the get permission for aparticular resource, that resource won't be visible at all in theGoogle Cloud console. However, the resource will be returned in a search using theAPI or Google Cloud CLI that specifies the resource's parent. This disparitybetween the Google Cloud console and other methods is a common source of confusionwhen trying to scan the resource hierarchy.
The following diagrams demonstrate some common configurations of permissions,and how they change what resources are visible to a user running a search.
In this example, all required permissions are granted in the Organizationresource. Therefore, the entire hierarchy is visible when performing a list orsearch.
The user in this example has all required permissions except forresourcemanager.organizations.get, but they are granted those permissions atthe Folder level. This permissions gap gives them full visibility on list orsearch of that part of the hierarchy, but not the other half.
This example shows the experience of a user with only theresourcemanager.projects.get permission granted at the Folder resource level.They are able to see the Projects underneath that Folder in the hierarchy, butonly by searching. Using the list functionality will not return any results.
This example shows the same issue as above, where the granted permissions onlyallow a user to find their Folder resources by searching. Using the listfunctionality will not return any results.
The user in this example has a mix of permissions throughout their Organization.They can list folders from the Organization level, which allows them to findthem with searches that specify the parent resource throughout the hierarchy.They can list Project resources for one Folder, but not the other, and they haveresourcemanager.projects.get permission on one Project at the bottom of thehierarchy.
The result is that they aren't able to return the Projects on the left side ofthis resource hierarchy. They can list the Projects on the right side only byusing a search that specifies the parent resource, and only one Project isvisible when viewed in the Google Cloud console.
In this example, the user can get the Organization resource and list Projectresources by specifying the parent throughout the hierarchy. However, they donot have permission to list or search any of the intermediate Folders. TheirProjects are searchable if the user happens to know the ID of its parentFolder. The Folders are not visible at all to this user, and so they will not beable to discover the ID if they don't already have it. The only resource thatwill appear in the Google Cloud console is the Organization.
When designing your custom user experience, it's important to be aware ofsituations similar to the above. You can use a combination of listing andsearching to render the resource hierarchy. You should also consider how tocommunicate to users that they are missing permissions that would allow them tosee the whole resource hierarchy.
