This page provides an overview of access control lists (ACLs). To learn how to set and manage ACLs, read Create and Manage Access Control Lists. To learn about other ways of controlling access to buckets and objects, read Overview of Access Control.
What is an access control list?
An access control list (ACL) is the mechanism you use to share objects with other users and allow other users to access your buckets and objects. In Cloud Storage, you can apply an ACL to either individual objects or entire buckets to control access to them. Each ACL consists of one or more entries. An entry gives a specific user (or group) the ability to perform specific actions. Each entry consists of two pieces of information:
A permission, which defines what actions can be performed (for example, read or write).
A scope (sometimes referred to as a grantee), which defines who can perform the specified actions (for example, a specific user or group of users).
As an example, suppose you have a bucket that you want anyone to be able to be access objects from, but you also want your collaborator to be able to add or remove objects from the bucket. In this case, your ACL would consist of two entries:
In one entry, you would give
READERpermission to a scope of
In the other entry, you would give
WRITERpermission to the scope of your collaborator (there are several ways to specify this person, such as by their email).
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 regardless of how many users are in the group or domain.
When a user requests access to a bucket or object, the Cloud Storage system
reads the bucket or object ACL and determines whether to allow or reject the
access request. If the ACL grants the user permission for the requested
operation, the request is allowed. If the ACL does not grant the user permission
for the requested operation, the request fails and a
error is returned.
Note that while ACLs can be used to manage most actions involving buckets and objects, the ability to create a bucket comes from having the appropriate project permission.
Permissions describe what can be done to a given object or bucket.
Cloud Storage lets you assign the following concentric permissions for your buckets and objects, as shown in the following table:
||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.|
||Allows a user to list, create, overwrite, and delete objects in a bucket 1.||N/A. You cannot apply this permission to objects.|
||Gives a user
||Gives a user
|Default||Buckets have the predefined
project-private ACL applied when
they are created. Buckets are always owned by the
||Objects have the predefined project-private ACL applied when they are uploaded. Objects are always owned by the original requester who uploaded the object.|
In this page, we generally refer to the permissions as
OWNER, which are how they are specified in the JSON API and the
Google Cloud Platform Console. If you are using the XML API, the equivalent
FULL_CONTROL, respectively. And, when
you use OAuth 2.0 authentication to authenticate tools and applications
(grant permission to them) to access Google Cloud Storage API
on your behalf, access is restricted by OAuth scope
devstorage.full_control. The following table
summarizes the permissions terminology you commonly encounter:
|JSON API||XML API||OAuth2 Scope|
Scopes specify who it is that has a given permission.
An ACL consists of one or more entries, where each entry grants permissions to a scope. You can specify an ACL scope using any of the following entities:
|Scope ("grantee")||Entity Type(s)||Example|
|Google account email address||Userfirstname.lastname@example.org|
|Google Storage ID||User, Group||
|Google group email address||Groupemail@example.com|
|Convenience values for projects||Project||
|Google Apps domain||Domain||[USERNAME]@[YOUR_DOMAIN].com|
|Special identifier for all Google account holders||User||
|Special identifier for all users||User||
Google account email address:
Every user who has a Google account must have a unique email address associated with that account. You can specify a scope by using any email address that is associated with a Google account, such as a gmail.com address.
Cloud Storage remembers email addresses as they are provided in ACLs until the entries are removed or overwritten. If a user changes email addresses, you should update ACL entries to reflect these changes.
Cloud Storage ID:
A Cloud Storage ID (sometimes referred to as a canonical ID) is a string of 64 hexadecimal digits that identifies a specific Google account holder or a specific Google group. Each project, its editors, owners, and users have unique Cloud Storage IDs.
Use Finding Cloud Storage IDs to locate the Cloud Storage IDs for your project.
Google group email address:
Every Google group has a unique email address that is associated with the group. For example, the Cloud Storage Announce group has the following email address: firstname.lastname@example.org. You can find the email address that is associated with a Google group by clicking About on the homepage of every Google group. For more information about Google groups, see the Google groups homepage.
Like Google account email addresses, Cloud Storage remembers group email addresses as they are provided in ACLs until the entries are removed or overwritten. You do not need to worry about updating Google Group email addresses, because Google Group email addresses are permanent and unlikely to change.
Convenience values for projects:
The convenience values
viewers-<project-number>represent the lists of owners, editors, and viewers of the project whose project number is <project-number>.
You can use these convenience values to specify project owners, editors, and viewers instead of using the corresponding Cloud Storage IDs.
Google Apps domain:
Google Apps customers can associate their email accounts with an Internet domain name. When you do this, each email account takes the form [USERNAME]@[YOUR_DOMAIN].com. You can specify a scope by using any Internet domain name that is associated with a Google Apps account.
Special identifier for all Google account holders:
This special scope identifier represents anyone who is authenticated with a Google account. The special scope identifier for all Google account holders is
Special identifier for all users:
This special scope identifier represents anyone who is on the Internet, with or without a Google account. The special scope identifier for all users is
Concentric permissions and scopes
When specifying ACLs in Cloud Storage, you do not need to
list multiple scopes to grant multiple permissions. Cloud Storage uses concentric permissions, so
when you grant
WRITER permission, you also grant
READER permission, and if
OWNER permission, you also grant
When specifying an ACL using the Google Cloud Platform Console, JSON API, or gsutil, you can specify multiple
scopes for the same entry. The most permissive permission is the access granted to the scope.
For example, if you provide two entries for a user, one with
and one with
WRITER permission on a bucket, the user will have
WRITER permission on the bucket.
In the XML API, it is not possible to provide two ACL entries with the same scope. For example,
granting a user
WRITE permission on a bucket results in an error. Instead, grant the user
WRITE permission, which also grants the user
A predefined or "canned" ACL is an alias for a set of specific ACL entries that you can use to quickly
apply many ACL entries at once to a bucket or object. Predefined ACLs are defined for common
scenarios such as revoking all access permissions except for owner permission (predefined ACL
private), or making an object publicly readable (predefined ACL
The table below lists predefined ACLs that you can use and shows which ACL entries are applied for each predefined ACL. When using the table below, note that:
The project owners group has ownership of buckets in the project, and the user that creates an object has ownership of that object. If an object was created by an anonymous user, then the project owners group has ownership of the object.
In the table, the JSON API descriptions of permissions,
READER, are used. The equivalent XML API scopes are
|JSON API||XML API/gsutil||Description|
Gives the bucket or object owner
Gives the object owner
Gives the object and bucket owners
Gives permission to the project team based on their roles. Anyone who
is part of the team has
Gives the bucket or object owner
Gives the bucket or object owner
* See the note at the end of the table regarding caching.
Gives the bucket owner
* See the note at the end of the table regarding caching.
* By default, publicly readable objects are served with a
that allows the objects to be cached for 3600 seconds. If you need to ensure
that updates become visible immediately, you should set a
Cache-Control header of
Cache-Control:private, max-age=0, no-transform on the objects. For help doing
this, see the
gsutil setmeta command.
When buckets are created or objects are uploaded, if you do not explicitly assign an ACL to them, they are given the default ACL. You can change the default ACL given to an object; the process to do so is described in Changing default object ACLs. Note that when you change the default ACL, the ACLs of objects that already exist in the bucket or buckets that already exist in the project remain unchanged.
Default bucket ACLs
All buckets are owned by the project owners group. Project owners are granted
OWNER permission automatically to all buckets inside their project. When you create a
project, you are automatically added as a project owner.
If you create a bucket with the default bucket ACL—that is, you do not specify a
predefined ACL when you create the bucket—your bucket has the
projectPrivate ACL applied to it. The
projectPrivate ACL gives
additional permissions to project team members based on their roles. These additional permissions
are defined as follows:
All Project Team Members
projectPrivateACL provides all team members with
READERaccess to buckets in a project. All project team members can list objects within buckets. All project team members can also list buckets within a project, independent of bucket ACLs.
projectPrivateACL provides project editors with
OWNERpermissions to buckets in a project. Project editors can list a bucket's contents and create, overwrite, or delete objects in a bucket. Project editors can also list, create, and delete buckets, independent of bucket ACLs.
projectPrivateACL provides project owners with
OWNERpermissions. Project owners can also perform all tasks that project editors can perform, in addition to administrative tasks such as adding and removing team members or changing billing information.
Project teams, project editors, and project owners are identified using Cloud Storage IDs. You can find these Cloud Storage IDs in the Google Cloud Platform Console. This can be useful if you want to use these IDs to customize access to objects and buckets. For more information, see Finding Cloud Storage IDs.
Default object ACLs
By default, anyone who has
OWNER permission or
WRITER permission on a
bucket can upload objects into that bucket. When you upload an object, you can provide a
predefined ACL or not specify an ACL at all. If you don't specify an
ACL, Cloud Storage applies the bucket's default object ACL to the object. Every bucket has a default
object ACL, and this ACL is applied to all objects uploaded to that bucket without a predefined ACL
or an ACL specified in the request (JSON API only). The initial value for the default object ACL of
every bucket is
Based on how objects are uploaded, object ACLs are applied accordingly:
If you make an authenticated request to upload an object and do not specify any object ACLs when you upload it, then you are listed as the owner of the object and the predefined
projectPrivateACL is applied to the object by default. 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 change object ownership only by overwriting an object.
You (the object owner) are granted
OWNERpermission on the object. If you attempt to give less than
OWNERpermission to the owner, Cloud Storage automatically escalates the permission to
The project owners and project editors group have
OWNERpermission on the object.
The project team members group has
READERpermission on the object.
If an unauthenticated (anonymous) user uploads an object, which is possible if a bucket grants the
OWNERpermission, then the default bucket ACLs are applied to the object as described above.
Anonymous users cannot specify a predefined ACL during object upload. Anonymous users have the following Cloud Storage ID:
ACLs, like any other administrative settings, require 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 ACL settings on buckets and objects, especially if you manage buckets and objects 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 to your buckets and objects.
The principle of least privilege is a security guideline for granting privileges or rights. When you grant access based on the principle of least privilege, you grant the minimum privilege that's necessary for a user to accomplish their assigned task. For example, if you want to share a file with someone, grant them
READERpermission and not
OWNERpermission to people you do not know.
OWNERpermission allows a user to change ACLs and take control of data. You should use the
OWNERpermission only when you want to delegate administrative control over objects and buckets.
Be careful how you grant permissions for anonymous users.
allAuthenticatedUsersscopes 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
Avoid setting ACLs that result in inaccessible objects.
An inaccessible object is an object that cannot be downloaded (read) and can only be deleted. This can happen when the owner of an object leaves a project without granting anyone else
READERpermission on the object. To avoid this problem, you can use the
bucket-owner-full- controlpredefined ACLs when you or anyone else uploads objects to your buckets.
Be sure you delegate administrative control of your buckets.
By default, the project owners group is the only entity that has
OWNERpermission on a bucket when it is created. You should have at least two members in the project owners group at any given time so that if a team member leaves the group, your buckets can still be managed by the other project owners.
Cloud Storage helps you adhere to these best practices by enforcing some ACL modification rules, which prevent you from setting ACLs that make data inaccessible:
You cannot apply an ACL that specifies a different bucket or object owner.
Bucket and object ownership cannot be changed by modifying ACLs. If you apply a new ACL to a bucket or object, be sure that the bucket or object owner remains unchanged in the new ACL.
The bucket or object owner always has
OWNERpermission of the bucket or object.
The owner of a bucket is the project owners group, and the owner of an object is either the user who uploaded the object, or the project owners group if the object was uploaded by an anonymous user.
When you apply a new ACL to a bucket or object, Cloud Storage respectively adds
OWNERpermission to the bucket or object owner if you omit the grants. It does not grant the project owners group
OWNERpermission for an object (unless the object was created by an anonymous user), so you must explicitly include it.
You cannot apply ACLs that change the ownership of a bucket or object (which
should not be confused with the
OWNER permission). Once created in
Cloud Storage, bucket and object ownership are permanent. You can, however,
effectively change the ownership of objects (but not buckets) by overwriting
them. Overwriting is basically a delete operation followed immediately by an
upload operation. During an upload operation, the person who is performing the
upload becomes the owner of the object. Keep in mind that to overwrite an
object, the person performing the overwrite (and is gaining ownership of
the object by doing so) must have
OWNER permission on the bucket in
which the object is being uploaded.