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 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 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, Compute Engine exports of usage reports or custom images, Cloud Audit Logs, Cloud SQL Exports, Cloud Spanner, Cloud Billing, 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.
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 Requesterrors.
JSON API requests for a full projection of bucket or object metadata include an empty ACL list as part of the response.
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
Public caching is not supported.
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 two metrics that track ACL usage. Use these metrics to determine what, if any, impact enabling Bucket Policy Only:
||The number of object requests that succeed now, but would fail if Bucket Policy Only was enabled.|
||The number of requests sent to modify object ACLs.|
For more information on Stackdriver metrics, see Metrics, Time Series, and Resources.
If these metrics indicate 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.
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|