Prerequisites for disabling ACLs - Amazon Simple Storage Service

Prerequisites for disabling ACLs

A bucket access control list (ACL) in Amazon S3 is a mechanism that allows you to define granular permissions for individual objects within an S3 bucket, specifying which AWS accounts or groups can access and modify those objects. A majority of modern use cases in Amazon S3 no longer require the use of ACLs. We recommend that you use AWS Identity and Access Management (IAM) and bucket policies to manage access, and to keep ACLs disabled, except in unusual circumstances where you need to control access for each object individually.

If you have ACLs enabled on your bucket, before you disable ACLs, complete the following prerequisites:

Review bucket and object ACLs and migrate ACL permissions

When you disable ACLs, permissions granted by bucket and object ACLs no longer affect access. Before you disable ACLs, review your bucket and object ACLs.

Each of your existing bucket and object ACLs has an equivalent in an IAM policy. The following bucket policy examples show you how READ and WRITE permissions for bucket and object ACLs map to IAM permissions. For more information about how each ACL translates to IAM permissions, see Mapping of ACL permissions and access policy permissions.

Before you disable ACLs:

  • If your bucket ACL grants access outside of your AWS account, first, you must migrate your bucket ACL permissions to your bucket policy.

  • Next, reset your bucket ACL to the default private ACL.

  • We also recommend that you review your object-level ACL permissions and migrate them to your bucket policy.

If your bucket ACLs grant read or write permissions to others outside of your account, before you can disable ACLs, you must migrate these permissions to your bucket policy. After you migrate these permissions, you can set Object Ownership to the Bucket owner enforced setting. If you don't migrate bucket ACLs that grant read or write access outside of your account, your request to apply the Bucket owner enforced setting fails and returns the InvalidBucketAclWithObjectOwnership error code.

If your bucket ACL grants access outside of your AWS account, before you disable ACLs, you must migrate your bucket ACL permissions to your bucket policy and reset your bucket ACL to the default private ACL. If you don't migrate and reset, your request to apply the Bucket owner enforced setting to disable ACLs fails and returns the InvalidBucketAclWithObjectOwnership error code. We also recommend that you review your object ACL permissions and migrate them to your bucket policy.

To review and migrate ACL permissions to bucket policies, see the following topics.

Bucket policies examples

These example bucket policies show you how to migrate READ and WRITE bucket and object ACL permissions for a third-party AWS account to a bucket policy. READ_ACP and WRITE_ACP ACLs are less relevant for policies because they grant ACL-related permissions (s3:GetBucketAcl, s3:GetObjectAcl, s3:PutBucketAcl, and s3:PutObjectAcl).

Example – READ ACL for a bucket

If your bucket had a READ ACL that grants AWS account 111122223333 permission to list the contents of your bucket, you can write a bucket policy that grants s3:ListBucket, s3:ListBucketVersions, s3:ListBucketMultipartUploads permissions for your bucket.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "Permission to list the objects in a bucket", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:root" ] }, "Action": [ "s3:ListBucket", "s3:ListBucketVersions", "s3:ListBucketMultipartUploads" ], "Resource": "arn:aws:s3:::amzn-s3-demo-bucket" } ] }
Example – READ ACLs for every object in a bucket

If every object in your bucket has a READ ACL that grants access to AWS account 111122223333, you can write a bucket policy that grants s3:GetObject and s3:GetObjectVersion permissions to this account for every object in your bucket.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "Read permission for every object in a bucket", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:root" ] }, "Action": [ "s3:GetObject", "s3:GetObjectVersion" ], "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*" } ] }

This example resource element grants access to a specific object.

"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/OBJECT-KEY"
Example – WRITE ACL that grants permissions to write objects to a bucket

If your bucket has a WRITE ACL that grants AWS account 111122223333 permission to write objects to your bucket, you can write a bucket policy that grants s3:PutObject permission for your bucket.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "Permission to write objects to a bucket", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:root" ] }, "Action": [ "s3:PutObject" ], "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*" } ] }

Using the S3 console to review and migrate ACL permissions

To review a bucket's ACL permissions
  1. Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/.

  2. In the Buckets list, choose the bucket name.

  3. Choose the Permissions tab.

  4. Under Access control list (ACL), review your bucket ACL permissions.

To review an object's ACL permissions
  1. Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/.

  2. In the Buckets list, choose the bucket name containing your object.

  3. In the Objects list, choose your object name.

  4. Choose the Permissions tab.

  5. Under Access control list (ACL), review your object ACL permissions.

To migrate ACL permissions and update your bucket ACL
  1. Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/.

  2. In the Buckets list, choose the bucket name.

  3. On the Permissions tab, under Bucket policy, choose Edit.

  4. In the Policy box, add or update your bucket policy.

    For example bucket policies, see Bucket policies examples and Example use cases.

  5. Choose Save changes.

  6. Update your bucket ACL to remove ACL grants to other groups or AWS accounts.

  7. Apply the Bucket owner enforced setting for Object Ownership.

Using the AWS CLI to review and migrate ACL permissions

  1. To return the bucket ACL for your bucket, use the get-bucket-acl AWS CLI command:

    aws s3api get-bucket-acl --bucket amzn-s3-demo-bucket

    For example, this bucket ACL grants WRITE and READ access to a third-party account. In this ACL, the third-party account is identified by the canonical user ID. To apply the Bucket owner enforced setting and disable ACLs, you must migrate these permissions for the third-party account to a bucket policy.

    { "Owner": { "DisplayName": "DOC-EXAMPLE-ACCOUNT-OWNER", "ID": "852b113e7a2f25102679df27bb0ae12b3f85be6BucketOwnerCanonicalUserID" }, "Grants": [ { "Grantee": { "DisplayName": "DOC-EXAMPLE-ACCOUNT-OWNER", "ID": "852b113e7a2f25102679df27bb0ae12b3f85be6BucketOwnerCanonicalUserID", "Type": "CanonicalUser" }, "Permission": "FULL_CONTROL" }, { "Grantee": { "DisplayName": "THIRD-PARTY-EXAMPLE-ACCOUNT", "ID": "72806de9d1ae8b171cca9e2494a8d1335dfced4ThirdPartyAccountCanonicalUserID", "Type": "CanonicalUser" }, "Permission": "READ" }, { "Grantee": { "DisplayName": "THIRD-PARTY-EXAMPLE-ACCOUNT", "ID": "72806de9d1ae8b171cca9e2494a8d1335dfced4ThirdPartyAccountCanonicalUserID", "Type": "CanonicalUser" }, "Permission": "WRITE" } ] }

    For other example ACLs, see Example use cases.

  2. Migrate your bucket ACL permissions to a bucket policy:

    This example bucket policy grants s3:PutObject and s3:ListBucket permissions for a third-party account. In the bucket policy, the third-party account is identified by the AWS account ID (111122223333).

    aws s3api put-bucket-policy --bucket amzn-s3-demo-bucket --policy file://policy.json policy.json: { "Version": "2012-10-17", "Statement": [ { "Sid": "PolicyForCrossAccountAllowUpload", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:root" ] }, "Action": [ "s3:PutObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket", "arn:aws:s3:::amzn-s3-demo-bucket/*" } ] }

    For more example bucket policies, see Bucket policies examples and Example use cases.

  3. To return the ACL for a specific object, use the get-object-acl AWS CLI command.

    aws s3api get-object-acl --bucket amzn-s3-demo-bucket --key EXAMPLE-OBJECT-KEY
  4. If required, migrate object ACL permissions to your bucket policy.

    This example resource element grants access to a specific object in a bucket policy.

    "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/EXAMPLE-OBJECT-KEY"
  5. Reset the ACL for your bucket to the default ACL.

    aws s3api put-bucket-acl --bucket amzn-s3-demo-bucket --acl private
  6. Apply the Bucket owner enforced setting for Object Ownership.

Identify requests that required an ACL for authorization

To identify Amazon S3 requests that required ACLs for authorization, you can use the aclRequired value in Amazon S3 server access logs or AWS CloudTrail. If the request required an ACL for authorization or if you have PUT requests that specify an ACL, the string is Yes. If no ACLs were required, or if you are setting a bucket-owner-full-control canned ACL, or if the requests are allowed by your bucket policy, the aclRequired value string is "-" in Amazon S3 server access logs and is absent in CloudTrail. For more information about the expected aclRequired values, see aclRequired values for common Amazon S3 requests.

If you have PutBucketAcl or PutObjectAcl requests with headers that grant ACL-based permissions, with the exception of the bucket-owner-full-control canned ACL, you must remove those headers before you can disable ACLs. Otherwise, your requests will fail.

For all other requests that required an ACL for authorization, migrate those ACL permissions to bucket policies. Then, remove any bucket ACLs before you enable the bucket owner enforced setting.

Note

Do not remove object ACLs. Otherwise, applications that rely on object ACLs for permissions will lose access.

If you see that no requests required an ACL for authorization, you can proceed to disable ACLs. For more information about identifying requests, see Using Amazon S3 server access logs to identify requests and Identifying Amazon S3 requests using CloudTrail.

Review and update bucket policies that use ACL-related condition keys

After you apply the Bucket owner enforced setting to disable ACLs, new objects can be uploaded to your bucket only if the request uses bucket owner full control ACLs or doesn't specify an ACL. Before disabling ACLs, review your bucket policy for ACL-related condition keys.

If your bucket policy uses an ACL-related condition key to require the bucket-owner-full-control canned ACL (for example, s3:x-amz-acl), you don't need to update your bucket policy. The following bucket policy uses the s3:x-amz-acl to require the bucket-owner-full-control canned ACL for S3 PutObject requests. This policy still requires the object writer to specify the bucket-owner-full-control canned ACL. However, buckets with ACLs disabled still accept this ACL, so requests continue to succeed with no client-side changes required.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "Only allow writes to my bucket with bucket owner full control", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:user/ExampleUser" ] }, "Action": [ "s3:PutObject" ], "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*", "Condition": { "StringEquals": { "s3:x-amz-acl": "bucket-owner-full-control" } } } ] }

However, if your bucket policy uses an ACL-related condition key that requires a different ACL, you must remove this condition key. This example bucket policy requires the public-read ACL for S3 PutObject requests and therefore must be updated before disabling ACLs.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "Only allow writes to my bucket with public read access", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:user/ExampleUser" ] }, "Action": [ "s3:PutObject" ], "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*", "Condition": { "StringEquals": { "s3:x-amz-acl": "public-read" } } } ] }

Example use cases

The following examples show you how to migrate ACL permissions to bucket policies for specific use cases.

Grant access to the S3 log delivery group for server access logging

If you want to apply the Bucket owner enforced setting to disable ACLs for a server access logging destination bucket (also known as a target bucket), you must migrate bucket ACL permissions for the S3 log delivery group to the logging service principal (logging.s3.amazonaws.com) in a bucket policy. For more information about log delivery permissions, see Permissions for log delivery.

This bucket ACL grants WRITE and READ_ACP access to the S3 log delivery group:

{ "Owner": { "DisplayName": "DOC-EXAMPLE-ACCOUNT-OWNER", "ID": "852b113e7a2f25102679df27bb0ae12b3f85be6BucketOwnerCanonicalUserID" }, "Grants": [ { "Grantee": { "Type": "CanonicalUser", "DisplayName": "DOC-EXAMPLE-ACCOUNT-OWNER", "ID": "852b113e7a2f25102679df27bb0ae12b3f85be6BucketOwnerCanonicalUserID" }, "Permission": "FULL_CONTROL" }, { "Grantee": { "Type": "Group", "URI": "http://acs.amazonaws.com/groups/s3/LogDelivery" }, "Permission": "WRITE" }, { "Grantee": { "Type": "Group", "URI": "http://acs.amazonaws.com/groups/s3/LogDelivery" }, "Permission": "READ_ACP" } ] }
To migrate bucket ACL permissions for the S3 log delivery group to the logging service principal in a bucket policy
  1. Add the following bucket policy to your destination bucket, replacing the example values.

    aws s3api put-bucket-policy --bucket amzn-s3-demo-bucket --policy file://policy.json policy.json: { { "Version": "2012-10-17", "Statement": [ { "Sid": "S3ServerAccessLogsPolicy", "Effect": "Allow", "Principal": { "Service": "logging.s3.amazonaws.com" }, "Action": [ "s3:PutObject" ], "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/EXAMPLE-LOGGING-PREFIX*", "Condition": { "ArnLike": { "aws:SourceArn": "arn:aws:s3:::SOURCE-BUCKET-NAME" }, "StringEquals": { "aws:SourceAccount": "SOURCE-AWS-ACCOUNT-ID" } } } ] }
  2. Reset the ACL for your destination bucket to the default ACL.

    aws s3api put-bucket-acl --bucket amzn-s3-demo-bucket --acl private
  3. Apply the Bucket owner enforced setting for Object Ownership to your destination bucket.

Grant public read access to the objects in a bucket

If your object ACLs grant public read access to all of the objects in your bucket, you can migrate these ACL permissions to a bucket policy.

This object ACL grants public read access to an object in a bucket:

{ "Owner": { "DisplayName": "DOC-EXAMPLE-ACCOUNT-OWNER", "ID": "852b113e7a2f25102679df27bb0ae12b3f85be6BucketOwnerCanonicalUserID" }, "Grants": [ { "Grantee": { "DisplayName": "DOC-EXAMPLE-ACCOUNT-OWNER", "ID": "852b113e7a2f25102679df27bb0ae12b3f85be6BucketOwnerCanonicalUserID", "Type": "CanonicalUser" }, "Permission": "FULL_CONTROL" }, { "Grantee": { "Type": "Group", "URI": "http://acs.amazonaws.com/groups/global/AllUsers" }, "Permission": "READ" } ] }
To migrate public read ACL permissions to a bucket policy
  1. To grant public read access to all of the objects in your bucket, add the following bucket policy, replacing the example values.

    aws s3api put-bucket-policy --bucket amzn-s3-demo-bucket --policy file://policy.json policy.json: { "Version": "2012-10-17", "Statement": [ { "Sid": "PublicReadGetObject", "Effect": "Allow", "Principal": "*", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/*" ] } ] }

    To grant public access to a specific object in a bucket policy, use the following format for the Resource element.

    "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/OBJECT-KEY"

    To grant public access to all of the objects with a specific prefix, use the following format for the Resource element.

    "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/PREFIX/*"
  2. Apply the Bucket owner enforced setting for Object Ownership.

Grant Amazon ElastiCache (Redis OSS) access to your S3 bucket

You can export your ElastiCache (Redis OSS) backup to an S3 bucket, which gives you access to the backup from outside ElastiCache. To export your backup to an S3 bucket, you must grant ElastiCache permissions to copy a snapshot to the bucket. If you've granted permissions to ElastiCache in a bucket ACL, you must migrate these permissions to a bucket policy before you apply the Bucket owner enforced setting to disable ACLs. For more information, see Grant ElastiCache access to your Amazon S3 bucket in the Amazon ElastiCache User Guide.

The following example shows the bucket ACL permissions that grant permissions to ElastiCache.

{ "Owner": { "DisplayName": "DOC-EXAMPLE-ACCOUNT-OWNER", "ID": "852b113e7a2f25102679df27bb0ae12b3f85be6BucketOwnerCanonicalUserID" }, "Grants": [ { "Grantee": { "DisplayName": "DOC-EXAMPLE-ACCOUNT-OWNER", "ID": "852b113e7a2f25102679df27bb0ae12b3f85be6BucketOwnerCanonicalUserID", "Type": "CanonicalUser" }, "Permission": "FULL_CONTROL" }, { "Grantee": { "DisplayName": "aws-scs-s3-readonly", "ID": "540804c33a284a299d2547575ce1010f2312ef3da9b3a053c8bc45bf233e4353", "Type": "CanonicalUser" }, "Permission": "READ" }, { "Grantee": { "DisplayName": "aws-scs-s3-readonly", "ID": "540804c33a284a299d2547575ce1010f2312ef3da9b3a053c8bc45bf233e4353", "Type": "CanonicalUser" }, "Permission": "WRITE" }, { "Grantee": { "DisplayName": "aws-scs-s3-readonly", "ID": "540804c33a284a299d2547575ce1010f2312ef3da9b3a053c8bc45bf233e4353", "Type": "CanonicalUser" }, "Permission": "READ_ACP" } ] }
To migrate bucket ACL permissions for ElastiCache (Redis OSS) to a bucket policy
  1. Add the following bucket policy to your bucket, replacing the example values.

    aws s3api put-bucket-policy --bucket amzn-s3-demo-bucket --policy file://policy.json policy.json: { "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt15399483", "Effect": "Allow", "Principal": { "Service": "Region.elasticache-snapshot.amazonaws.com" }, "Action": [ "s3:PutObject", "s3:GetObject", "s3:ListBucket", "s3:GetBucketAcl", "s3:ListMultipartUploadParts", "s3:ListBucketMultipartUploads" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket", "arn:aws:s3:::amzn-s3-demo-bucket/*" ] } ] }
  2. Reset the ACL for your bucket to the default ACL:

    aws s3api put-bucket-acl --bucket amzn-s3-demo-bucket --acl private
  3. Apply the Bucket owner enforced setting for Object Ownership.