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

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

Before you begin

• Understand thebasic concepts of IAM.

Role types

There are three types of roles in IAM:

• Basic roles, which provide broad access to Google Cloud resources.
• Predefined roles, which provide granular access for a specific service andare managed by Google Cloud.
• Custom roles, which provide granular access according to a user-specifiedlist of permissions.

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

• View the role in the Google Cloud console.

  Go to Roles

• Run thegcloud iam roles describecommand.

• Get the role using the appropriate REST API method:

  • For predefined roles, useroles.get().
  • For project-level custom roles, useprojects.roles.get().
  • For organization-level custom roles, useorganizations.roles.get().

• For basic and predefined roles only: Search thepermissionsreference to see if the permission is granted by the role.

• For predefined roles only: Search thepredefined roledescriptions to see whichpermissions the role includes.

For guidance on when to use specific role types, seeChoose which type of roleto use.

Role components

Each role has the following components:

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

• Name: An identifier for the role in one of the followingformats:

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

• ID: A unique identifier for the role. For basic andpredefined roles, the ID is the same as the role name. For custom roles, theID is everything afterroles/ in the role name.

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

• Stage: The stage of the role in the launch lifecycle, such asALPHA,BETA, orGA. To learn more about launch stages, seeTesting and deploying.

• Permissions: The permissions included in the role. Permissions allowprincipals to perform specific actions on Google Cloud resources. When yougrant a role to a principal, the principal gets all of the permissions in therole.

  Permissions have the following format:

  SERVICE.RESOURCE.VERB

  For example, thecompute.instances.list permission allows a user to listthe Compute Engine instances they own, andcompute.instances.stop allowsa user to stop a VM.

  Permissions usually, but not always, correspond 1:1 with REST methods. Thatis, each Google Cloud service has an associated permission for eachREST method that it has. To call a method, the caller needs the associatedpermission. For example, to call the Pub/Sub API'sprojects.topics.publish method, you need thepubsub.topics.publishpermission.

• ETag: An identifier for the version of the role to helpprevent concurrent updates from overwriting each other. Basic and predefinedroles always have the ETagAA==. ETags for custom roles change each time youmodify the roles.

Basic roles

Preview — the Reader, Writer, and Admin basic roles

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Basic roles are highly permissive roles that give broad access toGoogle Cloud resources.

Caution: Basic roles include thousands of permissions across all Google Cloud services. In productionenvironments, do not grant basic roles unless there is no alternative. Instead, grant the mostlimitedpredefined roles orcustom roles that meet your needs.

The basic roles in IAM are Admin (roles/admin), Writer(roles/writer), and Reader (roles/reader). IAM also has threelegacy basic roles that existed prior to the introduction of IAM:Owner (roles/owner), Editor (roles/editor), and Viewer(roles/viewer). To learn more about these roles, seeLegacy basicroles on this page.

The following table summarizes the permissions that the Admin, Writer, andReader give principals across all Google Cloud services:

Note:Cloud Storageconvenience values andBigQuery special groupmembership don't give permissions toprincipals with the Admin, Writer, or Reader roles.

Basic role	Permissions
Reader (roles/reader)	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 Reader role, see the role details in the Google Cloud console: Go to Reader role
Writer (roles/writer)	All of the permissions in the Reader role,plus permissions for actions that modify state, such as changing existing resources. The permissions in the Writer role let you create and delete resources for most Google Cloud services. However, the Writer 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, seeRole types on this page. For a list of permissions in the Writer role, see the role details in the Google Cloud console: Go to Writer role
Admin (roles/admin)	All of the permissions in the Writer role,plus permissions for actions like the following: Completing sensitive tasks, like managing tag bindings for Compute Engine resources Managing roles and permissions for a project and all resources within the project Setting up billing for a project The Admin roledoesn'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 Admin role, see the role details in the Google Cloud console: Go to Admin role

You can't use the Google Cloud console to grant the Reader, Writer, or Adminroles. Instead, use the API or the gcloud CLI. You can also createentitlements for these roles usingPrivileged Access Manager.

For instructions, seeGranting, changing, and revokingaccess.

Legacy basic roles

Legacy basic roles existed prior to the introduction of IAM.They were originally known asprimitive roles. Unlike with other basicroles, you can't addconditions to role bindings for legacybasic roles.

The legacy basic roles are Owner (roles/owner), Editor (roles/editor), andViewer (roles/viewer).

When you grant a legacy basic role to a principal, the principal gets all of thepermissions in the role. The principal also gets any permissions thatservices provide to principals with legacy basic roles—for example,permissions gained throughCloud Storageconvenience values andBigQuery specialgroup membership.

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

Legacy basic role	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, seeRole 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 managing tag bindings for Compute Engine resources Managing roles and permissions for a project and all resources within the project Setting up billing for a project The Owner roledoesn'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

Generally, you can grant legacy basic roles using the Google Cloud console,the API, or the gcloud CLI. However, you must use theGoogle Cloud console to grant the Owner role in the following situations:

• The user that you're granting the Owner role to isn't part of yourorganization.
• The project that you're granting the Owner role on isn't part of anyorganization.

Additionally, you can only grant the Owner role to the following types ofprincipals:

• Google Accounts
• Service accounts in your organization
• Google groups in your organization

To learn how to grant roles, seeGranting, changing, and revokingaccess.

Predefined roles

In addition to the basic roles, IAM provides additionalpredefined roles that give granular access to specific Google Cloudresources. These roles are created and maintained by Google. Googleautomatically updates their permissions as necessary, such as whenGoogle Cloud adds new features or services.

You can grant multiple roles to the same user, at any level of the resourcehierarchy. For example, the same user can have the Compute Network Admin andLogs Viewer roles on a project, and also have the Pub/Sub Publisher role on aPub/Sub topic within that project. To list the permissions contained ina role, seeGetting the role metadata.

For help choosing the most appropriate predefined roles, seeFind the right predefined roles.

For a list of predefined roles, see therolesreference.

Custom roles

IAM also lets you createcustom IAM roles.Custom roles help you enforce the principle of least privilege, because theyhelp to ensure that the principals in your organization have only thepermissions that they need.

Custom roles are user-defined, and allow you to bundle one or more supportedpermissions to meet your specific needs. When you create a custom role, you mustchoose an organization or project to create it in. You can then grant the customrole on the organization or project, as well as any resources within thatorganization or project. You can only create 300per organization and 300 per project.

You can only grant a custom role within the project or organization in which youcreated it. You cannot grant custom roles on other projects or organizations,or on resources within other projects or organizations.

Note: You cannot define custom roles at the folder level. If you need to use a custom role within a folder, define the custom role at the organization level.

You create a custom role by combining one or more of the supportedIAM permissions. To learn how to create a custom role,seeCreate and manage custom roles.

Caution: You should only allow a small number of highly trusted principals toedit custom roles. If a principal can edit custom roles in a project ororganization, they can add any permission to any custom role in that project ororganization. As a result, if you grantany custom role to the principal, theycan use the custom role to get unlimited access.

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.

To see a full list of the permissions that are supported in custom roles, seeSupport levels for permissions in customroles.

An organization-level custom role can include any of the IAMpermissions that are supported in custom roles. A project-level custom role cancontain any supported permissionexcept for permissions that can only be usedat the organization or folder level.

The reason that you can't include folder-specific and organization-specificpermissions in project-level roles is that they don't do anything when grantedat the project level. This is because resources in Google Cloud areorganized hierarchically. Permissions are inherited through the resourcehierarchy, meaning that they are effective for the resource and all of thatresource's descendants. However, organizations and folders are always aboveprojects in theGoogle Cloud resource hierarchy. As a result, you'll never be able to usea permission that you were given at the project level to access folders ororganizations. As a result, folder-specific and organization-specificpermissions—for example,resourcemanager.folders.list—areineffective for project-level custom roles.

Permission dependencies

Some permissions are effective only when given together. For example, toupdate an allow policy, you must read the policy before you can modifyand write it. As a result, to update an allow policy, you almost always need thegetIamPolicy permission for that service and resource type, in addition to thesetIamPolicy permission.

To make sure your custom roles are effective, you can create custom roles basedon predefined roles with similar permissions. Predefined roles are designed withspecific tasks in mind and contain all of the permissions you need to accomplishthose tasks. Reviewing these roles can help you see which permissions areusually granted together. Then, you can use that information to design effectivecustom roles.

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

Custom roles lifecycle

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

Creation

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

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

  You can't change role IDs, so choose them carefully. You can delete a customrole, but you can't create a new custom role with the same ID in the sameorganization or project until after the 44-daydeletion process has completed. For more information about the deletionprocess, seeDeleting a custom role.

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

  Role titles can be up to 100 bytes long andcan contain uppercase and lowercase alphanumeric characters and symbols. Youcan change role titles at any time.

• Role description: The role description is an optional field where you canprovide additional information about a role. For example, you could includethe role's intended purpose, the date a role was created or modified, and anypredefined roles that the custom role is based on. Descriptions can be up to300 bytes long and can containuppercase and lowercase alphanumeric characters and symbols.

Also keeppermission dependencies inmind when creating custom roles.

To learn how to create a custom role based on a predefined role, seeCreatingand managing custom roles.

Launch

Custom roles include a launch stage as part of the role's metadata. The mostcommon launch stages for custom roles areALPHA,BETA, andGA. Theselaunch stages are informational; they help you keep track of whether each roleis ready for widespread use. Another common launch stage isDISABLED. Thislaunch stage lets youdisable a custom role.

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

• EAP orALPHA: The role is still being developed or tested, or it includespermissions for Google Cloud services or features that are not yetpublic. It is not ready for widespread use.
• BETA: The role has been tested on a limited basis, or it includespermissions for Google Cloud services or features that are not generallyavailable.
• GA: The role has been widely tested, and all of its permissions are forGoogle 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, seeEditing an existing custom role.

Maintenance

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

If you base your custom role on predefined roles, we recommend routinelychecking those predefined roles for permission changes. Tracking these changescan help you decide when and how to update your custom role. For example, youmight notice that a predefined role was updated with permissions to use a newPreview feature, and might decide to add those permissions to your custom roleas well.

To make it easier to see which predefined roles to monitor, we recommend listingany predefined roles that your custom role is based on in the custom role'sdescription field. The Google Cloud console does this automatically when youuse the Google Cloud console to create a custom role based on predefinedroles.

To learn how to update a custom role's permissions and description, seeEditingan existing custom role.

Refer to thepermissions change log todetermine 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 toDISABLED.

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

To learn how to disable a custom role, seedisabling a custom role.

What's next

• Learn how togrant IAM rolesto principals.
• Find out how tochoose the most appropriate predefined roles.
• Learn how tocreate custom roles.
• Learn about theuse cases for specific role types.

• Use thePolicy Troubleshooter to understand why a user doesor doesn't have access to a resource or have permission to call an API.