This page provides an overview of Identity and Access Management (IAM) and its use with controlling access to resources such as buckets and objects in Cloud Storage.
To learn about other ways of controlling access in Cloud Storage, see Overview of Access Control.
For a detailed discussion of IAM and its features generally, see Identity and Access Management.
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.
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,
which grants the permissions useful for creating objects in a bucket, and
Storage Object Admin, which grants a wide range of permissions for working
The collection of IAM roles that you set on a resource is called an IAM policy. The access granted by these roles apply to both the resource on which the policy is set and any resources contained within that resource. For example, you can set an IAM policy on a bucket that gives a user administrative control of that bucket and its objects. You can also set an IAM policy on the overall project that gives another user the ability to view objects in any bucket within that project.
Permissions allow principals to perform specific actions on buckets or objects
in Cloud Storage. For example, the
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 are a bundle of one or more permissions. For example, the
Storage Object Viewer role contains the permissions
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.
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, including Legacy Object IAM roles, work independently from ACLs. Similarly, 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:
Similarly, the following
storage.objects permissions together allow users to
work with object ACLs:
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.
There are a number of different types of principals. For example, Google
accounts and Google groups represent two general types, while
allUsers are two specialized types. For a list of
typical principal types in IAM, see
Concepts related to identity.
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:
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 firstname.lastname@example.org and email@example.com have the Viewer basic
role for a project named
my-example-project, and say you have a bucket in that
my-bucket. If you grant the Storage Object Creator role for
my-bucket to the convenience value
both firstname.lastname@example.org and email@example.com gain the permissions associated with
Storage Object Creator for
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.
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.typeto 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:
- Date/time: Set an expiration date for the
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.
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.
gsutil iam chcommand does not work with policies that contain conditions. To modify a policy that has conditions, use
gsutil iam getto retrieve the policy for the relevant bucket, edit it locally, and then use
gsutil iam setto 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
setIamPolicyon buckets with conditions, you must set the IAM policy version to 3.
- Since the
storage.objects.listpermission is granted at the bucket level, you cannot use the
resource.namecondition attribute to restrict object listing access to a subset of objects in the bucket. Users without
storage.objects.listpermission 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.
- Learn how to use IAM with Cloud Storage.
- Review the IAM reference table for Cloud Storage.
- Learn about best practices for using IAM.
- Manage IAM policies for all of your Google Cloud resources.