Uniform bucket-level access

Setup

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.

Overview

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. Uniform bucket-level access cannot be disabled after it has been active on a bucket for 90 consecutive days.

Should you use uniform bucket-level access?

Generally, using uniform bucket-level access is recommended:

  • Uniform bucket-level access unifies and simplifies how you grant access to your Cloud Storage resources.

  • Uniform bucket-level access prevents unintended data exposure from ACLs.

  • Uniform bucket-level access must be enabled to use the following features:

  • Uniform bucket-level access must be enabled to grant Workforce Identity Federation or Workload Identity Federation entities access to Cloud Storage resources.

You shouldn't use uniform bucket-level access if you want to use the ACLs system for your bucket.

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.

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

    • This behavior maintains the permissioning that objects would have inherited from the standard default object ACL for a bucket.

    • If you enable uniform bucket-level access on an existing bucket, you must apply any such roles manually; if you have previously changed the bucket's default object ACL, you likely want to apply a different set of IAM roles.

Behavior if reverted

To support the ability to disable uniform bucket-level access and revert to using ACLs, Cloud Storage saves existing ACLs. If you disable uniform bucket-level access:

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

Buckets without uniform bucket-level access have a default object ACL associated with them. New objects added to such buckets have this default object ACL applied to them unless an ACL is explicitly supplied at the time the object is added to the bucket.

For example, buckets commonly use the projectPrivate predefined ACL as their default object ACL. projectPrivate grants the object READER permission to the project viewers associated with the bucket, and it grants the object OWNER permission to the project editors and owners associated with 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 can 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:

What's next