This page describes the basic concepts of Cloud Identity and Access Management (Cloud IAM).

Cloud IAM lets you grant granular access to specific Google Cloud Platform (GCP) resources and helps prevent access to other resources. Cloud IAM lets you adopt the security principle of least privilege, where you grant only necessary permissions to access specific resources.

How Cloud IAM works

With Cloud IAM, you manage identity and access control by defining who (identity) has what access (role) for which resource. For example, Compute Engine virtual machine instances, Google Kubernetes Engine (GKE) clusters, and Cloud Storage buckets are all GCP resources. The organizations, folders, and projects that you use to organize your resources are also resources.

In Cloud IAM, permission to access a resource is not granted directly to the end user. Instead, permissions are grouped into roles, and roles are granted to authenticated members. A Cloud IAM policy defines and enforces what roles are granted to which members, and this policy is attached to a resource. When an authenticated member attempts to access a resource, Cloud IAM checks the resource's policy to determine whether the action is permitted.

The following diagram illustrates permission management in Cloud IAM.


The model for access management in Cloud IAM has three main parts:

  • Member. A member can be a Google Account (for end users), a service account (for apps and virtual machines), a Google Group, or a G Suite or Cloud Identity domain that can access a resource. The identity of a member is an email address associated with a user, service account, or group; or a domain name associated with G Suite or Cloud Identity domains.
  • Role. A role is a collection of permissions. Permissions determine what operations are allowed on a resource. When you grant a role to a member, you grant all the permissions that the role contains.
  • Policy. The Cloud IAM policy binds a set of members to a role. When you want to define who (member) has what type of access (role) on a resource, you create a policy and attach it to the resource.

In the preceding diagram, for example, the Cloud IAM policy binds the end user identified by userid@gmail.com to the App Engine Admin role (roles/appengine.appAdmin). If the policy is attached to a project, the user userid@gmail.com has the App Engine Admin role within that project. In this case, the user can view, create, and update all project-level app configurations and settings for App Engine.

The rest of this page describes these concepts in greater detail.

In Cloud IAM, you grant access to members. Members can be of the following types:

  • Google account
  • Service account
  • Google group
  • G Suite domain
  • Cloud Identity domain

Google account

A Google account represents a developer, an administrator, or any other person who interacts with GCP. Any email address that is associated with a Google account can be an identity, including gmail.com or other domains. New users can sign up for a Google account by going to the Google account signup page.

Service account

A service account is an account that belongs to your application instead of an individual end user. When you run code that is hosted on GCP, you specify the account that the code should run as. You can create as many service accounts as needed to represent the different logical components of your application. For more information about using a service account in your application, see Getting started with authentication.

Google group

A Google group is a named collection of Google accounts and service accounts. Every group has a unique email address that is associated with the group. You can find the email address that is associated with a Google group by clicking About on the homepage of any Google group. For more information about Google groups, see the Google groups homepage.

Google groups are a convenient way to apply an access policy to a collection of users. You can grant and change access controls for a whole group at once instead of granting or changing access controls one-at-a-time for individual users or service accounts. You can also easily add members to and remove members from a Google group instead of updating a Cloud IAM policy to add or remove users.

Note that Google groups don't have login credentials, and you cannot use Google groups to establish identity to make a request to access a resource.

G Suite domain

A G Suite domain represents a virtual group of all the Google accounts that have been created in an organization's G Suite account. G Suite domains represent your organization's Internet domain name (such as example.com), and when you add a user to your G Suite domain, a new Google account is created for the user inside this virtual group (such as username@example.com).

Like Google groups, G Suite domains cannot be used to establish identity, but they enable convenient permission management.

Cloud Identity domain

A Cloud Identity domain is like a G Suite domain because it represents a virtual group of all Google accounts in an organization. However, Cloud Identity domain users don't have access to G Suite applications and features. For more information, see About Cloud Identity.


The value allAuthenticatedUsers is a special identifier that represents all service accounts and all users on the internet who have authenticated with a Google account. This identifier includes accounts that are not connected to a G Suite or Cloud Identity domain, such as personal Gmail accounts. Users who are not authenticated, such as anonymous visitors, are not included.


The value allUsers is a special identifier that represents anyone who is on the internet, including authenticated and unauthenticated users.

When an authenticated member attempts to access a resource, Cloud IAM checks the resource's Cloud IAM policy to determine whether the action is allowed.

This section describes the entities and concepts involved in the authorization process.


You can grant access to users for a GCP resource. Some examples of resources are projects, Compute Engine instances, and Cloud Storage buckets.

Some services, such as Compute Engine and Cloud Storage, support granting Cloud IAM permissions at a granularity finer than the project level. For example, you can grant the Storage Admin (roles/storage.admin) role to a user for a particular Cloud Storage bucket, or you can grant the Compute Instance Admin (roles/compute.instanceAdmin) role to a user for a specific Compute Engine instance.

In other cases, you can grant Cloud IAM permissions at the project level. The permissions are then inherited by all resources within that project. For example, to grant access to all Cloud Storage buckets in a project, grant access to the project instead of each individual bucket. Or to grant access to all Compute Engine instances in a project, grant access to the project rather than each individual instance.

For information on what roles can be granted on which resources, see Understanding Roles and refer to the Lowest Resource column for a given role.


Permissions determine what operations are allowed on a resource. In the Cloud IAM world, permissions are represented in the form of <service>.<resource>.<verb>, for example pubsub.subscriptions.consume.

Permissions usually, but not always, correspond 1:1 with REST methods. That is, each GCP service has an associated set of permissions for each REST method that it exposes. The caller of that method needs those permissions to call that method. For example, the caller of Publisher.Publish() needs the pubsub.topics.publish permission.

You don't assign permissions to users directly. Instead, you assign them a role which contains one or more permissions.


A role is a collection of permissions. You cannot assign a permission to the user directly; instead you grant them a role. When you grant a role to a user, you grant them all the permissions that the role contains.

Permission to Role mapping

There are three kinds of roles in Cloud IAM:

  • Primitive roles: The roles historically available in the Google Cloud Platform Console will continue to work. These are the Owner, Editor, and Viewer roles.

  • Predefined roles: Predefined roles are the Cloud IAM roles that give finer-grained access control than the primitive roles. For example, the predefined role Pub/Sub Publisher (roles/pubsub.publisher) provides access to only publish messages to a Cloud Pub/Sub topic.

  • Custom roles: Roles that you create to tailor permissions to the needs of your organization when predefined roles don't meet your needs.

To learn how to assign a role to user, see Granting, Changing, and Revoking Access. For information about the available fine-grained Cloud IAM predefined roles, see Understanding Roles. For information about custom roles, see Understanding Custom Roles and Creating and Managing Custom Roles.

IAM Policy

You can grant roles to users by creating a Cloud IAM policy, which is a collection of statements that define who has what type of access. A policy is attached to a resource and is used to enforce access control whenever that resource is accessed.

IAM Policy

A Cloud IAM policy is represented by the IAM Policy object. An IAM Policy object consists of a list of bindings. A Binding binds a list of members to a role.

role is the role you want to assign to the member. The role is specified in the form of roles/<name of the role>. For example, roles/storage.objectAdmin, roles/storage.objectCreator, and roles/storage.objectViewer.

members contains a list of one or more identities as described in the Concepts related to identity section above. Each member type is identified with a prefix, such as a Google account (user:), service account (serviceAccount:), Google group (group:), or a G Suite or Cloud identity domain (domain:). In the example snippet below, the storage.objectAdmin role is assigned to the following members using the appropriate prefix: user:alice@example.com, serviceAccount:my-other-app@appspot.gserviceaccount.com, group:admins@example.com, and domain:google.com. The objectViewer role is assigned to user:bob@example.com.

The following code snippet shows the structure of a Cloud IAM policy.

  "bindings": [
      "role": "roles/storage.objectAdmin",
       "members": [
      "role": "roles/storage.objectViewer",
      "members": [

Cloud IAM and Policy APIs

Cloud IAM provides a set of methods that you can use to create and manage access control policies on GCP resources. These methods are exposed by the services that support Cloud IAM. For example, the Cloud IAM methods are exposed by the Resource Manager, Cloud Pub/Sub, and Cloud Life Sciences APIs, just to name a few.

The Cloud IAM methods are:

  • setIamPolicy(): Allows you to set policies on your resources.
  • getIamPolicy(): Allows you to get a policy that was previously set.
  • testIamPermissions(): Allows you to test whether the caller has the specified permissions for a resource.

You can find the API reference topics for these methods in the documentation for each service that supports Cloud IAM.

Policy hierarchy

GCP resources are organized hierarchically:

  • The organization is the root node in the hierarchy.
  • Folders are children of the organization.
  • Projects are children of the organization, or of a folder.
  • Resources for each service are descendants of projects.

Each resource has exactly one parent. See the Resource Manager resource hierarchy for more information.

The following diagram is an example of a GCP resource hierarchy:

Resource Hierarchy

You can set a Cloud IAM policy at any level in the resource hierarchy: the organization level, the folder level, the project level, or the resource level. Resources inherit the policies of the parent resource. If you set a policy at the organization level, it is automatically inherited by all its children projects, and if you set a policy at the project level, it's inherited by all its child resources. The effective policy for a resource is the union of the policy set at that resource and the policy inherited from higher up in the hierarchy.

This policy inheritance is transitive; in other words, resources inherit policies from the project, which inherit policies from folders, which inherit policies from the organization. Therefore, the organization-level policies also apply at the resource level.

For example: In the diagram above, topic_a is a Cloud Pub/Sub resource that lives under the project example-prod. If you grant the Editor role to micah@example.com for example-prod, and grant the Publisher role to song@example.com for topic_a, you effectively grant the Editor role for topic_a to micah@example.com and the Publisher role to song@example.com.

The Cloud IAM policy hierarchy follows the same path as the GCP resource hierarchy. If you change the resource hierarchy, the policy hierarchy changes as well. For example, moving a project into an organization will update the project's Cloud IAM policy to inherit from the organization's Cloud IAM policy.

Child policies cannot restrict access granted at a higher level. For example, if you grant the Editor role to a user for a project, and grant the Viewer role to the same user for a child resource, then the user still has the Editor role grant for the child resource.

Cloud IAM support for GCP services

With Cloud IAM, every API method across all GCP services is checked to make sure that the account making the API request has the appropriate permission to use the resource.

Prior to Cloud IAM, you could only grant Owner, Editor, or Viewer roles. These roles give very broad access on a project and did not allow fine- grained separation of duties. GCP services now offer additional predefined roles that give finer-grained access control than the Owner, Editor, and Viewer roles. For example, Compute Engine offers roles such as Instance Admin and Network Admin and App Engine offers roles such as App Admin and Service Admin. These predefined roles are available in addition to the legacy Owner, Editor, and Viewer roles.

Predefined roles are available for most GCP services. For details, see the list of all predefined roles. If you need even more control over permissions, consider creating a custom role.

You can grant users certain roles to access resources at a granularity finer than the project level. For example, you can create a Cloud IAM access control policy that grants a user the Subscriber role for a particular Cloud Pub/Sub topic. The list of all predefined roles shows the lowest-level, or finest-grained, type of resource that accepts each role.

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud IAM Documentation