Setup

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

Note: Enabling uniform bucket-level access on a bucket is required for creating andmanaging managed folders in that bucket.

Overview

Cloud Storage offers two systems for granting users permission toaccess your buckets and objects:IAM andAccess Control Lists (ACLs). These systems act in parallel - in order fora user to access a Cloud Storage resource, only one of the systemsneeds to grant the user permission. IAM is used throughoutGoogle Cloud and allows you to grant a variety of permissions at thebucket and project levels. ACLs are used only by Cloud Storage and havelimited permission options, but they allow you to grant permissions on aper-object basis.

In order to support a uniform permissioning system, Cloud Storage hasuniform bucket-level access. Using this feature on a bucket disables ACLs for allCloud Storage resources in the bucket; access to Cloud Storageresources then is granted exclusively through IAM. Uniform bucket-level accesscannot be disabled after it has been active on a bucket for 90 consecutive days.

Caution: If you enable uniform bucket-level access, you revoke access from users whogain their access solely through object ACLs and prevent users fromadministrating permissions using bucket ACLs. Be sure that you readconsiderations when migrating an existing bucket prior to enablinguniform bucket-level access.

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 yourCloud Storage resources.

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

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

  • Hierarchical namespace
  • Managed folders
  • IAM conditions set directly on the bucket

• Uniform bucket-level access must be enabled to grantWorkforce Identity Federation orWorkload Identity Federation entitiesaccess to Cloud Storage resources.

  Note: Even when uniform bucket-level access is disabled, Workforce Identity Federationand Workload Identity Federation entities can be added to ACLs andIAM policies, but doing so does not grant the entities anyaccess to Cloud Storage resources, unless you subsequently enableuniform bucket-level access.

You shouldn't use uniform bucket-level access ifyou want to use the ACLs systemfor your bucket.

Behavior when enabled

You can enable uniform bucket-level access either when you create a new bucket, or whenyou explicitlyenable 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 with400 Bad Request errors.

  • This includes JSON API requests using anyBucketAccessControls,DefaultObjectAccessControls, orObjectAccessControlsmethods.

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

• Individualobject ownership no longer exists; access that is grantedfrom such ownership is revoked, and requests for bucket and objectmetadata no longer contain anowner field.

• At creation time, buckets receive specialized IAM roles.If you enable uniform bucket-level access as part of creating a new bucket, thatbucket getsadditional IAM roles.

  • This behavior maintains the permissioning that objects would haveinherited from the standarddefault object ACL for a bucket.

  • If you enable uniform bucket-level access on an existing bucket, you must applyany such roles manually; if you have previously changed the bucket'sdefault object ACL, you likely want to apply a different set ofIAM 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 gainACLs according to thedefault object ACLs used by the bucket.

Requirements for disabling uniform bucket-level access

In order to disable uniform bucket-level access, the following must be true:

• The feature has been enabled for less than 90 consecutive days.

• You haveremoved any IAM conditions from the bucket'sIAM policy.

• The bucket is not subject to theRequire uniform bucket-level accessorganization policy constraint.

• You have deleted anymanaged folders from the bucket.

Considerations when migrating an existing bucket

When you enable uniform bucket-level access on an existing bucket, you should ensurethat users and services that previously relied on ACLs for access have theirpermissions migrated to IAM. This section outlines some stepsyou should take when migrating a bucket to uniform bucket-level access. Note that sinceACLs and IAM aresynchronized for bucket permissions, yourconsiderations focus specifically on access to objects within your bucket andnot on access to the bucket.

Consider whether a bucket-level IAM permission overexposes data

Before assigning IAM equivalents to your ACLs, consider thefollowing:

• An IAM permission applied at the bucket level applies toall objects in the bucket, whereas object ACLs can vary from object toobject.

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

Check object ACL usage

When migrating to uniform bucket-level access, you should check to see if objects inthe bucket are being accessed through the ACLs applied to them. To check this,Cloud Monitoring has a metric that tracks ACL usage. If this metricindicates users or services rely on ACLs for access to your objects, you shouldassignIAM equivalents to the bucket beforeenabling uniform bucket-level access. For a guide to checking ACL usage inMonitoring, seeCheck for ACL usage.

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

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.

Caution: Since this metric contains personally identifiable information (PII)such as project ID and bucket name, only ACL usage within the past6 weeksappears in Monitoring. Enabling uniform bucket-level access might stillbreak your workflow if ACLs were used more than 6 weeks ago.

An important ACL operation to examine isOBJECT_ACCESS_REQUIRED_OBJECT_ACL:

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

• If this number is greater than zero, there were requests to access objectswithin the past 6 weeks that required object ACL permissions. You shouldassignequivalent IAM policies beforeenabling uniform bucket-level access.

For more information on Monitoring metrics, seeMetrics, Time Series, and Resources.

Check the bucket's default object ACL

Buckets without uniform bucket-level access have adefault object ACL associatedwith them. New objects added to such buckets have this default object ACLapplied to them unless an ACL is explicitly supplied at the time the object isadded to the bucket.

For example, buckets commonly use theprojectPrivate predefined ACL as theirdefault object ACL.projectPrivate grants the objectREADER permission totheproject viewers associated with the bucket, and it grants the objectOWNER permission to the project editors and owners associated with the bucket.

Prior to enabling uniform bucket-level access,check the default object ACL thatyour bucket has. Consider whether you want to grant the permissions associatedwith the default object ACL after you've enabled uniform bucket-level access. If so,assignIAM equivalents to the bucket.

Assign IAM equivalents to object ACLs

Object ACLs can grant access that IAM currently does not. Toensure existing users do not lose access to objects when you enableuniform bucket-level access, use the following table andassign 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 objectACLs,IAM Conditions can only be used on buckets withuniform bucket-level access enabled. This means:

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

• Before you candisable uniform bucket-level access on a bucket, you must firstremove all IAM Conditions from that bucket's policy. Forinformation on how to view and remove conditions from a bucket's policy, seeUsing IAM Conditions on bucket.

What's next

• Learn how touse uniform bucket-level access.
• Learn about theenforce uniform bucket-level access constraint, whichyou can set within your Google Cloud organization, folder, or project.
• Set IAM permissions on buckets and projects.