Usage

This page provides an overview of Identity and Access Management (IAM) and its use withcontrolling access to the buckets, managed folders, and objects resources inCloud Storage.

• To learn about other ways of controlling access in Cloud Storage, seeOverview of Access Control.

• For a detailed discussion of IAM and its features generally,seeIdentity and Access Management.

Overview

IAM allows you to control who has access to theresources in your Google Cloud project. Resources includeCloud Storage buckets, the managed folders within buckets, and objectsstored within buckets, as well as other Google Cloud entities such asCompute Engine instances.

Principals are the "who" of IAM. Principals can be individualusers, groups, domains, or even the public as a whole. Principals are grantedroles, which give them the ability to perform actions inCloud Storage as well as Google Cloud more generally. Each roleis a collection of one or morepermissions. Permissions arethe basic units of IAM: each permission lets you perform acertain action.

For example, thestorage.objects.create permission lets you createobjects. This permission is found in roles such as Storage Object Creator(roles/storage.objectCreator), which grants the permissions useful forcreating objects in a bucket, and Storage Object Admin(roles/storage.objectAdmin), which grants a wide range of permissions forworking with objects.

The collection of IAM roles that you set on a resource is calledan IAMpolicy. The access granted by these roles apply to boththe resource on which the policy is set and any resources contained within thatresource. For example, you can set an IAM policy on a bucket thatgives a user administrative control of that bucket and its objects. You can alsoset an IAM policy on the overall project that gives another userthe ability to view objects in any bucket within that project.

If you have a Google Cloudorganization resource, you can also useIAM deny policies to deny access to resources.When a deny policy is attached to a resource, the principal in the policy can'tuse the specified permission to access the resource or any sub-resource withinit, regardless of the roles they're granted. Deny policies override anyIAM allow policies.

Note: While you can set IAM policies on buckets, managed folders,and projects in order to control access to objects within them, you cannot setIAM policies directly on individual objects.

Permissions

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

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

Roles

Roles are a bundle of one or morepermissions. For example, theStorage Object Viewer (roles/storage.objectViewer) role contains thepermissionsstorage.objects.get andstorage.objects.list. You grant roles toprincipals, which allows them to perform actions on the buckets, managedfolders, and objects in your project.

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

Granting roles at the project level, bucket level, or managed folder level

You can grant roles to principals at the project level, bucket level, ormanaged folder level. The permissions granted by those roles apply additivelythroughout the resource hierarchy. You can grant roles at different levels ofthe resource hierarchy for more granularity in your permissions model.

For example, say you want to give a user permission to read objects in anybucket within a project but create objects only in bucket A. To achieve this,you can give the user the Storage Object Viewer (roles/storage.objectViewer)role for the project, which allows the user to read any object stored in anybucket within your project, and the Storage Object Creator(roles/storage.objectCreator) role for bucket A, which allows the user tocreate objects only in that bucket.

Some roles can be used at all levels of the resource hierarchy. When usedat the project level, the permissions they contain apply to all buckets,folders, and objects in the project. When used at the bucket level, thepermissions only apply to a specific bucket and the folders and objects withinit. Examples of such roles are the Storage Admin (roles/storage.admin) role,the Storage Object Viewer (roles/storage.objectViewer) role, andthe Storage Object Creator (roles/storage.objectCreator) role.

Some roles can only be applied at one level. For example, you can only apply theStorage Legacy Object Owner (roles/storage.legacyObjectOwner) role at thebucket level or at the managed folder level. TheIAM rolesthat allow you to control IAM deny policies can only be appliedat theorganization level.

Caution: Setting IAM policies at project, bucket, and managedfolder levels potentially allow users access to objects that they did not havepreviously. Carefully evaluate your policies before setting them.Note: When you view the IAM policy for a project, you don'tsee the IAM policies that exist for individual buckets. If youview the IAM policy for an individual bucket using theGoogle Cloud console, you do see project-level permissions that apply to thatbucket; however, other Cloud Storage tools, such asgcloud storage and theClient Libraries only return the policy ofthe bucket and don't include information inherited from the project-levelpolicy. Be sure to consult both project and bucket policies when evaluatingaccess levels for principals.

Relation to ACLs

In addition to IAM, your buckets and objects can use a legacyaccess control system calledaccess control lists (ACLs) if theuniform bucket-level access feature is not enabled for your bucket. Generally,you should avoid using ACLs, and you should enable uniform bucket-level accessfor your bucket. This section discusses what you should keep in mind if youallow ACL usage for a bucket and the objects within it.

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

Legacy Bucket role	Equivalent ACL
Storage Legacy Bucket Reader (roles/storage.legacyBucketReader)	Bucket Reader
Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter)	Bucket Writer
Storage Legacy Bucket Owner (roles/storage.legacyBucketOwner)	Bucket Owner

All other bucket-level IAM roles, includingLegacy ObjectIAM roles, work independently from ACLs. Similarly, allproject-level IAM roles work independently from ACLs. Forexample, if you give a user the Storage Object Viewer(roles/storage.objectViewer) role, the ACLs remain unchanged.

Because object ACLs work independently from IAM roles, they don'tappear in the hierarchy of IAM policies. When evaluating who hasaccess to one of your objects, make sure youcheck the ACLs for theobject, in addition to checking your project-level and bucket-levelIAM policies.

IAM deny policies vs. ACLs

IAM deny policies apply to access granted by ACLs. Forexample, if you create a deny policy that denies a principal thestorage.objects.get permission on a project, the principal cannot view objectsin that project, even if they are granted theREADER permission to individualobjects.

IAM permission for changing ACLs

You can use IAM to give principals the permission needed tochange ACLs on objects. The followingstorage.buckets permissions togetherallow users to work with bucket ACLs and default object ACLs:.get,.getIamPolicy,.setIamPolicy, and.update.

Similarly, the followingstorage.objects permissions together allow users towork with object ACLs:.get,.getIamPolicy,.setIamPolicy, and.update.

Custom roles

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

Principal types

There are a number of different types of principals. For example,Google Cloud accounts represent a general type, whileallAuthenticatedUsers andallUsers are two specialized types. For a list ofprincipal types in IAM, seePrincipal identifiers. Formore information about principals in general, seeIAM principals.

Convenience values

Cloud Storage supportsconvenience values, which are a special set ofprincipals that can be applied specifically to your IAM bucketpolicies. You should generally avoid using convenience values in productionenvironments, because they require grantingbasic roles,a practice which is discouraged in production environments.

A convenience value is a two-part identifier consisting of abasic roleand a project ID:

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

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

For example, say jane@example.com and john@example.com have the Viewer(roles/viewer) basic role for a project namedmy-example-project, and sayyou have a bucket in that project namedmy-bucket. If you grant the StorageObject Creator (roles/storage.objectCreator) role formy-bucket to the convenience valueprojectViewer:my-example-project, thenboth jane@example.com and john@example.com gain the permissions associated withthe Storage Object Creator role formy-bucket.

You can grant and revoke access to convenience values for your buckets, but notethat Cloud Storage automatically applies them in certain circumstances.Seemodifiable behavior for basic roles in Cloud Storage for moreinformation.

Conditions

IAM Conditions lets you set conditions that controlhow permissions are granted or denied to principals. Cloud Storagesupports the following types of condition attributes:

• resource.name: Grant or deny access to buckets and objects basedon the bucket or object name. You can also useresource.type togrant access to either buckets or objects, but doing so is mostly redundantwith usingresource.name. The following example condition applies anIAM 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 theCommon Expression Language (CEL). You specify conditions inthe role bindings of a bucket's IAM policy.

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

Keep these restrictions in mind:

• You must enableuniform bucket-level access on a bucket before addingconditions at the bucket level. Although conditions are allowed at theproject level, you should migrate all buckets in the project touniform bucket-level access to prevent Cloud Storage ACLs from overridingproject-level IAM conditions. You can apply auniform bucket-level access constraint to enable uniform bucket-level accessfor all new buckets in your project.
• When using the JSON API to callgetIamPolicy andsetIamPolicy on buckets with conditions, you must set theIAM policy version to 3.
• Since thestorage.objects.list permission is granted at the bucket level,you cannot use theresource.name condition attribute to restrict objectlisting access to a subset of objects in the bucket.
• Expired conditions remain in your IAM policy until you removethem.

Using with Cloud Storage tools

Although IAM permissions cannot be set through the XML API, usersgranted IAM permissions can still use the XML API, as well as anyother tool for accessing Cloud Storage.

For references on which IAM permissions allow users to performactions with different Cloud Storage tools, seeIAM references for Cloud Storage.

What's next

• Learn how to use IAM with Cloud Storage.
• Review the IAM reference table for Cloud Storage.
• Learn aboutbest practices for using IAM.
• Manage IAM policies for all of your Google Cloudresources.