Google Cloud offers Identity and Access Management (IAM), which lets
you give more granular access to specific Google Cloud resources and
prevents unwanted access to other resources. IAM lets you adopt the
security principle of least privilege
,
so you grant only the necessary access to your resources.
IAM lets you control
who (users)
has
what access (roles)
to
which
resources
by setting IAM policies. IAM policies grant specific role(s) to a
user giving the user certain permissions.
This page explains the
IAM
roles that
are available at the Folders level, and how to create and manage IAM
policies for folders using the Cloud Resource Manager API. For a detailed
description of IAM, read the
IAM documentation
. In
particular, see
Granting, Changing, and Revoking Access
.
Overview of IAM roles for Folders
To help you configure your IAM roles, the following table lists:
- The type of actions you want to enable
- The roles required to perform those actions
- The resource level on which you need to apply those roles
Type of actions
|
Roles required
|
Resource level
|
Administer folders across the organization resource
|
Folder Admin
|
Organization resource
|
Administer a folder and all projects and folders it contains
|
Folder Admin
|
Specific folder
|
Access and administer a folder's IAM policies
|
Folder IAM Admin
|
Specific folder
|
Create new folders
|
Folder Creator
|
Parent resource for the location of the new folders
|
Move folders and projects
|
Folder Mover
|
Parent resource for both the original folder location and the new folder location
|
Move a project to a new folder
|
Project Editor
or
Project Owner
|
Parent resource for both the original project location and new project location
|
Delete a folder
|
Folder Editor or Folder Admin
|
Specific folder
|
Best practices for using IAM roles and permissions with Folders
When assigning IAM roles and permissions for use with Folders, keep the
following in mind:
- Use groups whenever possible to manage principals.
- Minimize usage of basic roles, such as owner, editor, and viewer. Instead,
try to use the predefined roles for principle of least privilege.
- For folder-wide management, assign permissions at folder level and have
projects inherit them automatically. For example, you could assign a
department administrator group the
Folder Admin
role on the folder.
Network administrators that need to have department-wide permissions can have
the
Network Admin
role for the folder.
- Carefully consider what permissions might change before moving a resource out
of a folder. Otherwise, you could risk breaking existing apps or workflows
that require those permissions on that resource.
- Plan and test your resource hierarchy carefully before moving production
projects under folders. One way to do this is to create a test folder under
your organization resource and creating a prototype of your intended hierarchy
ahead of time.
- Granting a role to a user at the folder level will grant the user that role
for every resource underneath that folder as well. For example, if you grant
a user the Compute Admin role (
roles/compute.admin
) on a folder, that user
will have full control of all Compute Engine resources in every project in
that folder.
Understanding folder roles and permissions
Default roles
When you create a folder, you are granted the
Folder Admin
and
Folder Editor
roles for the folder to provide you full control as the
creator. See below for the permissions that these roles provide. These default
roles can be changed as normal in an IAM policy.
Using predefined roles
Role
|
Permissions
|
Folder Admin
(
roles/
resourcemanager.folderAdmin
)
Provides all available permissions for working with folders.
Lowest-level resources where you can grant this role:
|
essentialcontacts.*
essentialcontacts.
contacts.
create
essentialcontacts.
contacts.
delete
essentialcontacts.contacts.get
essentialcontacts.
contacts.
list
essentialcontacts.
contacts.
send
essentialcontacts.
contacts.
update
orgpolicy.constraints.list
orgpolicy.policies.list
orgpolicy.policy.get
resourcemanager.folders.*
resourcemanager.folders.create
resourcemanager.folders.delete
resourcemanager.folders.get
resourcemanager.
folders.
getIamPolicy
resourcemanager.folders.list
resourcemanager.folders.move
resourcemanager.
folders.
setIamPolicy
resourcemanager.
folders.
undelete
resourcemanager.folders.update
resourcemanager.
hierarchyNodes.*
resourcemanager.
hierarchyNodes.
createTagBinding
resourcemanager.
hierarchyNodes.
deleteTagBinding
resourcemanager.
hierarchyNodes.
listEffectiveTags
resourcemanager.
hierarchyNodes.
listTagBindings
resourcemanager.projects.get
resourcemanager.
projects.
getIamPolicy
resourcemanager.projects.list
resourcemanager.projects.move
resourcemanager.
projects.
setIamPolicy
|
Folder IAM Admin
(
roles/
resourcemanager.folderIamAdmin
)
Provides permissions to administer allow policies on folders.
Lowest-level resources where you can grant this role:
|
resourcemanager.folders.get
resourcemanager.
folders.
getIamPolicy
resourcemanager.
folders.
setIamPolicy
|
Folder Creator
(
roles/
resourcemanager.folderCreator
)
Provides permissions needed to browse the hierarchy and create folders.
Lowest-level resources where you can grant this role:
|
essentialcontacts.contacts.get
essentialcontacts.
contacts.
list
orgpolicy.constraints.list
orgpolicy.policies.list
orgpolicy.policy.get
resourcemanager.folders.create
resourcemanager.folders.get
resourcemanager.folders.list
resourcemanager.projects.get
resourcemanager.projects.list
|
Folder Editor
(
roles/
resourcemanager.folderEditor
)
Provides permission to modify folders as well as to view a folder's allow policy.
Lowest-level resources where you can grant this role:
|
essentialcontacts.contacts.get
essentialcontacts.
contacts.
list
orgpolicy.constraints.list
orgpolicy.policies.list
orgpolicy.policy.get
resourcemanager.folders.delete
resourcemanager.folders.get
resourcemanager.
folders.
getIamPolicy
resourcemanager.folders.list
resourcemanager.
folders.
undelete
resourcemanager.folders.update
resourcemanager.projects.get
resourcemanager.projects.list
|
Folder Mover
(
roles/
resourcemanager.folderMover
)
Provides permission to move projects and folders into and out of a parent
organization or folder.
Lowest-level resources where you can grant this role:
|
resourcemanager.folders.move
resourcemanager.projects.move
|
Folder Viewer
(
roles/
resourcemanager.folderViewer
)
Provides permission to get a folder and list the folders and projects below
a resource.
Lowest-level resources where you can grant this role:
|
essentialcontacts.contacts.get
essentialcontacts.
contacts.
list
orgpolicy.constraints.list
orgpolicy.policies.list
orgpolicy.policy.get
resourcemanager.folders.get
resourcemanager.folders.list
resourcemanager.projects.get
resourcemanager.projects.list
|
Creating custom roles
In addition to the predefined roles described in this topic, you can also create
custom roles
that are collections of
permissions that you tailor to your needs. When creating a custom role for use
with Resource Manager, be aware of the following points:
- List and get permissions, such as
resourcemanager.projects.get/list
,
should always be granted as a pair.
- When your custom role includes the
folders.list
and
folders.get
permissions, it should also include
projects.list
and
projects.get
.
- Be aware that the
setIamPolicy
permission for organization, folder, and
project resources allows the user to grant all other permissions, and so should be assigned with care.
Granting roles to enable folder browsing
List permissions enable folder browsing. The two types of list permissions that
typically need to be granted are
resourcemanager.folders.list
, which allows
users to list folders under a resource, and
resourcemanager.projects.list
,
which allows users to browse projects under an organization resource or folder. The
Organization Administrator is initialized with both of these permissions. For
users that have not been assigned the
Organization Administrator
role:
resourcemanager.folders.list
can be granted via the
Folder Viewer
and
Folder Editor
roles.
resourcemanager.projects.list
can be granted via the
Viewer
or
Browser
roles.
For organization resource principals to browse the entire organization resource hierarchy, list
permissions should be granted at the organization resource level.
Granting roles to enable folder creation
Users that need to create folders must be granted
Folder Creator
role on a
resource in the hierarchy above the level at which the folder will be created.
It can be helpful to grant browsing permissions along with folder creation
permissions so users can effectively navigate to where in the hierarchy the
folder will be created. See the
section above
for
more information on browsing permissions.
Folder Creator
does not grant a user permission to delete a folder. However,
when a person creates a folder, that person is automatically granted the
Folder Editor
role. The
Folder Editor
role enables folder deletion.
Granting roles to enable folder movement
To move a folder from one parent resource to another, users must have
the
Folder Mover
role on both old and new parent resources, or on a common
ancestor.
Granting roles to enable project movement
To move a project into a folder, users must have the
Project Editor
or
Project Owner
roles on the project and the
Project Mover
on both the
source and destination parent resources.
This is slightly different from the requirements for moving a non-org-owned
project into the organization resource, where users must have the
Project Editor
or
Project Owner
role on the project and the
Project Creator
role on
the organization resource.
Granting folder-specific roles to enable project creation
To create projects, users must have the
Project Creator
role.
However, rather than granting org-wide project creation permission, it can be
useful to instead restrict users to viewing and creating projects only within
a given folder.
To grant folder-specific permissions:
- Grant the user the
Organization Viewer
role at the org node level
(for example, domain.com).
- Create a new folder.
- Add the user to IAM at the folder level and grant them the
Folder Viewer
and
Project Creator
roles.
This allows the user to create projects in their folder without granting them
visibility to every project in the greater organization resource.