Uniform bucket-level access

Stay organized with collections Save and categorize content based on your preferences.

Go to examples

This page discusses uniform bucket-level access, which allows you to uniformly control access to your Cloud Storage resources. When you enable uniform bucket-level access on a bucket, Access Control Lists (ACLs) are disabled, and only bucket-level Identity and Access Management (IAM) permissions grant access to that bucket and the objects it contains. You revoke all access granted by object ACLs and the ability to administrate permissions using bucket ACLs.


Cloud Storage offers two systems for granting users permission to access your buckets and objects: 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. IAM is used throughout Google Cloud and allows you to grant a variety of permissions at the bucket and project levels. ACLs are used only by Cloud Storage and have limited permission options, but they allow you to grant permissions on a per-object basis.

In order to support a uniform permissioning system, Cloud Storage has uniform bucket-level access. Using this feature on a bucket disables ACLs for all Cloud Storage resources in the bucket; access to Cloud Storage resources then is granted exclusively through IAM. After you enable uniform bucket-level access, you can reverse your decision for 90 days.

Should you use uniform bucket-level access?

Generally, using uniform bucket-level access is recommended, because it unifies and simplifies how you grant access to your Cloud Storage resources.

Using uniform bucket-level access also enables you to use other Google Cloud security features such as domain restricted sharing, workforce identity federation, and IAM Conditions.

You might not want to use uniform bucket-level access and instead retain fine-grained ACLs if:

  • You want to control 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.

  • You use the XML API to view or set permissions for buckets.

Behavior when enabled

You can enable uniform bucket-level access either when you create a new bucket, or when you explicitly enable uniform bucket-level access on an existing bucket.

Once enabled, a bucket has the following behavior:

  • Requests to set, read, or modify bucket and object ACLs 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 uniform bucket-level access bucket is the source and when it's the destination). The gsutil commands acl and defacl also fail.

  • 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.

  • At creation time, buckets receive specialized IAM roles. If you enable uniform bucket-level access as part of creating a new bucket, that bucket gets additional IAM roles as noted in the linked table.

    • This behavior maintains the permissioning that objects inherited from the bucket's default object ACLs.

    • If you enable uniform bucket-level access 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 uniform bucket-level access and revert to using ACLs, Cloud Storage saves existing ACLs for 90 days. If you disable uniform bucket-level access during this time:

  • Objects regain their saved ACLs.

  • Any objects added to the bucket after uniform bucket-level access was enabled gain ACLs according to the default object ACLs used by the bucket.

Considerations when migrating an existing bucket

When you enable uniform bucket-level access on an existing bucket, you should ensure that users and services that previously relied on ACLs for access have their permissions migrated to IAM. This section outlines some steps you should take when migrating a bucket to uniform bucket-level access. Note that since ACLs and 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 IAM equivalents to your ACLs, consider the following:

  • An 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 uniform bucket-level access, you should check to see if objects in the bucket are being accessed through the ACLs applied to them. To check this, Cloud Monitoring 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 IAM equivalents to the bucket before enabling uniform bucket-level access. For a guide to checking ACL usage in Monitoring, see Check for ACL usage.

Use this metric to determine if enabling uniform bucket-level access would break your workflow:

Metric Description
storage.googleapis.com/authz/acl_operations_count The number of ACL operations that will be disabled once uniform bucket-level access 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. 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 IAM policies before enabling uniform bucket-level access.

For more information on Monitoring 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 uniform bucket-level access, 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 uniform bucket-level access. If so, assign IAM equivalents to the bucket.

Assign IAM equivalents to object ACLs

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

Object ACL permission Equivalent IAM role
READER Storage Legacy Object Reader (roles/storage.legacyObjectReader)
OWNER Storage Legacy Object Owner (roles/storage.legacyObjectOwner)

Considerations when using IAM Conditions

To prevent conflicts between a bucket's IAM policies and object ACLs, IAM Conditions can only be used on buckets with uniform bucket-level access enabled. This means:

  • To set IAM Conditions on a bucket, you must first enable uniform bucket-level access on that bucket.

  • To disable uniform bucket-level access on a bucket, you must first remove all IAM Conditions from that bucket's policy. For information on how to view and remove conditions from a bucket's policy, see Using IAM Conditions on bucket. Note that uniform bucket-level access cannot be disabled if it has been active on a bucket for 90 consecutive days.

What's next