Cloud Identity and Access Management (Cloud IAM) provides predefined roles that give granular access to specific Google Cloud Platform resources and prevent unwanted access to other resources.
Cloud IAM also provides the ability to create customized Cloud IAM roles. You can create a custom Cloud IAM role with one or more permissions and then grant that custom role to users. Cloud IAM provides a UI and API for creating and managing custom roles.
This topic does not provide a comprehensive list of all the Cloud IAM permissions you can include in your custom roles. To check whether a specific permission is supported in custom roles, see Support Level for Permissions in Custom Roles. To read about custom roles for a specific service, see the More IAM documentation section.
Before you begin
- Read the IAM Overview of basic Cloud IAM concepts.
- Read about the available IAM predefined roles.
- Understand the IAM best practices for least privilege.
In Cloud IAM, you don't directly grant users permissions. Instead, you grant them roles, which bundle one or more permissions. There are three kinds of roles in Cloud IAM: primitive roles, predefined roles, and custom roles.
Primitive roles include three roles that existed prior to the introduction of Cloud IAM: Owner, Editor, and Viewer.
Predefined roles are created and maintained by Google. Their permissions are automatically updated as necessary, such as when new features or services are added to GCP.
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 GCP, your custom roles will not be updated automatically.
You create a custom role by combining one or more of the available Cloud IAM permissions. Permissions allow users to perform specific actions on Google Cloud Platform resources. In the Cloud IAM world, permissions are represented in the form:
For example, the
compute.instances.list permission allows a user
to list the Google Compute Engine instances they own, while
compute.instances.stop allows a user to stop a VM.
Permissions usually, but not always, correspond 1:1 with REST methods. That is,
each GCP 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
Custom roles can only be used to grant permissions in policies for the same project or organization that owns the roles or resources under them. You cannot grant custom roles from one project or organization on a resource owned by a different project or organization.
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
The custom roles user interface is in the Google Cloud Platform 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 GCP 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, make sure that there is not already an existing predefined role (or set of roles) for the service that meets your needs. You can learn about the permissions applicable to a specific service by following the links in the More IAM documentation section. For a list of the permissions contained in a predefined role, see Getting the role metadata.
If the set of permissions granted with one or more predefined roles is not right for you, you should create a custom role that is based off of one or more predefined roles, and add or delete permissions from it as necessary. The details about how to do this can be found in Creating and Managing Custom Roles.
Unsupported or unavailable permissions
You should also be aware that some permissions may not be visible to you or useable in a custom role. For example, a permission may not be available for use in custom roles if the service is in Beta, or if you have not enabled the API for the service.
The following Cloud IAM permissions are not supported in custom roles:
To see what permissions are supported in a custom role for a given GCP service, refer to this table.
Some permissions are only effective when granted in pairs.
For example, since updating Cloud IAM policies requires using the
setIamPolicy almost always requires using the
getIamPolicy so that
you can obtain the etag before updating a policy.
Naming the role
The ID for a custom role must be unique. It can be up to 64 characters long and comprised of uppercase and lowercase alphanumeric characters, underscores, and periods.
The title for a custom role does not have to be unique. Therefore, the GCP Console could display more than one custom role with the same title. To avoid confusion, use unique and descriptive titles for your custom roles. Titles can be up to 100 characters long and comprised of uppercase and lowercase alphanumeric characters and symbols. Role titles can be changed at any time.
Choose the ID of your role carefully, because it cannot be changed. You can delete a role, but you can't create a new custom role with the same ID until after the 37-day deletion process has completed. For more information about the deletion process, see Deleting a custom role.
The role title is what is displayed in the GCP Console. Choose unambiguous titles to prevent confusion for users selecting custom roles in the GCP Console. Also consider indicating which roles are organization-level vs. project-level by putting that information in the role title.
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 comprised of uppercase and lowercase alphanumeric characters and symbols.
Testing and deploying
Custom roles include a
role.stage property. Initially, set the stage to
ALPHA to indicate that the role is in early development and not ready for
production. Then, allow a small set of members of your organization to use
the role in a few sample use cases.
When the members are happy with the newly created custom role, change the
role.stage property to
GA. In general, if your custom role
references permissions for services that are in Beta, you should mark it
GA, until the service is out of Beta.
Job functions and product functionality are constantly evolving. Keeping custom roles up-to-date and assigned the least privileges necessary 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 primitive and predefined roles. Your custom roles for that service do not inherit those new permissions, so users assigned to those custom roles may 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 may 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; there is no link to the predefined role(s) it may have been based on.
We recommend adding these details to the description field for an existing custom role to make it easier to review whether recent changes to predefined roles warrant updates to your custom role. The GCP Console automatically puts that information in the description when creating a new custom role.
Refer to the IAM Permissions Change Log to determine what permissions have changed recently.
Disabling Custom Roles
If you no longer wish for people in the your organization to use the role,
role.stage property to
DEPRECATED, and optionally set the
deprecation_message to let users know what alternative roles should be used or
where to get more information. You should also make sure that you don't have any
policies in your organization that might still be referencing the deprecated
When you're sure that the role can be disabled, call
disable this role.
Some predefined roles contain deprecated permissions or permissions that are otherwise not permitted in custom roles. A custom role that is based on a predefined role that contains deprecated or restricted permissions will not contain those permissions. See the Support Level for Permissions in Custom Roles topic for a complete list of all supported permissions.
Custom roles created within a project can't list other projects. 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:
- GCP 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.
- Cloud SDK gcloud command-line tool: 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.
- GCP Console: The following warning message is displayed: "Not applicable for project-level custom roles". The
More IAM documentation
|Cloud IAM for App Engine||Explains Cloud IAM roles for App Engine|
|Cloud IAM for BigQuery||Explains Cloud IAM roles for BigQuery|
|Cloud IAM for Cloud Bigtable||Explains Cloud IAM roles for Cloud Bigtable|
|Cloud IAM for Cloud Billing API||Explains Cloud IAM roles and permissions for Cloud Billing API|
|Cloud IAM for Cloud Dataflow||Explains Cloud IAM roles for Cloud Dataflow|
|Cloud IAM for Cloud Dataproc||Explains Cloud IAM roles and permissions for Cloud Dataproc|
|Cloud IAM for Cloud Datastore||Explains Cloud IAM roles and permissions for Cloud Datastore|
|Cloud IAM for Cloud DNS||Explains Cloud IAM roles and permissions for Cloud DNS|
|Cloud IAM for Cloud KMS||Explains Cloud IAM roles and permissions for Cloud KMS|
|Cloud IAM for AI Platform||Explains Cloud IAM roles and permissions for AI Platform|
|Cloud IAM for Cloud Pub/Sub||Explains Cloud IAM roles for Cloud Pub/Sub|
|Cloud IAM for Cloud Spanner||Explains Cloud IAM roles and permissions for Cloud Spanner|
|Cloud IAM for Cloud SQL||Explains Cloud IAM roles for Cloud SQL|
|Cloud IAM for Translation||Explains Cloud IAM roles for Translation|
|Cloud IAM for Cloud Storage||Explains Cloud IAM roles for Cloud Storage|
|Cloud IAM for Compute Engine||Explains Cloud IAM roles for Compute Engine|
|Cloud IAM for GKE||Explains Cloud IAM roles and permissions for GKE|
|Cloud IAM for Deployment Manager||Explains Cloud IAM roles and permissions for Deployment Manager|
|Cloud IAM for Organizations||Explains Cloud IAM roles for Organization.|
|Cloud IAM for Folders||Explains Cloud IAM roles for folders.|
|Cloud IAM for Projects||Explains Cloud IAM roles for projects.|
|Cloud IAM for Service Management||Explains Cloud IAM roles and permissions for Service Management|
|Cloud IAM for Stackdriver Debugger||Explains Cloud IAM roles for Debugger|
|Cloud IAM for Stackdriver Logging||Explains Cloud IAM roles for Logging|
|Cloud IAM for Stackdriver Monitoring||Explains Cloud IAM roles for Monitoring|
|Cloud IAM for Stackdriver Trace||Explains Cloud IAM roles and permissions for Trace|