This page describes how Google Cloud's Identity and Access Management (IAM)system works and how you can use it to manage access in Google Cloud.

IAM is a tool to manage fine-grained authorization forGoogle Cloud. In other words, it lets you controlwho can dowhatonwhich resources.

Access in Google Cloud

Every action in Google Cloud requires certain permissions. When someonetries to perform an action in Google Cloud—for example, create a VMinstance or view a dataset—IAM first checks to see if theyhave the required permissions. If they don't, then IAM preventsthem from performing the action.

Giving someone permissions in IAM involves the following threecomponents:

• Principal: The identity of the person or system that you want to givepermissions to
• Role: The collection of permissions that you want to give the principal
• Resource: The Google Cloud resource that you want to let theprincipal access

To give the principal permission to access the resource, you grant them therole on the resource. You grant these roles using anallow policy.

The following sections describe these concepts in more detail.

Principals

In Google Cloud you control access forprincipals. Principals representone or more identities that have authenticated to Google Cloud.

In the past, principals were referred to asmembers. Some APIs still use thatterm.

There are a variety of types of principals in IAM, but they canbe divided into two broad categories:

• Human users: Some IAM principal types represent humanusers. You use these principal types for managing your employees' access toGoogle Cloud resources.

  Principal types that represent human users include Google Accounts, Googlegroups, and federated identities in workforce identity pools.

• Workloads: Some IAM principal types represent workloads.You use these principal types when managing your workloads' accessGoogle Cloud resources.

  Principal types that represent workloads include serviceaccounts and federated identities in a workload identity pool.

For more information about principals, seeIAMprincipals.

Permissions and roles

Permissions determine what operations are allowed on a resource. InIAM, permissions are typically represented in the formservice.resource.verb. Often,permissions correspond one-to-one with REST API methods—for example, theresourcemanager.projects.list permission lets you listResource Manager projects.

You can't directly grant permissions to a principal. Instead, you giveprincipals permissions by granting themroles.

Roles are collections of permissions. When you grant a role to a principal, yougive that principal all of the permissions in that role.

There are three types of roles:

• Predefined roles: Roles that are managed by Google Cloud services.These roles contain the permissions needed to perform common tasks for eachgiven service. For example, the Pub/Sub Publisher role(roles/pubsub.publisher) provides access to publish messages to aPub/Sub topic.

• Custom roles: Roles that you create that contain only the permissions thatyou specify. You have complete control over the permissions in these roles.However, they have a higher maintenance burden than predefined roles andthere's a limit to the number of custom roles that you can have in yourproject and in your organization.

• Basic roles: Highly permissive roles that provide broad access toGoogle Cloud services. These roles can be useful for testing purposes,but shouldn't be used in production environments.

For more information about roles and permissions, seeRoles andpermissions.

Resources

Most Google Cloud services have their own resources. For example,Compute Engine has resources like instances, disks, and subnetworks.

In IAM, you grant roles on a resource. Granting a principal arole on a resource means that the principal can use the permissions in that roleto access the resource.

You can grant roles on a subset of Google Cloud resources. For a full listof resources that you can grant roles on, seeResource types that accept allowpolicies.

Google Cloud also has several container resources, including projects,folders, and organizations. Granting a principal a role on a container resourcegives the principal access to both the container resourceand the resources inthat container. This feature lets you use a single role grant to give aprincipal access to multiple resources, including resources that you can't grantroles on directly. For more information, seePolicy inheritanceon this page.

Allow policies

You grant roles to principals usingallow policies. In the past, thesepolicies were referred to asIAM policies.

An allow policy is a YAML or JSON object that's attached to a Google Cloudresource.

The following diagram shows how an allow policy is structured:

Each allow policy contains a list ofrole bindings that associateIAM roles with the principals who are granted those roles.

When an authenticated principal attempts to access a resource,IAM checks the resource's allow policy to determine whetherthe principal has the required permissions. If the principal is in a rolebinding that includes a role with the required permissions, then they're allowedto access the resource.

To see examples of allow policies and learn about their structure, seeUnderstanding allow policies.

Policy inheritance

Google Cloud has container resources—such as projects, folders, andorganizations—that let you organize your resources in a parent-childhierarchy. This hierarchy is called theresource hierarchy.

The Google Cloud resource hierarchy has the following structure:

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

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

If you set an allow policy on a container resource, then the allow policy alsoapplies to all resources in that container. This concept is calledpolicyinheritance, because descendant resources effectively inherit their ancestorresources' allow policies.

Policy inheritance has the following implications:

• You can use a single role binding to grant access to multiple resources.If you want to give a principal access to all resources in a container, thengrant them a role on the container instead of on the resources in thecontainer.

  For example, if you want to let your security administrator manage allowpolicies for all resources in your organization, then you could grant themthe Security Admin role (roles/iam.securityAdmin) on the organization.

• You can grant access to resources that don't have their own allowpolicies. Not all resources accept allow policies, but all resources inheritallow policies from their ancestors. To give a principal access to a resourcethat can't have its own allow policy, grant them a role on one of theresource's ancestors.

  For example, imagine you want to give someone permission to write logs to alog bucket. Log buckets don't have their own allow policies, so to givesomeone this permission, you can instead grant them the Logs Bucket Writerrole (roles/logging.bucketWriter) on the project that contains the logbucket.

• To understand who can access a resource, you need to also viewall of theallow policies that affect the resource. To get a complete list of theprincipals that have access to the resource, you need to view the resource'sallow policyand the resource's ancestors' allow policies. The union of allof these policies is called theeffective allow policy.

For more information about policy inheritance for allow policies, seeUsing resource hierarchy for access control.

Advanced access control

In addition to allow policies, IAM provides the following accesscontrol mechanisms to help you refine who has access to what resources:

• Additional policy types: IAM offers the following policytypes in addition to allow policies:

  • Deny policies: Deny policies prevent principals from using certainpermissions, even if they're granted a role with the permission.

  • Principal access boundary (PAB) policies: Principal access boundarypolicies define and enforce the resources a principal is eligible toaccess. Principals can't access resources that they're not eligible toaccess, even if they've been granted a role on the resource.

  To learn more about these policies, seePolicy types.

• IAM Conditions: IAM Conditions lets youdefine and enforce conditional, attribute-based access control. You can useconditions in various policy types. For example, you can add a condition to arole binding in an allow policy to ensure that the role is only granted if thecondition is met.

  You can write conditions based on attributes like the resource in the requestand the time of the request.

  To learn more about IAM Conditions, seeOverview ofIAM Conditions.

• Privileged Access Manager (PAM): With Privileged Access Manager, you canlet principals request and be given temporary, auditable access to resources.For example, you could require that principals request access each time theywant to view a sensitive resource instead of permanently granting them aIAM role.

  You can also configure whether principals are required to providejustifications or get approvals when they request access.

  To learn more about Privileged Access Manager, seePrivileged Access Manageroverview.

Consistency model for the IAM API

TheIAM API iseventually consistent. In other words, if you write datawith the IAM API, then immediately read that data, the readoperation might return an older version of the data. Also, changes you makemight take time to affect access checks.

This consistency model affects how the IAM API works. Forexample, if you create a service account, then immediately refer to that serviceaccount in another request, the IAM API might say that theservice account couldn't be found. This behavior occurs because operations areeventually consistent; it can take time for the new service account to becomevisible to read requests.

What's next

• To learn how to configure identities for Google Cloud, seeIdentitymanagement for Google Cloud.
• For instructions on how to grant, change, and revoke IAMroles to principals, seeManage access to projects, folders, and organizations.
• For a list of available IAM roles, seePredefined roles.
• To get help with choosing the most appropriate predefined roles, readFind the right predefined roles.
• For more information about the policy types available in IAM,seePolicy types.