Understanding IAM Custom Roles

Give Feedback on the Custom Roles Alpha

Google 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 who are part of your organization. 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. Learn about the permissions you can apply to a specific service using the links in the More IAM documentation section.

Before you begin

Basic concepts

You don't directly grant users permissions. Instead, you grant them roles, which bundle one or more permissions. Predefined roles are created by Google and we maintain with the most up-to-date permissions required for new features and other changes. Custom roles allow you to bundle one or more of the available permissions to specifically meet your needs. You can create a custom role at the organization level and at the project level.

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:

`<service>.<resource>.<verb>`

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 Cloud Platform service has an associated set of permissions for each REST method that it has. To call a method, the caller needs those permissions. For example, the caller of topic.publish() needs the pubsub.topics.publish permission.

Custom roles can only be created for project-wide or organization-wide use. They cannot be created at the folder level.

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 iam.roles.create permission.

Users who are not owners, including organization administrators, must be assigned either the Organization Role Administrator role, or the IAM Role Administrator role. The IAM Security Reviewer role (roles/iam.securityReviewer) enables the ability to view custom roles but not administer them.

The custom roles user interface is in the 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 Permissions
roles/iam.organizationRoleAdministrator iam.roles.create
iam.roles.delete
iam.roles.undelete
iam.roles.get
iam.roles.getIamPolicy
iam.roles.setIamPolicy
iam.roles.list
iam.roles.update
resourcemanager.projects.get
resourcemanager.projects.getIamPolicy
resourcemanager.projects.list
resourcemanager.organizations.get
resourcemanager.organizations.getIamPolicy

IAM Role Administrator role

The IAM 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.

The following table lists the permissions in the IAM Role Administrator role:

Role Permissions
roles/iam.roleAdmin iam.roles.create
iam.roles.delete
iam.roles.undelete
iam.roles.get
iam.roles.list
iam.roles.update
iam.roles.getIamPolicy
iam.roles.setIamPolicy
resourcemanager.projects.get
resourcemanager.projects.getIamPolicy

Custom roles lifecycle

There are a few concepts that apply when deciding how to model, create, and manage your custom roles.

Creation

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.

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.

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.

Permission dependencies

Some permissions are only effective when granted in pairs. For example, since updating IAM policies requires using the Read-Modify-Write pattern, setIamPolicy almost always requires using the getIamPolicy so that you can obtain the etag before updating a policy.

Also, to ensure that the Google Cloud Console works as expected, be aware that you need to grant permissions for resourcemanager.projects.get and resourcemanager.projects.list at the appropriate levels. In general, you should grant list permission on the parent resource, and get permission on the child resource.

Naming the role

The ID for a custom role must be unique, but the name property does not have to be.

Therefore, the console could display more than one custom role with the same name. To avoid confusion, use unique and descriptive names for your custom roles.

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 7-day waiting period during which the deleted role can be un-deleted.

The role name is what is displayed in the console. Choose unambiguous names to prevent confusion for users selecting custom roles in the Console. Also consider indicating which roles are organization-level vs. project-level by putting that in the role name. The role name can be changed at any time.

Role description

Always update the role description after editing a custom role, to at least reflect the date it was modified and a summary of the intended job role.

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 BETA or GA. In general, if your custom role references permissions for services that are in Beta, you should mark it BETA, not GA until they are out of Beta.

Maintenance

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 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. Since 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 that sort of information to the Description field, so it’s easier to review whether more recent changes to Predefined roles warrant updates. In the Alpha release, the Cloud Console automatically puts that information in the Description when creating a new custom role.

Disabling Custom Roles

If you no longer wish for people in the your organization to use the role, change its 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 role.

When you're sure that the role can be disabled, call roles:UpdateRole() to disable this role.

Alpha restrictions

Functionality limitations

  • You can create and grant custom roles at the organization or project level. You can also grant a custom role at any level below a project. For example, you can grant the role to a user for an organization, a project, or a resource under the project, such as a Google Compute Engine instance.

  • No more than 300 custom roles can be created at the project or organization level. When a role is marked for deletion, it is not completely deleted for 7 days to allow for undeletion. Roles in this "soft deleted" state count against the 300 limit so that undeletion will not fail due to lack of space to reinstate the role.

Reliability expectations

  • This is an Alpha release. Don't use this feature for production workloads. Please consult with your account manager on your testing plans for further updates.

  • The API and the UI for custom roles is subject to change.

Known Issues

  • 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.

  • Custom roles created within a project can't list other projects. When you copy a predefined role that includes the resourcemanager.projects.list permission into a new custom role, that permission is removed and the following message is displayed:

    • Cloud Platform Console: Forbidden Permissions
    • Cloud SDK gcloud command-line tool: not valid

What's next

More IAM documentation

Documentation Description
IAM Overview Explains the basic concepts of IAM.
Understanding Roles Explains primitive and curated IAM roles.
IAM for Organizations Explains IAM roles and permissions for the Organizations.
IAM for Projects Explains IAM roles and permissions for projects.
IAM for App Engine Explains IAM roles and permissions for App Engine.
IAM for Compute Engine Explains IAM roles and permissions for Compute Engine.
IAM for Cloud Storage Explains IAM roles and permissions for Cloud Storage.
IAM for Cloud BigQuery Explains IAM roles and permissions for Cloud BigQuery.
IAM for Cloud Bigtable Explains IAM roles and permissions for Cloud Bigtable.
IAM for Stackdriver Logging Explains IAM roles and permissions for Stackdriver Logging.
IAM for Cloud Pub/Sub Explains IAM roles and permissions for Cloud Pub/Sub.
IAM for Cloud Dataflow Explains IAM roles and permissions for Cloud Dataflow.
IAM for Stackdriver Debugger Explains IAM roles and permissions for Stackdriver Debugger.
IAM for Cloud Deployment Manager Explains IAM roles and permissions for Cloud Deployment Manager.
IAM for Cloud Datastore Explains IAM roles and permissions for Cloud Datastore.
IAM for Cloud Dataproc Explains IAM roles and permissions for Cloud Dataproc.
IAM for Google Container Engine Explains IAM roles and permissions for Google Container Engine.
IAM for Cloud DNS Explains IAM roles and permissions for Cloud DNS.
IAM for Google Genomics Explains IAM roles and permissions for Google Genomics.
IAM for Stackdriver Trace Explains IAM roles and permissions for Stackdriver Trace.
IAM for Cloud Billing API Explains IAM roles and permissions for Cloud Billing API.
IAM for Service Management Explains IAM roles and permissions for Service Management.

Send feedback about...

Cloud Identity and Access Management Documentation