Identity and Access Management

Go to examples

This page provides an overview of Identity and Access Management (IAM) and its use with controlling access to buckets and objects in Cloud Storage. To learn about other ways of controlling access to buckets and objects, see Overview of Access Control.

This page focuses on aspects of IAM that are relevant specifically to Cloud Storage. For a detailed discussion of IAM and its features generally, see Identity and Access Management. In particular, see the Managing IAM Policies section.

Overview

IAM allows you to control who has access to the resources in your Google Cloud project. Resources include Cloud Storage buckets and objects stored within buckets, as well as other Google Cloud entities such as Compute Engine instances.

The set of access rules you apply to a resource is called an IAM policy. An IAM policy applied to your project defines the actions that users can take on all objects or buckets within your project. An IAM policy applied to a single bucket defines the actions that users can take on that specific bucket and objects within it.

For example, you can create an IAM policy for one of your buckets that gives one user administrative control of that bucket. Meanwhile, you can add another user to your project-wide IAM policy that gives that user the ability to view objects in any bucket of your project.

Principals are the "who" of IAM. Principals can be individual users, groups, domains, or even the public as a whole. Principals are granted roles, which give them the ability to perform actions in Cloud Storage as well as Google Cloud more generally. Each role is a collection of one or more permissions. Permissions are the basic units of IAM: each permission allows you to perform a certain action.

For example, the storage.objects.create permission allows you to create objects. This permission is found in roles such as Storage Object Creator, where it is the only permission, and Storage Object Admin, where many permissions are bundled together. If you grant the Storage Object Creator role to a principal for a specific bucket, they can only create objects in that bucket. If you grant another principal the Storage Object Admin role for the bucket, they can do additional tasks, such as deleting objects, but still only within that bucket. If these two users are granted these roles and no others, they won't have knowledge of any other buckets in your project. If you give a third principal the Storage Object Admin role, but do so for your project and not just a single bucket, they have access to any object in any bucket of your project.

Using IAM with Cloud Storage makes it easy to limit a principal's permissions without having to modify each bucket or object permission individually.

Caution: For fine-grained access control of individual objects, Cloud Storage uses Access control lists (ACLs). Object ACLs do not appear in the hierarchy of IAM policies. When evaluating who has access to one of your objects, make sure you check the ACLs for the object, in addition to checking your project- and bucket-level IAM policies.

Permissions

Permissions allow principals to perform specific actions on buckets or objects in Cloud Storage. For example, the storage.buckets.list permission allows a principal to list the buckets in your project. You don't directly give principals permissions; instead, you grant roles, which have one or more permissions bundled within them.

For a reference list of the IAM permissions that apply to Cloud Storage, see IAM Permissions for Cloud Storage.

Roles

Roles are a bundle of one or more permissions. For example, the Storage Object Viewer role contains the permissions storage.objects.get and storage.objects.list. You grant roles to principals, which allows them to perform actions on the buckets and objects in your project.

For a reference list of the IAM roles that apply to Cloud Storage, see IAM Roles for Cloud Storage.

Project-level roles vs. bucket-level roles

Granting roles at the bucket level does not affect any existing roles that you granted at the project level, and vice versa. Thus, you can use these two levels of granularity to customize your permissions. For example, say you want to give a user permission to read objects in any bucket but create objects only in one specific bucket. To achieve this, give the user the Storage Object Viewer role at the project level, thus allowing the user to read any object stored in any bucket in your project, and give the user the Storage Object Creator role at the bucket level for a specific bucket, thus allowing the user to create objects only in that bucket.

Some roles can be used at both the project level and the bucket level. When used at the project level, the permissions they contain apply to all buckets and objects in the project. When used at the bucket level, the permissions only apply to a specific bucket and the objects within it. Examples of such roles are Storage Admin, Storage Object Viewer, and Storage Object Creator.

Some roles can only be applied at one level. For example, you can only apply the Storage Legacy Object Owner role at the bucket level.

Caution: Setting IAM policies at project and bucket levels potentially allow users access to objects that they did not have previously. Carefully evaluate your policies before setting them.

Note: When you view the IAM policy for a project, you do not see the IAM policies that exist for individual buckets. If you view the IAM policy for an individual bucket using the Google Cloud Console, you do see project-level permissions that apply to that bucket; however, other Cloud Storage tools, such as gsutil and the Client Libraries only return the policy of the bucket, and do not include information inherited from the project-level policy. Be sure to consult both project and bucket policies when evaluating access levels for principals.

Relation to ACLs

Legacy Bucket IAM roles work in tandem with bucket ACLs: when you add or remove a Legacy Bucket role, the ACLs associated with the bucket reflect your changes. Similarly, changing a bucket-specific ACL updates the corresponding Legacy Bucket IAM role for the bucket.

Legacy Bucket role	Equivalent ACL
Storage Legacy Bucket Reader	Bucket Reader
Storage Legacy Bucket Writer	Bucket Writer
Storage Legacy Bucket Owner	Bucket Owner

All other bucket-level IAM roles, and all project-level IAM roles, work independently from ACLs. For example, if you give a user the Storage Object Viewer role, the ACLs remain unchanged. This means you can use bucket-level IAM roles to grant broad access to all objects within a bucket and use the fine-grained object ACLs to customize access to specific objects within the bucket.

IAM permission for changing ACLs

You can use IAM to give principals the permission needed to change ACLs on objects. The following storage.buckets permissions together allow users to work with bucket ACLs and default object ACLs: .get, .getIamPolicy, .setIamPolicy, and .update.

Similarly, the following storage.objects permissions together allow users to work with object ACLs: .get, .getIamPolicy, .setIamPolicy, and .update.

Custom roles

While IAM has many predefined roles that cover common use cases, you may wish to define your own roles which contain bundles of permissions that you specify. To support this, IAM offers custom roles.

Principal types

There are a number of different types of principals. For example, Google accounts and Google groups represent two general types, while allAuthenticatedUsers and allUsers are two specialized types. For a list of typical principal types in IAM, see Concepts related to identity.

Convenience values

Cloud Storage supports convenience values, which are a special set of principals that can be applied specifically to your IAM bucket policies. You should generally avoid using convenience values in production environments, because they require granting basic roles, a practice which is discouraged in production environments.

A convenience value is a two-part identifier consisting of a basic role and a project ID:

• projectOwner:PROJECT_ID
• projectEditor:PROJECT_ID
• projectViewer:PROJECT_ID

A convenience value acts as a bridge between the principals granted the basic role and an IAM role: the IAM role granted to the convenience value is, in effect, also granted to all principals of the specified basic role for the specified project ID.

For example, say [e-mail] and [e-mail] have the Viewer basic role for a project named my-example-project, and say you have a bucket in that project named my-bucket. If you grant the Storage Object Creator role for my-bucket to the convenience value projectViewer:my-example-project, then both [e-mail] and [e-mail] gain the permissions associated with Storage Object Creator for my-bucket.

You can grant and revoke access to convenience values for your buckets, but note that Cloud Storage automatically applies them in certain circumstances. See modifiable behavior for basic roles in Cloud Storage for more information.

Conditions

IAM Conditions allows you to set conditions that control how permissions are granted to principals. Cloud Storage supports the following types of condition attributes:

• resource.name: Grant access to buckets and objects based on the bucket or object name. You can also use resource.type to grant access to either buckets or objects, but doing so is mostly redundant with using resource.name. The following example condition applies an IAM setting to all objects with the same prefix:

  resource.name.startsWith('projects/_/buckets/BUCKET_NAME/objects/OBJECT_PREFIX')

• Date/time: Set an expiration date for the permission.

  request.time < timestamp('2019-01-01T00:00:00Z')

These conditional expressions are logic statements that use a subset of the Common Expression Language (CEL). You specify conditions in the role bindings of a bucket's IAM policy.

Note: You can also use double quotes in your conditional expressions, but they should be properly escaped when you are using gcloud commands and HTTP/REST requests to update a conditional policy. For example, request.time < timestamp(\"2019-01-01T00:00:00Z\").

Keep these restrictions in mind:

• You must enable uniform bucket-level access on a bucket before adding conditions at the bucket level. Although conditions are allowed at the project level, you should migrate all buckets in the project to uniform bucket-level access to prevent Cloud Storage ACLs from overriding project-level IAM conditions. You can apply a uniform bucket-level access constraint to enable uniform bucket-level access for all new buckets in your project.
• The gsutil iam ch command does not work with policies that contain conditions. To modify a policy that has conditions, use gsutil iam get to retrieve the policy for the relevant bucket, edit it locally, and then use gsutil iam set to re-apply it to the bucket.
• gsutil must be at version 4.38 or higher to use conditions.
• When using the JSON API to call getIamPolicy and setIamPolicy on buckets with conditions, you must set the IAM policy version to 3.
• Since the storage.objects.list permission is granted at the bucket level, you cannot use the resource.name condition attribute to restrict object listing access to a subset of objects in the bucket. Users without storage.objects.list permission at the bucket level can experience degraded functionality for the Console and gsutil.
• Expired conditions remain in your IAM policy until you remove them.

Using with Cloud Storage tools

Although IAM permissions cannot be set through the XML API, users granted IAM permissions can still use the XML API, as well as any other tool for accessing Cloud Storage.

For references of which IAM permissions allow users to perform actions with different Cloud Storage tools, see IAM with the Cloud Console, IAM with gsutil, IAM with JSON, and IAM with XML.

Best practices

IAM, like any other administrative settings, requires active management to be effective. Before you make a bucket or object accessible to other users, be sure you know who you want to share the bucket or object with and what roles you want each of those people to play. Over time, changes in project management, usage patterns, and organizational ownership may require you to modify IAM settings on buckets and projects, especially if you manage Cloud Storage in a large organization or for a large group of users. As you evaluate and plan your access control settings, keep the following best practices in mind:

• Use the principle of least privilege when granting access.

  The principle of least privilege is a security guideline for granting access to your resources. When you grant access based on the principle of least privilege, you give a user only the access they need to accomplish their assigned task. For example, if you want to share files with someone, you should grant them the storage.objectReader role and not the storage.admin role.

• Avoid granting roles with setIamPolicy permission to people you do not know.

  Granting setIamPolicy permission allows a user to change permissions and take control of data. You should use roles with setIamPolicy permission only when you want to delegate administrative control over objects and buckets.

• Be careful how you grant permissions for anonymous users.

  The allUsers and allAuthenticatedUsers principal types should only be used when it is acceptable for anyone on the Internet to read and analyze your data. While these scopes are useful for some applications and scenarios, it is usually not a good idea to grant all users certain permissions such as setIamPolicy, update, create, or delete.

• Avoid setting permissions that result in inaccessible buckets and objects.

  A bucket or object becomes inaccessible when there is no one with permission to read it. This can happen for a bucket when all IAM permissions on the bucket get removed. This can happen for an object when the object's owner leaves a project and there are no bucket or project-level IAM policies that grant access to objects. In both cases, you can regain access by granting an appropriate role, such as Storage Admin, to yourself or another principal at the project level. Note that doing so gives access to all buckets and objects in the project, so you may want to revoke the role once you've reset access to the affected bucket or object.

• Be sure you delegate administrative control of your buckets.

  You should be sure that your buckets and resources can still be managed by other team members should an individual with administrative access leave the group. Two common ways to achieve this are the following:

  • Grant the Storage Admin role for your project to a group instead of an individual.

  • Grant the Storage Admin role for your project to at least two individuals.

What's next

• Learn how to use IAM with Cloud Storage.
• Review the IAM reference table for Cloud Storage.