Roles and permissions

Stay organized with collections Save and categorize content based on your preferences.

This page describes Identity and Access Management (IAM) basic, predefined, and custom 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.ROLE
    • Project-level custom roles: projects/PROJECT_ID/roles/ROLE
    • Organization-level custom roles: organizations/ORG_ID/roles/ROLE

    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. When you grant a role to a principal, the principal gets all of the permissions in the role.

  • 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

There are several basic roles that existed prior to the introduction of IAM: Owner, Editor, and Viewer. These roles are concentric; that is, the Owner role includes the permissions in the Editor role, and the Editor role includes the permissions in the Viewer role. They were originally known as "primitive roles."

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

Basic role definitions

Name Title Permissions
roles/viewer Viewer Permissions for read-only actions that do not affect state, such as viewing (but not modifying) existing resources or data.
roles/editor Editor All viewer permissions, plus permissions for actions that modify state, such as changing existing resources.
Note: The Editor role contains permissions to create and delete resources for most Google Cloud services. However, it does not 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.
roles/owner Owner All Editor permissions and permissions for the following actions:
  • Manage roles and permissions for a project and all resources within the project.
  • Set up billing for a project.
Note:
  • Granting the Owner role at a resource level, such as a Pub/Sub topic, doesn't grant the Owner role on the parent project.
  • Granting the Owner role at the organization level doesn't allow you to update the organization's metadata. However, it allows you to modify all projects and other resources under that organization.
  • 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.

You can grant basic roles using the Google Cloud console, the API, and the gcloud CLI. See Granting, changing, and revoking access for instructions.

To see how to grant roles using the Google Cloud console, 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

Any user with the correct permissions can create a custom role. Custom roles are granted in the same way as predefined and basic roles.

To learn more about custom roles, see Understanding IAM custom roles and Creating and managing custom roles.

What's next