Roles and permissions

This page describes Identity and Access Management (IAM) roles, which are collections of IAM permissions.

A role contains a set of permissions that allows you to perform specific actions on Google Cloud resources. To make permissions available to principals, including users, groups, and service accounts, you grant roles to the principals.

Before you begin

Role types

There are three types of roles in IAM:

  • Basic roles, which include the Owner, Editor, and Viewer roles that existed prior to the introduction of IAM.
  • Predefined roles, which provide granular access for a specific service and are managed by Google Cloud.
  • Custom roles, which provide granular access according to a user-specified list of permissions.

To determine if a permission is included in a basic, predefined, or custom role, you can use one of the following methods:

Role components

Each role has the following components:

  • Title: A human-readable name for the role. The role title is used to identify the role in the Google Cloud console.

  • Name: An identifier for the role in one of the following formats:

    • Predefined roles: roles/SERVICE.IDENTIFIER
    • Project-level custom roles: projects/PROJECT_ID/roles/IDENTIFIER
    • Organization-level custom roles: organizations/ORG_ID/roles/IDENTIFIER

    The role name is used to identify the role in allow policies.

  • ID: A unique identifier for the role. For basic and predefined roles, the ID is the same as the role name. For custom roles, the ID is everything after roles/ in the role name.

  • Description: A human-readable description of the role.

  • Stage: The stage of the role in the launch lifecycle, such as ALPHA, BETA, or GA. To learn more about launch stages, see Testing and deploying.

  • Permissions: The permissions included in the role. Permissions allow principals to perform specific actions on Google Cloud resources. When you grant a role to a principal, the principal gets all of the permissions in the role.

    Permissions have the following format:

    SERVICE.RESOURCE.VERB

    For example, the compute.instances.list permission allows a user to list the Compute Engine instances they own, and compute.instances.stop allows a user to stop a VM.

    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 the associated permission. For example, to call the Pub/Sub API's projects.topics.publish method, you need the pubsub.topics.publish permission.

  • ETag: An identifier for the version of the role to help prevent concurrent updates from overwriting each other. Basic and predefined roles always have the ETag AA==. ETags for custom roles change each time you modify the roles.

Basic roles

Basic roles are highly permissive roles that existed prior to the introduction of IAM. They were originally known as primitive roles. You can use basic roles to grant principals broad access to Google Cloud resources.

When you grant a basic role to a principal, the principal gets all of the permissions in the basic role. They also get any permissions that services provide to principals with basic roles—for example, permissions gained through Cloud Storage convenience values and BigQuery special group membership.

The following table summarizes the permissions that the basic roles give users across all Google Cloud services:

Basic roles Permissions
Viewer (roles/viewer)

Permissions for read-only actions that don't affect state, such as viewing (but not modifying) existing resources or data.

For a list of permissions in the Viewer role, see the role details in the Google Cloud console:

Go to Viewer role

Editor (roles/editor)

All viewer permissions, plus permissions for actions that modify state, such as changing existing resources.

The permissions in the Editor role let you create and delete resources for most Google Cloud services. However, the Editor role doesn't contain permissions to perform all actions for all services. For more information about how to check whether a role has the permissions that you need, see Role types on this page.

For a list of permissions in the Editor role, see the role details in the Google Cloud console:

Go to Editor role

Owner (roles/owner)

All Editor permissions, plus permissions for actions like the following:

  • Completing sensitive tasks, like creating App Engine applications
  • Managing roles and permissions for a project and all resources within the project
  • Setting up billing for a project

The Owner role doesn't contain all permissions for all Google Cloud resources. For example, it doesn't contain permissions to modify your Cloud Billing payment information or create IAM deny policies.

For a list of permissions in the Owner role, see the role details in the Google Cloud console:

Go to Owner role

You can grant basic roles using the Google Cloud console, the API, and the gcloud CLI. However, to grant the Owner role on a project to a user outside of your organization, you must use the Google Cloud console, not the gcloud CLI. If your project is not part of an organization, you must use the Google Cloud console to grant the Owner role.

For instructions, see Granting, changing, and revoking access.

Predefined roles

In addition to the basic roles, IAM provides additional predefined roles that give granular access to specific Google Cloud resources. These roles are created and maintained by Google. Google automatically updates their permissions as necessary, such as when Google Cloud adds new features or services.

You can grant multiple roles to the same user, at any level of the resource hierarchy. For example, the same user can have the Compute Network Admin and Logs Viewer roles on a project, and also have the Pub/Sub Publisher role on a Pub/Sub topic within that project. To list the permissions contained in a role, see Getting the role metadata.

For help choosing the most appropriate predefined roles, see Choose predefined roles.

For a list of predefined roles, see the roles reference.

Custom roles

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.

Custom roles are user-defined, and allow you to bundle one or more supported permissions to meet your specific needs. 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 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.

You create a custom role by combining one or more of the supported IAM permissions.

Supported 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:

Support level Description
SUPPORTED The permission is fully supported in custom roles.
TESTING 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.
NOT_SUPPORTED The permission is not supported in custom roles.

An organization-level custom role can include any of the IAM permissions that are supported in custom roles. A project-level custom role can contain any supported permission except for permissions that can only be used at the organization or folder level.

The reason that you can't include folder-specific and organization-specific permissions in project-level roles is that they don't do anything when granted at the project level. This is because resources in Google Cloud are organized hierarchically. Permissions are inherited through the resource hierarchy, meaning that they are effective for the resource and all of that resource's descendants. However, organizations and folders are always above projects in the Google Cloud resource hierarchy. As a result, you'll never be able to use a permission that you were given at the project level to access folders or organizations. As a result, folder-specific and organization-specific permissions—for example, resourcemanager.folders.list—are ineffective for project-level custom roles.

When to use custom roles

In most situations, you should be able to use predefined roles instead of custom roles. Predefined roles are maintained by Google, and are updated automatically when new permissions, features, or services are added to Google Cloud. In contrast, custom roles are not maintained by Google; when Google Cloud adds new permissions, features, or services, your custom roles will not be updated automatically.

However, you might want to create 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 doesn't need and shouldn't 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.

Also be aware of the following limits:

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

  • There are limits to the number of custom roles you can create:

    • You can create up to 300 organization-level custom roles in your organization
    • You can create up to 300 project-level custom roles in each project in your organization.

Permission dependencies

Some permissions are effective only when given together. For example, to update an allow policy, you must read the policy before you can modify and write it. 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 setIamPolicy permission.

To make sure your custom roles are effective, you can create custom roles based on predefined roles with similar permissions. Predefined roles are designed with specific tasks in mind and contain all of the permissions you need to accomplish those tasks. Reviewing these roles can help you see which permissions are usually granted together. Then, you can use that information to design effective custom roles.

To learn how to create a custom role based on a predefined role, see Creating and managing custom roles.

Custom roles lifecycle

The following sections describe key considerations at each phase of a custom role's lifecycle. You can use this information to inform how you create and manage your custom roles.

Creation

When you're creating a custom role, choose an ID, title, and description that help you identify the role:

  • Role ID: The role ID is a unique identifier for the role. It can be up to 64 bytes long and can contain uppercase and lowercase alphanumeric characters, underscores, and periods. You can't reuse a role ID within an organization or project.

    You can't change role IDs, so choose them carefully. You can delete a custom role, but you can't create a new custom role with the same ID in the same organization or project until after the 44-day deletion process has completed. For more information about the deletion process, see Deleting a custom role.

  • Role title: The role title appears in the list of roles in the Google Cloud console. The title doesn't have to be unique, but we recommend using unique and descriptive titles to better distinguish your roles. Also, consider indicating in the role title if the role was created at the organization level or the project level.

    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.

  • Role description: The role description is an optional field where you can provide additional information about a role. For example, you could include the role's intended purpose, the date a role was created or modified, and any predefined roles that the custom role is based on. Descriptions can be up to 300 bytes long and can contain uppercase and lowercase alphanumeric characters and symbols.

Also keep permission dependencies in mind when creating custom roles.

To learn how to create a custom role based on a predefined role, see Creating and managing custom roles.

Launch

Custom roles include a launch stage as part of the role's metadata. The most common launch stages for custom roles are ALPHA, BETA, and GA. These launch stages are informational; they help you keep track of whether each role is ready for widespread use. Another common launch stage is DISABLED. This launch stage lets you disable a custom role.

We recommend that you use launch stages to convey the following information about the role:

  • EAP or 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.
  • DEPRECATED: The role is no longer in use.

To learn how to change a role's launch stage, see Editing an existing custom role.

Maintenance

You are responsible for maintaining custom roles. This includes updating roles as your users' responsibilities change, as well as updating roles to let users access new features that require additional permissions.

If you base your custom role on predefined roles, we recommend routinely checking those predefined roles for permission changes. Tracking these changes can help you decide when and how to update your custom role. For example, you might notice that a predefined role was updated with permissions to use a new Preview feature, and might decide to add those permissions to your custom role as well.

To make it easier to see which predefined roles to monitor, we recommend listing any predefined roles that your custom role is based on in the custom role's description field. The Google Cloud console does this automatically when you use the Google Cloud console to create a custom role based on predefined roles.

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.

Disabling

If you no longer want any principals in your organization to use a custom role, you can disable the role. To disable the role, change its launch stage to DISABLED.

Disabled roles still appear in your IAM policies and can be granted to principals, but they don't have any effect.

To learn how to disable a custom role, see disabling a custom role.

What's next