Usage

This page provides an overview of access control lists (ACLs), which let youcontrol access to individual buckets or objects. To learn about other ways ofcontrolling access to buckets and objects, readOverview of Access Control.

Should you use access control lists?

In most cases, you should avoid using ACLs, and you shouldenable uniform bucket-level access for your buckets, which prevents ACL usage:

• ACLs can't be used exclusively to control access to your Google Cloudresources, because ACLs can't be set on the overall project or resourcesoutside Cloud Storage.
• Enabling uniform bucket-level access creates a simpler access control surface andlets you use additional Google Cloud features. For more information, seeshould you use uniform bucket-level access.
• Thedomain restricted sharing organization policy andcustom organization policies don't prevent access granted by ACLs,potentially leading to unintended access.
• Unexpected behaviors and access can occur when using ACLs in projects thathaveIAM conditions set at or above the project level.

You most likely want to use ACLs in the following cases:

• You need to customize access to individual objects within a bucket, such as ifyou want the uploader of an object to have full control over that object, butless access to other objects in your bucket.
• You are exclusively using theXML API or requireinteroperabilitywith Amazon S3.

What is an access control list?

An access control list (ACL) is a mechanism you can use to define who has accessto your buckets and objects, as well as what level of access they have. InCloud Storage, you apply ACLs to individual buckets and objects. EachACL consists of one or moreentries. An entry gives a specific user (or group)the ability to perform specific actions. Each entry consists of two pieces ofinformation:

• Apermission, which defineswhat actions can be performed (for example,read or write).

• Ascope (sometimes referred to as agrantee), which defineswho canperform the specified actions (for example, a specific user or group ofusers).

As an example, suppose you have a bucket that you want anyone to be able toaccess objects from, but you also want your collaborator to be able to add orremove objects from the bucket. In this case, your ACL would consist of twoentries:

• In one entry, you would giveREADER permission to a scope ofallUsers.

• In the other entry, you would giveWRITER permission to the scope of yourcollaborator (there are several ways to specify this person, such as by theiremail).

The maximum number of ACL entries you can create for a bucket or object is 100.When the entry scope is a group or domain, it counts as one ACL entry regardlessof how many users are in the group or domain.

When a user requests access to a bucket or object, the Cloud Storagesystem reads the bucket or object ACL and determines whether to allow or rejectthe access request. If the ACL grants the user permission for the requestedoperation, the request is allowed. If the ACL does not grant the user permissionfor the requested operation, the request fails and a403 Forbidden error isreturned.

Note that while ACLs can be used to manage most actions involving buckets andobjects, the ability tocreate a bucket comes from having the appropriateproject permission.

Permissions

Permissions describewhat can be done to a given object or bucket.

Cloud Storage lets you assign the followingconcentricpermissions for your buckets and objects, as shown in the following table:

	Buckets	Objects
READER	Allows a user to list a bucket's contents. Also allows a user to read bucket metadata, excluding ACLs.	Allows a user to download an object's data.
WRITER	Gives a user all access that's granted by theREADER permission. Additionally allows a user to create, replace, and delete objects in a bucket, including creating objects using multipart uploads.	N/A. You cannot apply this permission to objects.
OWNER	Gives a user all access that's granted by theWRITER permission. Also allows a user to read and write bucket metadata, including ACLs, and to work with tags on the bucket.	Gives a user all access that's granted by theREADER permission. Also allows a user to read and write object metadata, including ACLs.
Default	Buckets have the predefinedproject-private ACL applied when they are created. Buckets are always owned by theproject-owners group.	Objects have the predefinedproject-private ACL applied when they are uploaded. Objects are always owned by the original requester who uploaded the object.

Note: You cannot grant discrete permissions for reading or writing ACLs or othermetadata. To allow someone to read and write ACLs, you must grant themOWNERpermission.

In this page, we generally refer to the permissions asREADER,WRITER,andOWNER, which are how they are specified in theJSON API and theGoogle Cloud console. If you are using theXML API, the equivalentpermissions areREAD,WRITE, andFULL_CONTROL, respectively.

Scopes

Scopes specifywho it is that has a given permission.

An ACL consists of one or more entries, where each entry grants permissions toa scope. You can specify an ACL scope using any of the following entities:

Scope ("grantee")	Entity Type(s)	Example
Special identifier for all entities	User	allUsers
Special identifier for all valid accounts	User	allAuthenticatedUsers
User account email address	User	jeffersonloveshiking@gmail.com
Service account email address	User	my-service-account@my-project.iam.gserviceaccount.com
Google group email address	Group	work-group@googlegroups.com
Convenience values for projects	Project	owners-123456789012
Google Workspace domain	Domain	dana@example.com
Cloud Identity domain	Domain	dana@example.com

• Special identifier for all entities:

  The special scope identifierallUsers represents any entity on theInternet. Note that while this identifier is aUser entity type, whenusing the Google Cloud console it's labeled as aPublic entity type.

• Special identifier for all valid accounts:

  The special scope identifierallAuthenticatedUsers represents mostauthenticated accounts, including service accounts. For more information,seeIAM principals. Note that while this identifier is aUser entity type, when using the Google Cloud console it's labeled asaPublic entity type.

• User account email address:

  Every user who has a user account must have a unique email addressassociated with that account. You can specify a scope by using any emailaddress that is associated with a user account.

  Cloud Storage remembers email addresses as they are provided inACLs until the entries are removed or replaced. If a user changes emailaddresses, you should update ACL entries to reflect these changes.

• Service account email address:

  Everyservice account has a unique email address associated with it.You can specify a scope by using the email address that is associated withthe service account.

• Google group email address:

  EveryGoogle group has a unique email address that is associated withthe group. For example, theCloud Storage Announce group hasthe following email address: gs-announce@googlegroups.com. You can find theemail address that is associated with a Google group by clickingAbouton the homepage of every Google group.

  Like user account email addresses, Cloud Storage remembers groupemail addresses as they are provided in ACLs until the entries are removed.You don't need to worry about updating Google Group email addresses,because Google Group email addresses are permanent and unlikely to change.

• Convenience values for projects:

  Convenience values allow you to grant bulk access to your project'sviewers, editors, and owners. Convenience values combine a project roleand an associated project number. For example, in project867489160491,editors are identified aseditors-867489160491. You can find your projectnumber on the homepage of theGoogle Cloud console.

  You should generally avoid using convenience values in productionenvironments, because they require grantingbasic roles,a practice which is discouraged in production environments.

• Google Workspace or Cloud Identity:

  Google Workspace andCloud Identity customers can associatetheir email accounts with an Internet domain name. When you do this, eachemail account takes the formUSERNAME@YOUR_DOMAIN.com.You can specify a scope by using any Internet domain name that is associatedwith Google Workspace or Cloud Identity.

Concentric permissions and scopes

When specifying ACLs in Cloud Storage, you do not need to list multiplescopes to grant multiple permissions. Cloud Storage uses concentricpermissions, so when you grantWRITER permission, you also grantREADERpermission, and if you grantOWNER permission, you also grantREADER andWRITER permission.

When specifying an ACL, most tools allow you tospecify multiple scopes for the same entry. The most permissive permission isthe access granted to the scope. For example, if you provide two entries for auser, one withREADER permission and one withWRITER permission on a bucket,the user will haveWRITER permission on the bucket.

In the XML API, it is not possible to provide two ACL entries with the samescope. For example, granting a userREAD permission andWRITE permission ona bucket results in an error. Instead, grant the userWRITE permission, whichalso grants the userREAD permission.

ACLs and IAM

Identity and Access Management (IAM) and ACLs work in tandem to grant accessto your buckets and objects, which means a user only needs the relevantpermission from either of these systems in order to access a bucket or object.In general, permissions granted by IAM policies don't appear inACLs, and permissions granted by ACLs don't appear in IAMpolicies. SeeIAM relation to ACLs for more information.

Behavior with IAM deny

AnIAM deny policy overrides any applicable access thatwould otherwise be granted by an ACL you've set, when the deny policy and theACL target the same permission.

For example, if a bucket has a deny policy that prevents a user from havingthestorage.objects.get permission, and you create an ACL that grants theuser theREADER role on an object within the bucket, the user won'tbe able to view the object in the bucket. However, if the deny policyspecifies thestorage.buckets.get permission and the ACL grants theWRITER role on the bucket, the user won't be able to retrieve the bucket'smetadata, but can still list, create, and delete objects in the bucket.

Predefined ACLs

A predefined ACL, also sometimes known as a canned ACL, is an alias for a setof specific ACL entries that you can use to quickly apply many ACL entries atonce to a bucket or object.

Caution: By applying a predefined ACL to an existing bucket or object, youcompletely replace the existing bucket or object ACL with the predefined ACL.This change might cause you to lose access to the bucket or object ACL in somecases. For example, if you are in the project owners group but are not theowner of an object withprojectPrivate ACL, then after you apply thepredefined ACLpublicRead to the object, you loseOWNER permission andthus no longer can access the object ACL. If this occurs, you can use theIAM rolestorage.objectAdmin so that you have thepermission necessary to update the object's ACL and correct the change.

The table below lists predefined ACLs and shows which ACL entries are appliedfor each predefined ACL. When using the table below, note that:

• The project owners group has ownership of buckets in the project, and the userthat creates an object has ownership of that object. If an object was createdby an anonymous user, then the project owners group has ownership of theobject.

• In the table, the JSON API descriptions of permissions,OWNER,WRITER,andREADER, are used. The equivalent XML API scopes areFULL_CONTROL,WRITE, andREAD.

  JSON API/gcloud storage	XML API	Description
  private	private	Gives the bucket or object ownerOWNER permission for a bucket or object.
  bucketOwnerRead	bucket-owner-read	Gives the object ownerOWNER permission, and gives the bucket ownerREADER permission.This is used only with objects.
  bucketOwnerFullControl	bucket-owner-full-control	Gives the object and bucket ownersOWNER permission.This is used only with objects.
  projectPrivate	project-private	Gives permission to the project team based on their roles. Anyone who is part of the team hasREADER permission. Project owners and project editors haveOWNER permission. This is the default ACL for newly created buckets. This is also the default ACL for newly created objects unless thedefault object ACL for that bucket has been changed.
  authenticatedRead	authenticated-read	Gives the bucket or object ownerOWNER permission, and gives all authenticated user account holdersREADER permission.
  publicRead	public-read	Gives the bucket or object ownerOWNER permission, and gives all users, both authenticated and anonymous,READER permission. When you apply this to an object, anyone on the Internet can read the object without authenticating. When you apply this to a bucket, anyone on the Internet can list objects without authenticating. * See the note at the end of the table regarding caching.
  publicReadWrite	public-read-write	Gives the bucket ownerOWNER permission, and gives all users, both authenticated and anonymous,READER andWRITER permission. This ACL applies only to buckets. When you apply this to a bucket, anyone on the Internet can list, create, replace, and delete objects without authenticating. Important: Setting a bucket topublicReadWrite allows anyone on the Internet to upload anything to your bucket. You are responsible for this content. * See the note at the end of the table regarding caching.

* By default, publicly readable objects are served with aCache-Controlheader that allows the objects to be cached for 3600 seconds. If you need toensure that updates become visible immediately, you shouldset theCache-Control metadata for the objects toCache-Control:private, max-age=0, no-transform.

Default ACLs

When buckets are created or objects are uploaded, if you do not explicitlyassign an ACL to them, they are given the default ACL. You can change thedefault ACL given to an object; the process to do so is described inChanging default object ACLs. Note that when you change the defaultACL, the ACLs of objects that already exist in the bucket or buckets thatalready exist in the project remain unchanged.

Default bucket ACLs

All buckets are owned by the project owners group. Additionally, project ownersare grantedOWNER permission for any buckets inside their project that use apredefined ACL.

If you create a bucket with the default bucket ACL—that is, you do notspecify apredefined ACL when you create thebucket—your bucket has the predefinedprojectPrivate ACL applied to it.

Default object ACLs

By default, anyone who hasOWNER permission orWRITER permission on a bucketcan upload objects into that bucket. When you upload an object, you can provideapredefined ACL or not specify an ACL at all. If you don'tspecify an ACL, Cloud Storage applies the bucket's default object ACLto the object. Every bucket has a default object ACL, and this ACL is applied toall objects uploaded to that bucket without a predefined ACL or an ACL specifiedin the request (JSON API only). The initial value for the default object ACL ofevery bucket isprojectPrivate.

Based on how objects are uploaded, object ACLs are applied accordingly:

• Authenticated Uploads

  If you make an authenticated request to upload an object and do not specifyany object ACLs when you upload it, then you are listed as the owner of theobject and the predefinedprojectPrivate ACL is applied to the object bydefault. This means:

  • You (the person who uploaded the object) are listed as the object owner.Object ownership cannot be changed by modifying ACLs. You can changeobject ownership only by replacing an object.

  • You (the object owner) are grantedOWNER permission on the object. Ifyou attempt to give less thanOWNER permission to the owner,Cloud Storage automatically escalates the permission toOWNER.

  • The project owners and project editors group haveOWNER permission onthe object.

  • The project team members group hasREADER permission on the object.

• Anonymous Uploads

  If an unauthenticated (anonymous) user uploads an object, which is possibleif a bucket grants theallUsers groupWRITER orOWNER permission,then the default bucket ACLs are applied to the object as described above.

  Anonymous users cannot specify a predefined ACL during object upload.

Important: If you change the default object ACL for a bucket, the change maytake time to propagate, and new objects created in the bucket may still get theold default object ACL for a short period of time (seeConsistency). Inorder to make sure that new objects created in the bucket will get the updateddefault object ACL, you should wait at least 30 seconds between changing thedefault object ACL and creating new objects.

ACL behavior

Cloud Storage helps you adhere tobest practices by enforcingsome ACL modification rules, which prevent you from setting ACLs that make datainaccessible:

• You cannot apply an ACL that specifies a different bucketor object owner.

  Bucket and object ownership cannot be changed by modifying ACLs. If youapply a new ACL to a bucket or object, be sure that the bucket or objectowner remains unchanged in the new ACL.

• The bucket or object owner always hasOWNER permission of thebucket or object.

  The owner of a bucket is the project owners group, and the owner of anobject is either the user who uploaded the object, or the project ownersgroup if the object was uploaded by an anonymous user.

  When you apply a new ACL to a bucket or object, Cloud Storagerespectively addsOWNER permission to the bucket or object owner if youomit the grants. It doesnot grant the project owners groupOWNERpermission for an object (unless the object was created by an anonymoususer), so you must explicitly include it.

You cannot apply ACLs that change theownership of a bucket or object (whichshould not be confused with theOWNER permission). Once created inCloud Storage, bucket and object ownership are permanent. You can,however, effectively change the ownership of objects (but not buckets) byreplacing them. Replacement is basically a delete operation followed immediatelyby an upload operation. During an upload operation, the person who is performingthe upload becomes the owner of the object. Keep in mind that to replace anobject, the person performing the replacement (and gaining ownership ofthe object by doing so) must haveWRITER orOWNER permission on the bucketin which the object is being uploaded.

Note: You can disableall ownership properties of a bucket and the objectswithin it byenabling uniform bucket-level access. Doing so also removes all useof ACLs in the bucket, makingIAM policies the only accesscontrol system used by the bucket.

What's next

• Learn how touse ACLs.
• Learn how to simplify your access control usinguniform bucket-level access.
• Learn aboutbest practices for using ACLs.