Identity and Access Management (IAM) provides predefined roles that give fine-grained access to specific Google Cloud resources and help prevent unwanted access to other resources.
IAM also lets you create custom IAM roles. Custom roles help you enforce the principle of least privilege, because they help to ensure that the principals in your organization have only the permissions that they need.
Consider creating a custom role in the following situations:
- A principal needs a permission, but each predefined role that includes that permission also includes permissions that the principal does not need and should not have.
- You use role recommendations to replace overly permissive role grants with more appropriate role grants. In some cases, you might receive a recommendation to create a custom role.
Some IAM permissions are not supported in custom roles. To check whether a specific permission is supported, see Support level for permissions in custom roles.
Before you begin
- Read the overview of IAM.
- Read about IAM predefined roles.
- Understand best practices for implementing the principle of least privilege.
In IAM, you don't directly grant permissions. Instead, you grant roles, which contain one or more permissions. There are several kinds of roles in IAM: basic roles, predefined roles, and custom roles.
Basic roles include three roles that existed prior to the introduction of IAM: Owner, Editor, and Viewer.
Predefined roles are created and maintained by Google. Google automatically updates their permissions as necessary, such as when Google Cloud adds new features or services.
Custom roles are user-defined, and allow you to bundle one or more supported permissions to meet your specific needs. Custom roles are not maintained by Google; when new permissions, features, or services are added to Google Cloud, your custom roles will not be updated automatically.
When you create a custom role, you must choose an organization or project to create it in. You can then grant the custom role on the organization or project, as well as any resources within that organization or project.
You create a custom role by combining one or more of the available IAM permissions. Permissions allow users to perform specific actions on Google Cloud resources. In the IAM world, permissions are represented in the form:
For example, the
compute.instances.list permission allows a user
to list the Compute Engine instances they own, and
allows a user to stop a VM. When you add a permission to a custom role, you must
specify the service, resource, and verb explicitly—you cannot use
wildcard characters (
Permissions usually, but not always, correspond 1:1 with REST methods. That is,
each Google Cloud service has an associated permission for each
REST method that it has. To call a method, the caller needs that permission.
For example, the caller of
topic.publish() needs the
When you create a custom role at the project level, the custom role cannot
contain permissions that are only available at the folder or organization level.
For example, you cannot use the
in a project-level custom role, because a project cannot contain other projects;
as a result, the permission is only useful at the folder or organization level.
You can only grant a custom role within the project or organization in which you created it. You cannot grant custom roles on other projects or organizations, or on resources within other projects or organizations.
Required permissions and roles
To create a custom role, a caller must have the
Users who are not owners, including organization administrators, must be
assigned either the Organization Role Administrator role
roles/iam.organizationRoleAdmin) or the IAM Role Administrator role
roles/iam.roleAdmin). The IAM Security Reviewer role
roles/iam.securityReviewer) enables the ability to view custom roles but not
administer them. To learn how to grant these roles, see Granting, changing, and
The custom roles user interface is in the Google Cloud console under IAM Roles. It is only available to users who have permissions to create or manage custom roles. By default, only project owners can create new roles. Project owners can control access to this feature by granting IAM Role Administrator role to others on the same project; for organizations, only Organization Administrators can grant the Organization Role Administrator role.
The administrative roles are described in more detail below.
Organization Role Administrator role
If you have an organization associated with your Google Cloud account, the Organization Role Administrator role enables you to administer all custom roles in your organization. This role can only be granted at the organization level. Only Organization Administrators can grant the Organization Role Administrator role.
The following table lists the permissions in the Organization Role Administrator role:
Role Administrator role
The Role Administrator role enables you to administer all custom roles for a project. Use this role if you do not have an organization. This role can only be granted at the project level by project or organization owners.
The following table lists the permissions in the Role Administrator role:
Custom roles lifecycle
There are a few concepts that apply when deciding how to model, create, and manage your custom roles.
Before you decide to create a custom role, check whether the service has a predefined role—or a combination of multiple predefined roles—that meets your needs. For a complete list of predefined roles, as well as the permissions that are included in each predefined role, see the predefined roles reference.
If there is no predefined role—or combination of predefined roles—that meets your needs, you can create a custom role that includes only the permissions you need to grant. For details, see Creating and managing custom roles.
Unsupported or unavailable permissions
You can include many, but not all, IAM permissions in custom roles. Each permission has one of the following support levels for use in custom roles:
||The permission is fully supported in custom roles.|
||Google is testing the permission to check its compatibility with custom roles. You can include the permission in custom roles, but you might see unexpected behavior. Not recommended for production use.|
||The permission is not supported in custom roles.|
Some permissions might not be visible to you or usable in a custom role, even if they are supported in custom roles. For example, a permission might not be available for use in custom roles if you have not enabled the API for the service. Also, if you're creating a project-level custom role, you can't use organization-level permissions in the role.
To check whether you can use a specific permission in custom roles, see Support level for permissions in custom roles. To check which permissions you can use with a specific resource, see Viewing the available permissions for a resource.
Some permissions are effective only when granted in pairs. For example, to
update an allow policy, you must use the read-modify-write
pattern. As a result, to update an allow policy, you almost always need the
getIamPolicy permission for that service and resource type, in addition to the
To make sure your custom roles are effective, you can create custom roles based on predefined roles with similar permissions. The predefined roles can help you see which permissions are typically used in combination.
To learn how to create a custom role based on a predefined role, see Creating and managing custom roles.
Naming the role
Roles have both an ID and a title. The role ID is a unique identifier for the role. The role title appears in the list of roles in the Google Cloud console.
Role IDs must be unique within the project or organization in which you created the role. This ensures that the role's full ID, which includes its project or organization, is unique. Role IDs can be up to 64 characters long and can contain uppercase and lowercase alphanumeric characters, underscores, and periods.
You cannot change role IDs, so choose your role IDs carefully. You can delete a custom role, but you can't create a new custom role with the same full ID until after the 44-day deletion process has completed. For more information about the deletion process, see Deleting a custom role.
The title for a custom role does not have to be unique. Therefore, the Google Cloud console could display more than one custom role with the same title. To avoid confusion, use unique and descriptive titles for your custom roles. Also, consider indicating in the role title if the role is an organization-level role or a project-level role.
Role titles can be up to 100 bytes long and can contain uppercase and lowercase alphanumeric characters and symbols. You can change role titles at any time.
Consider updating the role description after editing a custom role, and include both the date it was modified and a summary of the intended purpose for the role. Descriptions can be up to 256 characters long and can contain uppercase and lowercase alphanumeric characters and symbols.
Testing and deploying
Custom roles include a launch stage, which is stored in the
stage property for
the role. The most common launch stages for active custom roles are
GA. These launch stages are informational; they help you keep
track of whether each role is ready for widespread use. Another common launch
DISABLED. This launch stage lets you disable a custom
We recommend that you use the
GA launch stages to convey
the following information about the role:
ALPHA: The role is still being developed or tested, or it includes permissions for Google Cloud services or features that are not yet public. It is not ready for widespread use.
BETA: The role has been tested on a limited basis, or it includes permissions for Google Cloud services or features that are not generally available.
GA: The role has been widely tested, and all of its permissions are for Google Cloud services or features that are generally available.
For a full list of possible launch stages, see the role reference.
To learn how to change a role's launch stage, see Editing an existing custom role.
Job functions and product functionality are constantly evolving. Keeping custom roles up-to-date and following the principle of least privilege requires maintenance effort.
For example, when a released service gets new Beta features, those API methods become publicly available and the permissions are automatically added to the corresponding basic and predefined roles. Your custom roles for that service do not inherit those new permissions, so users assigned to those custom roles might report that they cannot access the new Beta features. At that point, you could choose to add them, or perhaps create a separate custom role to only grant certain users access to those Beta features.
While Google might update an existing predefined role by adding (or removing) permissions, we do not modify custom roles based on the predefined roles. Custom roles are flat lists of permissions; a custom role has no link to the predefined roles it might have been based on.
If your custom role is based on any predefined roles, we recommend listing those roles in the custom role's description field. Doing this makes it easier for you to check whether you should update your custom role based on changes to a predefined role. The Google Cloud console automatically puts that information in the description when it creates a new custom role.
To learn how to update a custom role's permissions and description, see Editing an existing custom role.
Refer to the permissions change log to determine what roles and permissions have changed recently.
Disable custom roles
If you no longer want people in your organization to use a custom role, you can
disable the role. To disable the role, change its launch stage to
When a role is disabled, all role bindings that grant the role are inactivated, meaning that granting the role to a user has no effect.
To learn how to disable a custom role, see disabling a custom role.
- Some predefined roles contain permissions that are not permitted in custom roles. To check whether you can use a specific permission in a custom role, see Support level for permissions in custom roles.
- Custom roles can contain up to 3,000 permissions. Also, the maximum total size of the title, description, and permission names for a custom role is 64 KB.
resourcemanager.projects.listpermission is only supported for organization-level custom roles—it is not permitted in project-level custom roles. When you copy a predefined role that includes the
resourcemanager.projects.listpermission into a new project-level custom role, one of the following messages will be displayed:
- Google Cloud console: The following warning message is displayed:
"Not applicable for project-level custom roles". The
resourcemanager.projects.listpermission will be automatically unselected from the list of included permissions, and you can proceed with creating the role.
- gcloud CLI Google Cloud CLI: The following error message is
INVALID_ARGUMENT: Permission resourcemanager.projects.list is not valid. The custom role will not be created until you first remove the
resourcemanager.projects.listpermission from the role definition and try the operation again.
- Google Cloud APIs: The following error message is returned:
Permission resourcemanager.projects.list is not valid, along with an HTTP 400 error code and a status of
INVALID_ARGUMENT. The custom role will not be created until you first remove the
resourcemanager.projects.listpermission from the role definition and try the operation again.
- Google Cloud console: The following warning message is displayed: "Not applicable for project-level custom roles". The
- Learn how to create custom roles.
- Further enforce least privilege with role recommendations, which lets you safely downscope your principals' permissions.