How do I grant cross-account access to objects that are in Amazon S3 buckets?

10 minute read

I want to grant another AWS Account access to an object that's in an Amazon Simple Storage Service (Amazon S3) bucket.

Short description

As an account administrator you can grant users in another account cross-account access to objects that you own in your account. You can also grant permissions for specific S3 resources that don't require full administrative access. You can grant permissions for specific S3 resources without full administrative access.

Use one of the following methods to grant cross-account access to objects:

AWS Identity and Access Management (IAM) policies and resource-based bucket policies for programmatic-only access to S3 bucket objects. This method allows you to access Amazon S3 through code, AWS Command Line Interface (AWS CLI) commands, or APIs with your own IAM identity.
IAM policies and resource-based access control lists (ACLs) for programmatic-only access to S3 bucket objects. This method allows you to access Amazon S3 through code, CLI commands, or APIs with your own IAM identity.
Note: When you turn on the Bucket owner enforced setting, Amazon S3 deactivates all bucket and object ACLs. So, you can't use ACLs to grant cross-account access. By default, Bucket owner enforced is turned on for all newly created buckets. To manage cross-account access, it's also a best practice to use IAM policies and bucket policies instead of ACLs. For more information, see Controlling ownership of objects and deactivating ACLs for your bucket.
Cross-account IAM roles for programmatic and console access to S3 bucket objects. This method allows you to access Amazon S3 through code, CLI commands, APIs, and the console when you assume a role in the bucket owner's account.

If the requester is an IAM role principal, then the account that owns the principal must use an IAM policy to grant the S3 bucket permissions. The owner of the bucket must also use a bucket policy or ACL to grant permissions. After you grant access, programmatic access to cross-account buckets is the same as access to the account buckets.

Cross-account access with Amazon S3 access points or AWS Key Management Service (AWS KMS) requires additional configuration. For more information, see Why do cross-account users receive Access Denied errors when they try to access my S3 objects that I encrypted with an AWS KMS customer managed key?

It's a best practice to use S3 access points for large data sets that you must access as cross-account objects. For more information, see Simplify and scale access management to shared datasets with cross-account Amazon S3 access points.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

In the following procedures, Account A is your account and Account B is the account that you want to grant object access to.

IAM policies and resource-based bucket policies

To manage cross-account access and audit the S3 object's permissions, use resource-based bucket policies. The principal account (Account B) must grant IAM permissions to its users or roles to perform S3 actions. The bucket owner account (Account A) must use a bucket policy to allow the cross-account principal to access the bucket and its objects. Bucket policies define the principal, resource, and action elements at the bucket level. This allows you to control access to specific objects within the bucket and review who has access to your S3 resources.

Apply a bucket policy at the bucket level that defines the principal, resource, and action elements. When you apply a bucket policy at the bucket level, you can define access to different objects inside the bucket. You can also review the bucket policy to see who can access objects in an S3 bucket.

To use bucket policies to manage S3 bucket access, complete the following steps:

Create an S3 bucket in Account A for access by users from Account B.
Create an IAM user or role in Account B for access by users from Account A.

Give the IAM user or role in Account B GetObject and PutObject permissions. Also, grant the IAM user or role permission to call PutObjectAcl that grants object permission to the bucket owner. If you need to access specific versions of versioned objects in a versioning-enabled bucket, include the s3:GetObjectVersion permission:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:GetObjectVersion",
                "s3:PutObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::AccountABucketName/*"
        }
    ]
}

Note: In the preceding policy, replace the example values your user values.
You can also limit access to a specific bucket folder that's in Account A. To limit access, define the folder name in the Resource element, such as "arn:aws:s3:::AccountABucketName/FolderName/*". For more information, see How can I grant a user access to a specific folder in my Amazon S3 bucket? You can also run the create-policy AWS CLI command to create an IAM identity-based policy.

Configure the bucket policy for Account A to grant GetObject and PutObject permissions to the IAM user or role that you created in Account B:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::AccountB:user/AccountBUserName"
            },
            "Action": [
                "s3:GetObject",
                "s3:GetObjectVersion",
                "s3:PutObject",
                "s3:PutObjectAcl"
            ],
            "Resource": [
                "arn:aws:s3:::AccountABucketName/*"
            ]
        }
    ]
}

You can also run the put-bucket-policy AWS CLI command to create an S3 bucket policy.

To limit access to a specific bucket folder, define the folder name in the Resource element, such as "arn:aws:s3:::AccountABucketName/FolderName/*". When you use the s3:PutObject permission with a condition key, the bucket owner has full control over the objects that other accounts upload. The PutObject API call enforces the ACL with specific headers.

IAM policies and resource-based ACLs

You can also use object ACLs to manage permissions for specific scenarios.

Important: It's a best practice to use IAM policies and bucket policies instead of ACLs for cross-account access. By default, newly created S3 buckets have the Bucket owner enforced setting turned on, which turns off all ACLs. The following ACL method only works if you explicitly turn off the Bucket owner enforced setting.

Amazon S3 ACLs allow users to define only READ, WRITE, READ_ACP, WRITE_ACP, and FULL_CONTROL permission sets. You can use only an account or one of the predefined Amazon S3 groups as a grantee for the Amazon S3 ACL. When you specify an email address or canonical user ID for an account, the ACL applies to all identities in the grantee account. For example, you can't use an ACL to restrict access to individual IAM users or roles. You also can't apply ACLs to different objects that share the same prefixes.

Note: ACLs don't support conditions for the S3 operations they authorize. Also, when Account B uploads objects to Account A's bucket, Account B owns those objects by default. This means the bucket owner might not control the objects that the ACL grantee uploaded, unless the uploader explicitly grants permissions to the bucket owner.

To use bucket and object ACLs to manage S3 bucket access, complete the following steps:

Turn off the Bucket owner enforced setting for the bucket in Account A. This setting is on by default for newly created buckets and prevents the use of ACLs.
Create an IAM user or role in Account B.
Grant the user or role permissions to perform the required Amazon S3 operations. Users who call PutObject and GetObject must have the permissions that are listed in the Resource-based policies and IAM policies section.

Configure the bucket ACL to include at least WRITE permission for Account B. WRITE permission allows Account B IAM users or roles to upload objects to a bucket that Account A owns:

...<AccessControlPolicy>
  <Owner>
    <ID> AccountACanonicalUserID </ID>
    <DisplayName> AccountADisplayName </DisplayName>
  </Owner>
  <AccessControlList>
...
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID> AccountBCanonicalUserID </ID>
        <DisplayName> AccountBDisplayName </DisplayName>
      </Grantee>
      <Permission> WRITE </Permission>
    </Grant>
    ...
  </AccessControlList>
</AccessControlPolicy>

Note: To find your CanonicalUserID, see Finding an AWS account canonical user ID. When you specify an email address as a grantee, Amazon S3 converts it to the canonical user ID for that account. It stores only the canonical user ID in the ACL, not the email address.

Configure object ACLs to include at least READ permission for Account B. READ permission allows IAM roles or users in Account B to download objects from a bucket that Account A owns:

...<AccessControlPolicy>
  <Owner>
    <ID> AccountACanonicalUserID </ID>
    <DisplayName> AccountADisplayName </DisplayName>
  </Owner>
  <AccessControlList>
...
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID> AccountBCanonicalUserID </ID>
        <DisplayName> AccountBDisplayName </DisplayName>
      </Grantee>
      <Permission> READ </Permission>
    </Grant>
    ...
  </AccessControlList>
</AccessControlPolicy>

ACL permissions vary based on the S3 resource, bucket, or object that you apply an ACL to. For more information, see Access control list (ACL) overview. When you create your bucket or upload an object to an existing bucket, configure bucket and object ACLs.

Cross-account IAM roles

Not all AWS services support resource-based policies. Instead, use cross-account IAM roles to centralize permission management when you provide cross-account access to multiple services. This method allows cross-account access to objects that another account or AWS service owns or uploaded. If you don't use cross-account IAM roles, then you must modify the object ACL. For more information, see How Amazon S3 authorizes a request for an object operation.

To use cross-account IAM roles to manage S3 bucket access, complete the following steps:

Create an IAM role in Account A that can be assumed by users or roles from Account B.

Grant the role permissions to perform the required S3 operations. In the role's trust policy, grant a user or role from Account B permissions to assume the role in Account A:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::AccountB:user/AccountBUserName"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Note: IAM roles must have a trust policy that defines the principals who can assume the role and when the roles can assume them. IAM roles can have multiple permissions policies that define the permissions that a principal can perform and the resources that they use.

You can also run the create-role AWS CLI command to create a role with the trust policy.

The following access policy allows a user who assumed the role to use the Amazon S3 console to programmatically download and upload objects. If you require only programmatic access, then you can remove the first two statements in the policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "s3:ListAllMyBuckets"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::*"
            ]
        },
        {
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:s3:::AccountABucketName"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject"
            ],
            "Resource": "arn:aws:s3:::AccountABucketName/*"
        }
    ]
}

For more information, see How can I grant a user access to a specific folder in my Amazon S3 bucket? You can also run the create-policy AWS CLI command to create an IAM identity-based policy.

Grant an IAM role or user in Account B permission to assume the IAM role that you created in Account A. You must add the following policy as a permissions policy to the IAM user or role:

{
    "Version": "2012-10-17",
    "Statement": {
        "Effect": "Allow",
        "Action": "sts:AssumeRole",
        "Resource": "arn:aws:iam::AccountA:role/AccountARole"
    }
}

You can also run the create-policy AWS CLI command to create an IAM identity-based policy.

From a role in Account B, assume the role in Account A so that IAM identities in Account B can perform the required S3 operations.
Note: When you assume an IAM role in Account A, Amazon S3 determines the operation based on the access policy. The IAM role works as an API call that a local IAM identity in Account A invoked. A bucket policy or an ACL for cross-account access isn't required. For more information, see Policy actions for Amazon S3.