Bucket Policy Only

This page discusses the Bucket Policy Only feature, which allows you to uniformly control access to your Cloud Storage resources. When enabled on a bucket, only bucket-level Cloud Identity and Access Management (Cloud IAM) permissions grant access to that bucket and the objects it contains; Access Control Lists (ACLs) are disabled and access granted by ACLs is revoked. For a guide to using this feature, see Using Bucket Policy Only.


Cloud Storage offers two systems for granting users permission to access your buckets and objects: Cloud Identity and Access Management (Cloud IAM) and Access Control Lists (ACLs). These systems act in parallel - in order for a user to access a Cloud Storage resource, only one of the systems needs to grant the user permission. Cloud IAM is used throughout Google Cloud Platform (GCP) and allows you to grant fine-grained permissions at the bucket and project levels. ACLs are used only by Cloud Storage and have fewer permission options, but allow you to grant permissions on a per-object basis.

In order to support a uniform permissioning system, Cloud Storage has the Bucket Policy Only feature. Using this feature disables ACLs for all Cloud Storage resources: access to Cloud Storage resources then is granted exclusively through Cloud IAM.

Should you use Bucket Policy Only?

Use the Bucket Policy Only feature if:

  • You want to control access to Cloud Storage resources through a single permissioning system.

  • You want to have a consistent access control experience across your GCP resources.

  • You have many objects in your bucket, and you do not want to manage access to each one individually.

  • You want to use GCP security features such as Cloud Audit Logs and Domain Restricted Sharing, which only track access granted through Cloud IAM policies, not ACLs.

  • You do not want the uploader of an object to always have full control of the object.

Do not use the Bucket Policy Only feature if:

  • You want to grant access to specific objects in a bucket via legacy ACLs.

  • You want the uploader of an object to have full control over that object, but less access to other objects in your bucket.


The following restriction applies when using Bucket Policy Only:

  • Certain GCP services that export to Cloud Storage cannot export to buckets that have Bucket Policy Only enabled. These services include:

    Stackdriver, Cloud Audit Logs, and Cloud Datastore.

  • You cannot use the XML API to check the status of, enable, or disable Bucket Policy Only.

  • You cannot use the XML API to view or set permissions for buckets with Bucket Policy Only enabled.

  • The value of Cache-Control is set to private by default for publicly accessible objects in Bucket Policy Only-enabled buckets, unless you explicitly set the value to public.

Behavior when enabled

You can enable Bucket Policy Only either when you create a new bucket, or when you explicitly enable Bucket Policy Only on an existing bucket.

Once enabled, the following ACL functionality ceases:

  • Requests to set, read, or modify bucket and object ACLs fail with 400 Bad Request errors.

  • JSON API requests made using BucketAccessControls, DefaultObjectAccessControls, and ObjectAccessControls methods fail with 400 Bad Request errors.

  • JSON API requests for a full projection of bucket or object metadata include an empty ACL list as part of the response.

  • The gsutil commands cp -p, mv -p, and rsync -p fail (both when the Bucket Policy Only bucket is the source and when it's the destination).

  • Individual object ownership no longer exists; access that is granted from such ownership is revoked, and requests for bucket and object metadata no longer contain an owner field.

Additionally, if you enable Bucket Policy Only as part of creating a new bucket, the bucket automatically receives additional Cloud IAM roles. This behavior maintains the permissioning that objects inherited from the bucket's default object ACLs. If you enable Bucket Policy Only on an existing bucket, you must apply any such roles manually; you may want to apply a different set of roles if you have changed the bucket's default object ACLs.

Behavior if reverted

To support the ability to disable Bucket Policy Only and revert to using ACLs, Cloud Storage saves existing ACLs for 90 days. If you disable Bucket Policy Only during this time:

  • Objects regain their saved ACLs.

  • Any objects added to the bucket after Bucket Policy Only was enabled gain ACLs according to the default object ACLs used by the bucket.

Considerations when migrating an existing bucket

When you enable Bucket Policy Only on an existing bucket, you should ensure that users and services that previously relied on ACLs for access have their permissions migrated to Cloud IAM. This section outlines some steps you should take when migrating a bucket to Bucket Policy Only. Note that since ACLs and Cloud IAM are synchronized for bucket permissions, your considerations focus specifically on access to objects within your bucket and not on access to the bucket.

Consider whether a bucket-level IAM permission overexposes data

Before assigning Cloud IAM equivalents to your ACLs, consider the following:

  • A Cloud IAM permission applied at the bucket level applies to all objects in the bucket, whereas object ACLs may vary from object to object.

If there is access that you want to apply to some objects but not others, you should group objects into separate buckets. Each grouping should contain those objects that have the same permissions.

Check object ACL usage

When migrating to Bucket Policy Only, you should check to see if objects in the bucket are being accessed through the ACLs applied to them. To check this, Stackdriver has a metric that tracks ACL usage. If this metric indicates users or services rely on ACLs for access to your objects, you should assign Cloud IAM equivalents to the bucket before enabling Bucket Policy Only. For a guide to checking ACL usage in Stackdriver, see Check for ACL usage.

Use this metric to determine if enabling Bucket Policy Only would break your workflow:

Metric Description
storage.googleapis.com/authz/acl_operations_count The number of ACL operations that will be disabled once Bucket Policy Only is enabled, broken down by ACL operation type and bucket.

An important ACL operation to examine is OBJECT_ACCESS_REQUIRED_OBJECT_ACL:

  • If this number is zero, no object level ACLs were required to access objects within the past 6 weeks. Cloud IAM policies are covering the necessary permissions at the bucket or project level.

  • If this number is greater than zero, there were requests to access objects within the past 6 weeks that required object ACL permissions. You should assign equivalent Cloud IAM policies before enabling Bucket Policy Only.

For more information on Stackdriver metrics, see Metrics, Time Series, and Resources.

Check the bucket's default object ACL

All buckets have a default object ACL associated with them. New objects added to a bucket have this default object ACL applied to them unless an ACL is explicitly supplied at the time the object is added to the bucket.

Prior to enabling Bucket Policy Only, check the default object ACL that your bucket has. Consider whether you want to grant the permissions associated with the default object ACL after you've enabled Bucket Policy Only. If so, assign Cloud IAM equivalents to the bucket.

Assign Cloud IAM equivalents to object ACLs

Object ACLs may grant access that Cloud IAM currently does not. To ensure existing users do not lose access to objects when you enable Bucket Policy Only, use the following table and assign affected users the appropriate Cloud IAM roles.

Object ACL permission Equivalent Cloud IAM role
READER roles/storage.legacyObjectReader
OWNER roles/storage.legacyObjectOwner

What's next

هل كانت هذه الصفحة مفيدة؟ يرجى تقييم أدائنا:

إرسال تعليقات حول...

هل تحتاج إلى مساعدة؟ انتقل إلى صفحة الدعم.