Overview

This page describes the basic concepts of Google Cloud Identity and Access Management.

Google Cloud Platform offers Cloud IAM, which lets you manage access control by defining who (members) has what access (role) for which resource.

IAM

With IAM you can grant more granular access to specific Google Cloud Platform resources and prevent unwanted access to other resources. IAM lets you adopt the security principle of least privilege, so you grant only the necessary access to your resources.

In Cloud IAM, you grant access to members. Members can be of 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 Google Cloud Platform. An email address that is associated with a Google account, such as a gmail.com address, can be an identity. 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 to an individual end user. When you run code that is hosted on Cloud Platform, 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. See the Google Cloud Platform Console Service Accounts documentation for more information.

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 members in an organization. G Suite customers can associate their email accounts with an Internet domain name. When you do this, each email account takes the form username@yourdomain.com. You can specify an identity by using any Internet domain name that is associated with a G Suite account.

Like groups, 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 members in an organization. However, Cloud Identity domain users don't have access to G Suite applications and features. Learn About Cloud Identity.

allAuthenticatedUsers

This is a special identifier that represents anyone who is authenticated with a Google account or a service account.

allUsers

This is a special identifier that represents anyone who is on the internet, with or without a Google account. Note that some APIs require authentication of any user accessing the service, and in those cases, allUsers will only imply authorization for all authenticated users.

After Google authenticates the member making a request, Cloud IAM makes an authorization decision on whether the member is allowed to perform an operation on a resource.

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

Resource

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

Permissions

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 Cloud Platform 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.

Roles

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 IAM roles that give finer-grained access control than the primitive roles. For example, the predefined role Publisher provides access to only publish messages to a 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.

For information about the available fine-grained IAM roles see Understanding Roles.

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 Policy object. A Policy 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 user. The role is specified in the form of roles/<name of the role>. For example, roles/owner, roles/editor, and roles/viewer.

The following code snippet shows the structure of a Cloud IAM policy. This policy assigns the owner role to alice@example.com, admins@example.com, google.com, and my-other-app@appspot.gserviceaccount.com, and the viewer role to bob@example.com.

{
  "bindings": [
   {
     "role": "roles/owner",
     "members": [
       "user:alice@example.com",
       "group:admins@example.com",
       "domain:google.com",
       "serviceAccount:my-other-app@appspot.gserviceaccount.com"]
   },
   {
     "role": "roles/viewer",
     "members": ["user:bob@example.com"]
   }
   ]
}

IAM and Policy APIs

Cloud IAM provides a standard set of methods that you can use to create and manage access control policies on Google Cloud Platform resources. These methods are exposed by the services that support Cloud IAM. For example, the Cloud IAM methods are exposed by the Google Cloud Resource Manager (CRM), Google Cloud Pub/Sub, and Google Genomics APIs.

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

Cloud Platform resources are organized hierarchically, where the Organization node is the root node in the hierarchy, the projects are the children of the Organization, and the other resources are the children of projects. Each resource has exactly one parent.

The following diagram is an example of a Cloud Platform resource hierarchy:

Resource Hierarchy

You can set an IAM access control 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 is inherited by all its children resources. The effective policy for a resource is the union of the policy set at that resource and the policy inherited from its parent. This policy inheritance is transitive; in other words, resources inherit policies from the project, 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 Pub/Sub resource that lives under the project example-test. If you grant the editor role to bob@gmail.com for example-test, and grant the publisher role to alice@gmail.com for topic_a, you effectively grant editor role to bob@gmail.com and publisher role to alice@gmail.com for topic_a.

The IAM policy hierarchy follows the same path as the Cloud Platform 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 IAM policy to inherit from the organization's IAM policy.

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

IAM support for Cloud Platform services

With IAM, every API method across all Cloud Platform 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 separation of duties. Cloud Platform services now offer additional 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.

The following products offer IAM predefined roles:

For a complete list of predefined roles, see Understanding Roles.

You can grant some roles to users to access resources at a granularity finer than the project level. For example, you can create an IAM access control policy that grants the Subscriber role to a user for a particular Pub/Sub topic. See Understanding Roles for information on what roles can be granted on which resources.

Next steps

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Identity and Access Management Documentation