This page describes how to control access to buckets and objects using Access Control Lists (ACLs). ACLs are a mechanism you can use to define who has access to your buckets and objects, as well as what level of access they have.
See the ACL overview to learn more about whether you should use ACLs for controlling access to your resources.
Set ACLs
Console
Go to the Cloud Storage browser in the Google Cloud console.
Go to the Cloud Storage browserNavigate to the object whose ACL you want to modify.
Choose Edit access from the more actions menu (
) associated with the object.
You should see a permission dialog that looks like:
This screenshot shows an ACL with four entries:
- In the first entry, all owners of a specific project (one whose project number is 867489140601) receive "Owner" access/permission for this object.
- In the second entry, all editors of a specific project (one whose project number is 867489140601) also receive "Owner" access/permission for this object.
- In the third entry, all viewers of a specific project (one whose project number is 867489140601) receive "Reader" access/permission for this object.
- In the fourth entry, the user who uploaded the object receives "Owner" access/permission for the object. Object uploaders are always set as an "Owner" and cannot be removed.
Click Add item.
Choose the type of Entity to give permission to.
Entity specifies the type of thing that's getting the permission (for example a user or a group). Refer to Access Control Scopes for a list of supported values for Entity.
Enter a value in Name.
Name identifies a specific user, group, or other entity type. Refer to Access Control Scopes for a list of supported values for Name.
Together, Entity and Name define who the permission applies to.
Choose a value in Access.
Access defines the permission that you want to set on the object. Refer to Access Control Permissions for a list of supported values for Access.
Click Save.
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
gsutil
Use gsutil acl
to specify ACLs:
To specify individual grants:
gsutil acl ch -u USER_EMAIL:PERMISSION gs://BUCKET_NAME
To specify canned ACLs:
gsutil acl set CANNED_ACL_NAME gs://BUCKET_NAME
To specify ACLs in JSON format:
gsutil acl set JSON_FILE gs://BUCKET_NAME
where
JSON_FILE
contains ACLs specified in JSON format.
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds an ACL to a bucket: The following sample adds an ACL to an object:
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds an ACL to a bucket: The following sample adds an ACL to an object:
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds an ACL to a bucket: The following sample adds an ACL to an object:
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds an ACL to a bucket: The following sample adds an ACL to an object:
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds an ACL to a bucket: The following sample adds an ACL to an object:
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds an ACL to a bucket: The following sample adds an ACL to an object:
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds an ACL to a bucket: The following sample adds an ACL to an object:
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds an ACL to a bucket: The following sample adds an ACL to an object:C++
C#
Go
Java
Node.js
PHP
Python
Ruby
JSON API
When creating a bucket, you can specify the acl[]
property in
an insert request. For an existing bucket, specify the acl[]
property in a patch or update request.
When creating an object, you can specify the acl[]
property in
the request body or the predefinedAcl
query parameter in an insert
request. For an existing object, specify the acl[]
property or the
predefinedAcl
query parameter in a patch or update request.
For definitions of the bucket and object ACL properties, see the
BucketAccessControls
and ObjectAccessControls
resources, respectively.
The following example shows different bucket ACL entries.
"acl": [ { "kind": "storage#bucketAccessControl", "id": "example-bucket/project-owners-123412341234", "selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/project-owners-123412341234", "bucket": "example-bucket", "entity": "project-owners-123412341234", "role": "OWNER", "projectTeam": { "projectNumber": "123412341234", "team": "owners" }, "etag": "CDk=" }, { "kind": "storage#bucketAccessControl", "id": "example-bucket/project-editors-123412341234", "selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/project-editors-123412341234", "bucket": "example-bucket", "entity": "project-editors-123412341234", "role": "OWNER", "projectTeam": { "projectNumber": "123412341234", "team": "editors" }, "etag": "CDk=" }, { "kind": "storage#bucketAccessControl", "id": "example-bucket/project-viewers-123412341234", "selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/project-viewers-123412341234", "bucket": "example-bucket", "entity": "project-viewers-123412341234", "role": "READER", "projectTeam": { "projectNumber": "123412341234", "team": "viewers" }, "etag": "CDk=" }, { "kind": "storage#bucketAccessControl", "id": "example-bucket/group-gs-announce@googlegroups.com", "selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/group-gs-announce@googlegroups.com", "bucket": "example-bucket", "entity": "group-gs-announce@googlegroups.com", "role": "READER", "email": "gs-announce@googlegroups.com", "etag": "CDk=" }, { "kind": "storage#bucketAccessControl", "id": "example-bucket/user-jane@gmail.com", "selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/user-jane@gmail.com", "bucket": "example-bucket", "entity": "user-jane@gmail.com", "role": "READER", "email": "jane@gmail.com", "etag": "CDk=" }, { "kind": "storage#bucketAccessControl", "id": "example-bucket/allUsers", "selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/allUsers", "bucket": "example-bucket", "entity": "allUsers", "role": "READER", "etag": "CDk=" }, { "kind": "storage#bucketAccessControl", "id": "example-bucket/allAuthenticatedUsers", "selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/allAuthenticatedUsers", "bucket": "example-bucket", "entity": "allAuthenticatedUsers", "role": "READER", "etag": "CDk=" } ]
XML API
In the XML API, you work with ACLs in XML format. You must attach an XML document to the body of requests to change bucket and object ACLs. An XML document is returned when you get bucket and object ACLs. The XML document contains the individual bucket or object ACL entries.
After creating a bucket with a
PUT
Bucket request, use a second PUT Bucket request with the?acl
parameter to change the bucket ACL.After uploading an object with a
PUT
Object request, change the ACL with another PUT request using the?acl
parameter or thex-googl-acl
request header.
Use the following ACL syntax for the XML API.
Element | Description |
---|---|
AccessControlList |
Container for Entries and Owner elements. |
Owner |
Container for DisplayName and ID elements. This element is not required for objects since an object is always owned by the user who uploaded it. This element is used when you are using Amazon S3 ACL syntax in a migration scenario. Amazon Simple Storage Service and Amazon S3 are trademarks of Amazon.com, Inc. or its affiliates in the United States and/or other countries. |
ID |
Google Cloud Storage ID of the bucket owner. |
DisplayName |
Not currently implemented. The value is always an empty string. |
Entries |
Container for zero or more Entry elements. |
Entry |
Container for Scope and Permission elements. An Entry must contain only one Scope and one Permission element. |
Scope |
Container for an ID , EmailAddress , or Domain element that defines the ACL scope. This element must have a type attribute that contains one of the following values: UserByID , UserByEmail , GroupByID , GroupByEmail , GroupByDomain , AllUsers , or AllAuthenticatedUsers . |
ID |
An identifier for the grantee when the permission entry is specified by ID. |
EmailAddress |
The email identifier for the grantee when the permission entry is specified by email. |
Domain |
The domain identifier for the grantee when the permission entry is specified by domain. |
Name |
Optional element that can be specified or that can be automatically added if the scope is UserByEmail or GroupByEmail . |
Permission |
The permission granted READ , WRITE , or FULL_CONTROL . |
When working with ACLs using the XML API:
- You can only use the XML format described above.
You cannot set duplicate scopes.
You can have many entries in your ACL XML, but you cannot have entries with duplicate scopes. For example, you cannot have two entries with the same scope element of
jane@example.com
.
The following example shows different bucket ACL entries:
<?xml version="1.0" encoding="UTF-8"?> <AccessControlList> <Owner> <ID>00b4903a9721...</ID> </Owner> <Entries> <Entry> <Scope type="GroupById"> <ID>00b4903a9722...</ID> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type="GroupById"> <ID>00b4903a9723...</ID> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type="GroupById"> <ID>00b4903a9724...</ID> </Scope> <Permission>READ</Permission> </Entry> <Entry> <Scope type="GroupByDomain"> <Domain>example.com</Domain> </Scope> <Permission>READ</Permission> </Entry> <Entry> <Scope type="GroupByEmail"> <EmailAddress>gs-announce@googlegroups.com</EmailAddress> </Scope> <Permission>READ</Permission> </Entry> <Entry> <Scope type="UserByEmail"> <EmailAddress>jane@gmail.com</EmailAddress> <Name>jane</Name> </Scope> <Permission>READ</Permission> </Entry> <Entry> <Scope type="AllUsers"/> <Permission>READ</Permission> </Entry> <Entry> <Scope type="AllAuthenticatedUsers"/> <Permission>READ</Permission> </Entry> </Entries> </AccessControlList>
Set the Name element in ACL XML
When you retrieve an ACL from a bucket or object, you might notice an additional
<Name>
element appended to some of your entries. For example, you might see an
entry that looks like the following:
<Entry> <Scope type="UserByEmail"> <EmailAddress>jane@gmail.com</EmailAddress> <Name>Jane</Name> </Scope> <Permission>FULL_CONTROL</Permission> </Entry>
These optional <Name>
elements are populated in two circumstances:
When the bucket or object's ACLs include
<Name>
as an element.When you set ACLs, you can choose to include the
<Name>
element with your ACL entries. You can provide any value in the<Name>
element, and Cloud Storage remembers these values until the ACL is removed or replaced. This approach can be useful if you are using identifiers that aren't easily identifiable, like Google Cloud Storage IDs.When a
UserByEmail
orGroupByEmail
scope contains a public Google profile.If you use either of these scopes but do not provide a
<Name>
element, Cloud Storage checks if the user or Google Group associated with the email address has a public Google profile with a public name. If so, Cloud Storage automatically populates the<Name>
element with the public name.
Apply a predefined ACL
Rather than specifying the entire ACL one entry at a time as shown above, you can use a predefined ACL, which will automatically apply a number of entries customized to a specific scenario. You can apply a predefined ACL to either a bucket or an object by using gsutil, the JSON API, or the XML API.
On new objects
To apply a predefined ACL to an object during object upload:
Console
You cannot apply a predefined ACL using the Google Cloud console. Use gsutil instead.
gsutil
Use the -a
option with the gsutil cp
command to apply the predefined ACL:
gsutil cp -a PREDEFINED_ACL OBJECT gs://BUCKET_NAME
For example, to apply the predefined ACL bucket-owner-read
while
uploading an object paris.jpg
to a bucket example-travel-maps
:
gsutil cp -a bucket-owner-read paris.jpg gs://example-travel-maps
JSON API
Use the predefinedAcl
query string parameter in an insert request to
apply the prefined ACL.
For example, to apply the predefined ACL bucketOwnerRead
while uploading
an object paris.jpg
to a bucket example-travel-maps
:
curl -X POST --data-binary @paris.jpg -H "Content-Type: image/jpeg"
-H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
"https://storage.googleapis.com/upload/storage/v1/b/example-travel-maps/o?name=paris.jpg&predefinedAcl=bucketOwnerRead"
The request looks like the following example:
POST /upload/storage/v1/b/example-travel-maps/o?name=paris.jpg&predefinedAcl=bucketOwnerRead HTTP/1.1 Host: www.googleapis.com Content-Type: image/jpeg Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg Content-Length: 12345 Date: Fri, 10 Oct 2014 00:02:38 GMT
XML API
Use the x-goog-acl
header in a Put Object request to apply the
predefined ACL.
For example, to apply the predefined ACL bucket-owner-read
while
uploading an object paris.jpg
to a bucket example-travel-maps
:
curl -X PUT --upload-file paris.jpg -H "x-goog-acl: bucket-owner-read"
-H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
https://storage.googleapis.com/example-travel-maps/paris.jpg
The request looks like the following example:
PUT /paris.jpg HTTP/1.1 Host: example-travel-maps.storage.googleapis.com Date: Thu, 09 Oct 2014 23:06:08 GMT Content-Length: 12345 Content-Type: image/jpg x-goog-acl: bucket-owner-read Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg 12345 bytes in entity body
On existing buckets or objects
You can also apply a predefined ACL to an existing bucket or object, which is useful if you want to change from one predefined ACL to another, or you want to update custom ACLs to a predefined ACL.
Console
You cannot apply a predefined ACL using the Google Cloud console. Use gsutil instead.
gsutil
Use the gsutil acl set
command to apply the predefined ACL:
gsutil acl set PREDEFINED_ACL gs://BUCKET_NAME/OBJECT_NAME
For example, to apply the predefined ACL private
to the object
paris.jpg
in the bucket example-travel-maps
:
gsutil acl set private gs://example-travel-maps/paris.jpg
JSON API
Use the predefinedAcl
query string parameter, and specify an empty acl
property in a patch request to apply the prefined ACL.
For example, to apply the predefined ACL private
to the object
paris.jpg
in the bucket example-travel-maps
:
curl -X PATCH --data '{"acl": []}' -H "Content-Type: application/json"
-H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
https://storage.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg?predefinedAcl=private
The request looks like the following example:
PATCH /storage/v1/b/example-travel-maps/o/paris.jpg?predefinedAcl=private HTTP/1.1 Host: www.googleapis.com Content-Type: application/json Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg Content-Length: 11 Date: Fri, 10 Oct 2014 18:57:59 GMT
XML API
Use the x-goog-acl
header with the acl
query string parameter in a
Put Object request, but do not include an XML document in your request.
For example, to apply the predefined ACL private
to the object
paris.jpg
in the bucket example-travel-maps
:
curl -X PUT -H "Content-Length: 0"
-H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
-H "x-goog-acl: private" https://storage.googleapis.com/example-travel-maps/paris.jpg?acl
The request looks like the following example:
PUT /paris.jpg?acl HTTP/1.1 Host: example-travel-maps.storage.googleapis.com Date: Thu, 09 Oct 2014 23:14:59 GMT Content-Length: 0 x-goog-acl: private Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg empty entity body
Set default object ACLs
To avoid setting ACLs every time you create a new object, you can set a default object ACL on a bucket. After you do this, every new object that is added to that bucket that does not explicitly have an ACL applied to it will have the default applied to it. For example, you might want to specify that only a certain group of users have access to most objects in a particular bucket. You can change the default object ACL, and then add objects to the bucket. These added objects have the default object ACL you specified automatically applied to them; however, you can give specific objects different ACLs, in which case those objects do not have the default ACL applied to them.
To view and change the default object ACL for a bucket:
Console
You cannot set default object ACLs using the Google Cloud console. Use gsutil instead.
gsutil
Use
gsutil defacl
to retrieve the default object ACL:gsutil defacl get gs://BUCKET_NAME
Use
gsutil defacl ch
orgsutil defacl set
to modify the default object ACL.For example, the following command adds
jane@gmail.com
to the default object ACL for a bucketexample-travel-maps
:gsutil defacl ch -u jane@gmail.com:READER gs://example-travel-maps
You can also specify the default object ACL from a file. For more information, see the help for
gsutil defacl
.
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds a default object ACL to a bucket: The following sample deletes a default object ACL from a bucket:
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample prints the default object ACL for a bucket: The following sample adds a default object ACL to a bucket: The following sample deletes a default object ACL from a bucket:
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds a default object ACL to a bucket: The following sample deletes a default object ACL from a bucket:
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds a default object ACL to a bucket: The following sample deletes a default object ACL from a bucket:
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds a default object ACL to a bucket: The following sample deletes a default object ACL from a bucket:
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds a default object ACL to a bucket: The following sample deletes a default object ACL from a bucket:
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds a default object ACL to a bucket: The following sample deletes a default object ACL from a bucket:
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds a default object ACL to a bucket: The following sample deletes a default object ACL from a bucket:C++
C#
Go
Java
Node.js
PHP
Python
Ruby
JSON API
Retrieve the default object ACL with a GET request. For example:
curl -X GET -H "Authorization: Bearer OAUTH2_TOKEN"
https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?projection=fullUse a patch request to replace the default object ACL. For example, the following request replaces the default object ACL with the ACL specified in
defacls.json
for a bucketexample-travel-maps
:curl -X PATCH --data @defacls.json -H "Content-Type: application/json" -H "Authorization: Bearer OAUTH2_TOKEN"
https://storage.googleapis.com/storage/v1/b/example-travel-mapsAn example of
defacls.json
:{ "defaultObjectAcl": [ { "email": "jane@gmail.com", "entity": "user-jane@gmail.com", "role": "READER" } ] }
XML API
Retrieve the default object ACL with a
GET
request scoped to your bucket and the?defaultObjectAcl
parameter. For example:curl -X GET -H "Authorization: Bearer OAUTH2_TOKEN"
https://storage.googleapis.com/BUCKET_NAME?defaultObjectAclUse a
PUT
request scoped to your bucket with the?defaultObjectAcl
parameter to replace the default object ACL with the ACL specified inacls.xml
. For example:curl -X PUT --data-binary @acls.xml -H "Authorization: Bearer OAUTH2_TOKEN"
http://storage.googleapis.com/BUCKET_NAME?defaultObjectAclAn example of
acls.xml
:<AccessControlList> <Entries> <Entry> <Permission>
FULL_CONTROL
</Permission> <Scope type="GroupByEmail"> <EmailAddress>travel-companions@googlegroups.com</EmailAddress> </Scope> </Entry> </Entries> </AccessControlList>
The syntax of ACLs is discussed in Setting ACLs. You can also specify a predefined ACL as the default object ACL.
To set the default object ACL for a bucket to a predefined ACL:
Console
You cannot set default object ACLs using the Google Cloud console. Use gsutil instead.
gsutil
Use the gsutil defacl
command with the name of the predefined ACL.
For example, to set the default object ACL to project-private
for the
bucket example-travel-maps
:
gsutil defacl set project-private gs://example-travel-maps
JSON API
Use a PUT request and the predefinedAcl
parameter.
For example:
curl -X PUT -H "Content-Length: 0" -H "Authorization: Bearer OAUTH2_TOKEN"
https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?predefinedAcl=private
XML API
Use a PUT
request scoped to your bucket with the ?defaultObjectAcl
parameter and the x-goog-acl
header.
For example:
curl -X PUT -H "x-goog-acl: project-private" -H "Content-Length: 0" -H "Authorization: Bearer OAUTH2_TOKEN"
http://storage.googleapis.com/BUCKET_NAME?defaultObjectAcl
The default object ACLs for a newly created bucket:
Shown below are the default object ACLs for a newly created bucket. Compare these to the default object ACLs of your bucket to see if your bucket's default object ACLs have been modified.
Console
You cannot work with default object ACLs using the Google Cloud console. Use gsutil instead.
gsutil
In the example below, the project ID is "123412341234"; your project ID will be different.
[ { "entity": "project-owners-123412341234", "projectTeam": { "projectNumber": "123412341234", "team": "owners" }, "role": "OWNER" }, { "entity": "project-editors-123412341234", "projectTeam": { "projectNumber": "123412341234", "team": "editors" }, "role": "OWNER" }, { "entity": "project-viewers-123412341234", "projectTeam": { "projectNumber": "123412341234", "team": "viewers" }, "role": "READER" } ]
JSON API
In the example below, the project ID is "123412341234"; your project ID will be different.
defaultObjectAcl": [ { "kind": "storage#objectAccessControl", "entity": "project-owners-123412341234", "role": "OWNER", "projectTeam": { "projectNumber": "123412341234", "team": "owners" } }, { "kind": "storage#objectAccessControl", "entity": "project-editors-123412341234", "role": "OWNER", "projectTeam": { "projectNumber": "123412341234", "team": "editors" } }, { "kind": "storage#objectAccessControl", "entity": "project-viewers-123412341234", "role": "READER", "projectTeam": { "projectNumber": "123412341234", "team": "viewers" } } ]
XML API
In the example below, the project role IDs start with "00b4903a97..."; your project IDs will be different.
<?xml version='1.0' encoding='UTF-8'?> <AccessControlList> <Entries> <Entry> <Scope type='GroupById'> <ID>00b4903a9721...</ID> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type='GroupById'> <ID>00b4903a9722...</ID> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type='GroupById'> <ID>00b4903a9723...</ID> </Scope> <Permission>READ</Permission> </Entry> </Entries> </AccessControlList>
Note that the default object ACL for a newly created bucket is equivalent to
the predefined projectPrivate
ACL.
Retrieving ACLs
To get the ACL of an existing bucket or object:
Console
Go to the Cloud Storage browser in the Google Cloud console.
Go to the Cloud Storage browserNavigate to the object whose ACL you want to view.
Choose Edit access from the drop down menu for the object.
You should see a permission dialog with the object's permissions.
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
gsutil
Use the gsutil acl get
to return an object's ACL.
For example, to return the ACL of the object paris.jpg
in the bucket
example-travel-maps
:
gsutil acl get gs://example-travel-maps/paris.jpg
Example response:
[ { "entity": "project-owners-123412341234", "projectTeam": { "projectNumber": "123412341234", "team": "owners" }, "role": "OWNER" }, { "entity": "project-editors-123412341234", "projectTeam": { "projectNumber": "123412341234", "team": "editors" }, "role": "OWNER" }, { "entity": "project-viewers-123412341234", "projectTeam": { "projectNumber": "123412341234", "team": "viewers" }, "role": "READER" }, { "email": "gs-announce@googlegroups.com", "entity": "group-gs-announce@googlegroups.com", "role": "READER" }, { "email": "jane@gmail.com", "entity": "user-jane@gmail.com", "role": "READER" }, { "entity": "allUsers", "role": "READER" }, { "entity": "allAuthenticatedUsers", "role": "READER" } ]
To return a bucket's ACL:
gsutil acl get gs://BUCKET_NAME
When gsutil returns ACLs for buckets and objects with gsutil acl get
,
they are in the same JSON format that you can use to set ACLs. ACLs in
JSON format use the JSON API property names, such as entity
and role
.
See the JSON API syntax for more information about how to interpret the output
or run gsutil help acls
.
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample gets a bucket ACL: The following sample gets an object ACL:
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample gets a bucket ACL: The following sample gets an object ACL:
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample gets a bucket ACL: The following sample gets an object ACL:
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample gets a bucket ACL: The following sample gets an object ACL:
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample gets a bucket ACL: The following sample gets an object ACL:
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample gets a bucket ACL: The following sample gets an object ACL:
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample gets a bucket ACL: The following sample gets an object ACL:
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample gets a bucket ACL: The following sample gets an object ACL:C++
C#
Go
Java
Node.js
PHP
Python
Ruby
JSON API
Make sure that you have
OWNER
permission on the bucket or object.Retrieve the bucket or object's ACL with a
GET
request.The object ACL is returned in JSON format, attached to the body of the response.
For example, to return the ACL for the object paris.jpg
in the bucket
example-travel-maps
:
curl -X GET -H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
https://storage.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg?projection=full
You should see a response that looks like:
{ "kind": "storage#object", "id": "example-travel-maps/paris.jpg/1412805837131000", "selfLink": "https://www.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg", "name": "paris.jpg", "bucket": "example-travel-maps", ... "acl": [ { ... "entity": "project-owners-867489160491", "role": "OWNER", "projectTeam": { "projectNumber": "867489160491", "team": "owners" }, ... }, { ... "entity": "user-jane@gmail.com", "role": "OWNER", "email": "jane@gmail.com", ... }, { ... "entity": "group-gs-announce@googlegroups.com", "role": "READER", "email": "gs-announce@googlegroups.com", ... } ], "owner": { "entity": "user-jane@gmail.com" }, ... }
You can also use the objectAccessControls
resource GET
method to
return individual entries in an object's ACL.
XML API
Make sure that you have
FULL_CONTROL
permission on the bucket or object.Retrieve the bucket or object's ACL by using the
acl
query string parameter in a GET Object request.
The ACLs are described in XML, attached to the body of the response.
For example, to return the ACL for the object paris.jpg
in the bucket
example-travel-maps
:
curl -X GET -H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
https://storage.googleapis.com/example-travel-maps/paris.jpg?acl
You should see a response that looks like:
<?xml version="1.0" encoding="UTF-8"?> <AccessControlList> <Owner> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> <Name>Owner Name</Name> </Owner> <Entries> <Entry> <Scope type="UserById"> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> <Name>Name</Name> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type="UserByEmail"> <EmailAddress>jane@gmail.com</EmailAddress> <Name>Jane</Name> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type="GroupByEmail"> <EmailAddress>gs-announce@googlegroups.com</EmailAddress> </Scope> <Permission>READ</Permission> </Entry> </Entries> </AccessControlList>
You can also use the JSON GET
method of the ObjectAccessControls
resource to return a specific ACL entry.
Changing ACLs
To change the ACL of an existing object or bucket:
Console
Go to the Cloud Storage browser in the Google Cloud console.
Go to the Cloud Storage browserNavigate to the object whose ACL you want to change.
Choose Edit access from the drop down menu for the object.
You should see a permission dialog with the object's permissions.
The following example shows how to grant the jane@gmail.com
user OWNER
permission
and the members of the gs-announce
group READER
permission on the
object paris.jpg
:
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
gsutil
Define the ACLs in a file.
Pass the ACLs file to
gsutil acl set
, and specify the object to set the ACLs on.
For example, to apply the ACLs from the file acls.txt
on an object
named paris.jpg
in the bucket example-travel-maps
:
gsutil acl set acl.txt gs://example-travel-maps/paris.jpg
The contents of acl.txt
are shown below. These ACLs grant the owners
of project 867489160491
along with the user jane@gmail.com
OWNER
permission for the object paris.jpg
, and they grant the members
of the gs-announce
group READER
permission for this object:
[ { "entity": "project-owners-867489160491", "role": "OWNER", "projectTeam": { "projectNumber": "867489160491", "team": "owners" }, }, { "entity": "user-jane@gmail.com", "email": "jane@gmail.com", "role": "OWNER" }, { "entity": "group-gs-announce@googlegroups.com", "email": "gs-announce@googlegroups.com", "role": "READER" } ]
You can also set the same ACL for this object with individual grants.
For example, to grant the jane@gmail.com
user READER
access use:
gsutil acl ch -u jane@gmail.com:READ gs://example-travel-maps/paris.jpg.
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample removes an ACL from a bucket: The following sample removes an ACL from an object:
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample removes an ACL from a bucket: The following sample removes an ACL from an object:
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample removes an ACL from a bucket: The following sample removes an ACL from an object:
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample removes an ACL from a bucket: The following sample removes an ACL from an object:
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample removes an ACL from a bucket:: The following sample removes an ACL from an object:
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample removes an ACL from a bucket: The following sample removes an ACL from an object:
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample removes an ACL from a bucket: The following sample removes an ACL from an object:
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample removes an ACL from a bucket: The following sample removes an ACL from an object:C++
C#
Go
Java
Node.js
PHP
Python
Ruby
JSON API
Define the ACLs in a JSON file.
Send a patch request with the JSON file, and specify the object to set the ACLs on.
For example, the following cURL command applies a JSON payload from the
document acls.json
to an object named paris.jpg
in the bucket
example-travel-maps
:
curl -X PATCH --data @acls.json -H "Content-Type: application/json"
-H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
https://storage.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg
If the ACL grants the owners of project 867489160491
and the user
jane@gmail.com
OWNER
permission, along with granting the members of the
gs-announce
group READER
permission, then the request looks like the
following example:
PATCH /storage/v1/b/example-travel-maps/o/paris.jpg HTTP/1.1 Host: www.googleapis.com Content-Type: application/json Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg Content-Length: 597 Date: Wed, 08 Oct 2014 22:37:58 GMT { "acl": [ { "entity": "project-owners-867489160491", "role": "OWNER", "projectTeam": { "projectNumber": "867489160491", "team": "owners" }, { "entity": "user-jane@gmail.com", "role": "OWNER", "email": "jane@gmail.com" }, { "entity": "group-gs-announce@googlegroups.com", "role": "READER", "email": "gs-announce@googlegroups.com" } ] }
XML API
Define the ACLs in an XML document.
Send a
PUT Object
request using theacl
query string parameter and the corresponding XML document.
The following cURL command applies an XML payload from the document
acls.xml
to an object named paris.jpg
in the bucket example-travel-maps
:
curl -X PUT --data-binary @acls.xml
-H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
https://storage.googleapis.com/example-travel-maps/paris.jpg?acl
If the ACL grants the jane@gmail.com
user FULL_CONTROL
permission and the
members of the gs-announce
group READ
permission, then the request looks like the following example:
PUT /paris.jpg?acl HTTP/1.1 Host: example-travel-maps.storage.googleapis.com Date: Sat, 20 Feb 2010 08:31:08 GMT Content-Length: 589 Content-Type=application/xml Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg <?xml version='1.0' encoding='utf-8'?> <AccessControlList> <Owner> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> </Owner> <Entries> <Entry> <Permission>FULL_CONTROL
</Permission> <Scope type="UserById"> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> </Scope> </Entry> <Entry> <Scope type="UserByEmail"> <EmailAddress>jane@gmail.com</EmailAddress> <Name>Jane</Name> </Scope> <Permission>FULL_CONTROL
</Permission> </Entry> <Entry> <Scope type="GroupByEmail"> <EmailAddress>gs-announce@googlegroups.com</EmailAddress> </Scope> <Permission>READ
</Permission> </Entry> </Entries> </AccessControlList>
What's next
- Learn more about ACLs.
- Learn how to simplify your access control using uniform bucket-level access.
- Learn about best practices when using ACLs.