Amazon CloudFront
Developer Guide (API Version 2016-09-29)

Restricting Access to Amazon S3 Content by Using an Origin Access Identity

If you're using an Amazon S3 bucket as the origin for a CloudFront distribution, you can either allow everyone to have access to the files there, or you can restrict access. If you limit access by using, for example, CloudFront signed URLs or signed cookies, you also won't want people to be able to view files by simply using the direct URL for the file. Instead, you want them to only access the files by using the CloudFront URL, so your protections work.

Important

If you use an Amazon S3 bucket configured as a website endpoint, you must set it up with CloudFront as a custom origin and you can't use the origin access identity feature described in this topic. You can restrict access to content on a custom origin by using custom headers. For more information, see Using Custom Headers to Restrict Access to Your Content on a Custom Origin.

When you first set up an Amazon S3 bucket as the origin for a CloudFront distribution, you grant everyone permission to read the files in your bucket. This allows anyone to access your files either through CloudFront or using the Amazon S3 URL. CloudFront doesn't expose Amazon S3 URLs, but your users might have those URLs if your application serves any files directly from Amazon S3 or if anyone gives out direct links to specific files in Amazon S3.

If you use CloudFront signed URLs or signed cookies to limit access to files in your Amazon S3 bucket, you probably also want to prevent users from accessing your Amazon S3 files by using Amazon S3 URLs. If users access your files directly in Amazon S3, they bypass the controls provided by CloudFront signed URLs or signed cookies, for example, control over the date and time that a user can no longer access your content and control over which IP addresses can be used to access content. In addition, if users access files both through CloudFront and directly by using Amazon S3 URLs, CloudFront access logs are less useful because they're incomplete.

To ensure that your users access your files using only CloudFront URLs, regardless of whether the URLs are signed, do the following:

  1. Create an origin access identity, which is a special CloudFront user, and associate the origin access identity with your distribution. You associate the origin access identity with origins, so that you can secure all or just some of your Amazon S3 content. You can also create an origin access identity and add it to your distribution when you create the distribution. For more information, see Creating a CloudFront Origin Access Identity and Adding it to Your Distribution.

  2. Change the permissions either on your Amazon S3 bucket or on the files in your bucket so that only the origin access identity has read permission (or read and download permission). When your users access your Amazon S3 files through CloudFront, the CloudFront origin access identity gets the files on behalf of your users. If your users request files directly by using Amazon S3 URLs, they're denied access. The origin access identity has permission to access files in your Amazon S3 bucket, but users don't. For more information, see Granting the Origin Access Identity Permission to Read Files in Your Amazon S3 Bucket.

Note

To create origin access identities, you must use the CloudFront console or CloudFront API version 2009-09-09 or later.

For detailed information about setting up a private Amazon S3 bucket to use with CloudFront, see How to Set Up and Serve Private Content Using S3 and Amazon CloudFront.

Creating a CloudFront Origin Access Identity and Adding it to Your Distribution

An AWS account can have up to 100 CloudFront origin access identities. However, you can add an origin access identity to as many distributions as you want, so one origin access identity is usually sufficient.

If you didn't create an origin access identity and add it to your distribution when you created the distribution, you can create and add one now by using either the CloudFront console or the CloudFront API:

Creating an Origin Access Identity and Adding it to Your Distribution

If you didn't create an origin access identity when you created your distribution, do the following.

To create a CloudFront origin access identity using the CloudFront console

  1. Sign in to the AWS Management Console and open the CloudFront console at https://console.aws.amazon.com/cloudfront/.

  2. Click the ID of a distribution that has an S3 origin, and then choose Distribution Settings.

  3. Choose the Origins tab.

  4. Choose an origin, and then choose Edit.

  5. For Restrict Bucket Access, choose Yes.

    Note

    If you don't see the Restrict Bucket Access option, your Amazon S3 origin might be configured as a website endpoint. In that configuration, S3 buckets must be set up with CloudFront as custom origins and you can't use an origin access identity with them.

  6. If you already have an origin access identity that you want to use, click Use an Existing Identity. Then select the identity in the Your Identities list.

    Note

    If you already have an origin access identity, we recommend that you reuse it to simplify maintenance.

    If you want to create an identity, click Create a New Identity. If you like, you can replace the bucket name in the Comment field with a custom description.

  7. If you want CloudFront to automatically give the origin access identity permission to read the files in the Amazon S3 bucket specified in Origin Domain Name, click Yes, Update Bucket Policy.

    Important

    If you choose Yes, Update Bucket Policy, CloudFront updates bucket permissions to grant the specified origin access identity the permission to read files in your bucket. However, CloudFront does not remove existing permissions. If users currently have permission to access the files in your bucket using Amazon S3 URLs, they will still have that permission after CloudFront updates your bucket permissions. To view or remove existing bucket permissions, use a method provided by Amazon S3. For more information, see Granting the Origin Access Identity Permission to Read Files in Your Amazon S3 Bucket.

    If you want to manually update permissions on your Amazon S3 bucket, choose No, I Will Update Permissions.

  8. Choose Yes, Edit.

  9. If you have more than one origin, repeat the steps to add an origin access identity for each one.

Creating an Origin Access Identity Using the CloudFront API

If you already have an origin access identity and you want to reuse it instead of creating another one, skip to Adding an Origin Access Identity to Your Distribution Using the CloudFront API.

To create a CloudFront origin access identity by using the CloudFront API, use the POST Origin Access Identity API action. The response includes an Id and an S3CanonicalUserId for the new origin access identity. Make note of these values because you will use them later in the process:

  • Id element – You use the value of the Id element to associate an origin access ID with your distribution.

  • S3CanonicalUserId element – You use the value of the S3CanonicalUserId element when you give CloudFront access to your Amazon S3 bucket or files.

For more information, see CreateCloudFrontOriginAccessIdentity in the Amazon CloudFront API Reference.

Adding an Origin Access Identity to Your Distribution Using the CloudFront API

You can use the CloudFront API to add a CloudFront origin access identity to an existing distribution or to create a new distribution that includes an origin access identity. In either case, include an OriginAccessIdentity element. This element contains the value of the Id element that the POST Origin Access Identity API action returned when you created the origin access identity. You can add the OriginAccessIdentity element to one or more origins.

See the following topics in the Amazon CloudFront API Reference:

Granting the Origin Access Identity Permission to Read Files in Your Amazon S3 Bucket

When you create or update a distribution, you can add an origin access identity and automatically update the bucket policy to give the origin access identity permission to access your bucket. Alternatively, you can choose to manually change the bucket policy or change ACLs, which control permissions on individual files in your bucket.

Whichever method you use, you should still review the bucket policy for your bucket and review the permissions on your files to ensure that:

  • CloudFront can access files in the bucket on behalf of users who are requesting your files through CloudFront.

  • Users can't use Amazon S3 URLs to access your files.

Important

If you configure CloudFront to accept and forward to Amazon S3 all of the HTTP methods that CloudFront supports, create a CloudFront origin access identity to restrict access to your Amazon S3 content, and grant the origin access identity the desired permissions. For example, if you configure CloudFront to accept and forward these methods because you want to use the PUT method, you must configure Amazon S3 bucket policies or ACLs to handle DELETE requests appropriately so users can't delete resources that you don't want them to.

Note the following:

  • You might find it easier to update Amazon S3 bucket policies than ACLs because you can add files to the bucket without updating permissions. However, ACLs give you more fine-grained control because you're granting permissions on each file.

  • By default, your Amazon S3 bucket and all of the files in it are private—only the AWS account that created the bucket has permission to read or write the files in it.

  • If you're adding an origin access identity to an existing distribution, modify the bucket policy or any file ACLs as appropriate to ensure that the files are not publicly available.

  • Grant additional permissions to one or more secure administrator accounts so you can continue to update the contents of the Amazon S3 bucket.

Important

There might be a brief delay between when you save your changes to Amazon S3 permissions and when the changes take effect. Until the changes take effect, you can get permission-denied errors when you try to access files in your bucket.

Updating Amazon S3 Bucket Policies

You can update the Amazon S3 bucket policy by using either the AWS Management Console or the Amazon S3 API:

  • Grant the CloudFront origin access identity the desired permissions on the bucket.

    To specify an origin access identity, use the value of Amazon S3 Canonical User ID on the Origin Access Identity page in the CloudFront console. If you're using the CloudFront API, use the value of the S3CanonicalUserId element that was returned when you created the origin access identity.

  • Deny access to anyone that you don't want to have access using Amazon S3 URLs.

For more information, go to Using Bucket Policies and User Policies in the Amazon Simple Storage Service Developer Guide.

For an example, see "Granting Permission to an Amazon CloudFront Origin Identity" in the topic Bucket Policy Examples, also in the Amazon Simple Storage Service Developer Guide.

Updating Amazon S3 ACLs

Using either the AWS Management Console or the Amazon S3 API, change the Amazon S3 ACL:

  • Grant the CloudFront origin access identity the desired permissions on each file that the CloudFront distribution serves.

    To specify an origin access identity, use the value of Amazon S3 Canonical User ID on the Origin Access Identity page in the CloudFront console. If you're using the CloudFront API, use the value of the S3CanonicalUserId element that was returned when you created the origin access identity.

  • Deny access to anyone that you don't want to have access using Amazon S3 URLs.

If another AWS account uploads files to your bucket, that account is the owner of those files. Bucket policies only apply to files that the bucket owner owns. This means that if another account uploads files to your bucket, the bucket policy that you created for your OAI will not be evaluated for those files.

For more information, see Managing Access with ACLs in the Amazon Simple Storage Service Developer Guide.

You can also change the ACLs programmatically by using one of the AWS SDKs. For an example, see the downloadable sample code in Create a URL Signature Using C# and the .NET Framework.

Using an Origin Access Identity in Amazon S3 Regions that Support Only Signature Version 4 Authentication

Newer Amazon S3 regions require that you use signature version 4 for authenticated requests. (For the versions of signature supported in each Amazon S3 region, see Amazon Simple Storage Service (S3) in the topic Regions and Endpoints in the Amazon Web Services General Reference.) However, when you create an origin access identity and add it to a CloudFront distribution, CloudFront typically uses signature version 4 for authentication when it requests files in your Amazon S3 bucket. If you're using an origin access identity and if your bucket is in one of the regions that requires signature version 4 for authentication, note the following:

  • DELETE, GET, HEAD, OPTIONS, and PATCH requests are supported without qualifications.

  • If you want to submit PUT requests to CloudFront to upload files to your Amazon S3 bucket, you must add an x-amz-content-sha256 header to the request, and the header value must contain a SHA256 hash of the body of the request. For more information, see the documentation about the x-amz-content-sha256 header on the Common Request Headers page in the Amazon Simple Storage Service API Reference.

  • POST requests are not supported.