Amazon CloudFront
Developer Guide (API Version 2014-10-21)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

Using an HTTPS Connection to Access Your Objects

For web distributions, you can use HTTPS requests to ensure that your objects are encrypted when CloudFront serves them to viewers and, optionally, when CloudFront gets the objects from your origin:

  • To require HTTPS between CloudFront and viewers: Configure some or all of your CloudFront cache behaviors either to redirect HTTP requests to HTTPS requests or to require that viewers use only the HTTPS protocol to access your objects in the CloudFront cache. You can also configure one or more cache behaviors in the same distribution to allow both HTTP and HTTPS, so you can require HTTPS for some objects but not for others.

  • To require HTTPS between CloudFront and your origin (optional): Configure one or more CloudFront origins to require that CloudFront fetches objects from your origin using the protocol that the viewer used to request the objects. For example, when you use this CloudFront setting and the viewer uses HTTPS to request an object from CloudFront, CloudFront also uses HTTPS to forward the request to your origin. When your origin is an Amazon S3 bucket, this is the default setting and cannot be changed.

    Important

    If your Amazon S3 bucket is configured as a website endpoint, you cannot configure CloudFront to use HTTPS to communicate with your origin because Amazon S3 doesn't support HTTPS connections in that configuration.

If you're using an HTTP server as your origin, and if you want to use HTTPS both between viewers and CloudFront and between CloudFront and your origin, you must install an SSL certificate on the HTTP server that is signed by a third-party certificate authority, for example, VeriSign or DigiCert.

Caution

If the origin server returns an invalid certificate or a self-signed certificate, or if the origin server returns the certificate chain in the wrong order, CloudFront drops the TCP connection, returns HTTP error code 502, and sets the X-Cache header to Error from cloudfront.

How CloudFront Works with HTTPS Connections

The following example of how CloudFront works with HTTPS connections assumes the following:

  • Your CloudFront distribution has one cache behavior (the default cache behavior) and one origin.

  • You have configured your distribution to use HTTPS between viewers and CloudFront and between CloudFront and your origin.

  • Your origin has an SSL certificate that was signed by a third-party certificate authority.

The process works basically the same way whether your origin server is an Amazon S3 bucket or an HTTP server.

CloudFront Process for Serving Objects Using HTTPS

  1. A viewer submits an HTTPS request to CloudFront. There's some SSL negotiation here between the viewer and CloudFront. In the end, the viewer submits the request in an encrypted format.

  2. If the object is in the CloudFront edge cache, CloudFront encrypts the object and returns it to the viewer, and the viewer decrypts it.

  3. If the object is not in the CloudFront cache, CloudFront performs the SSL negotiation with your origin and, when the negotiation is complete, forwards the request to your origin in an encrypted format.

  4. Your origin decrypts the request, encrypts the requested object, and returns the object to CloudFront.

  5. CloudFront decrypts the object, re-encrypts it, and forwards the object to the viewer. CloudFront also saves the object in the edge cache so the object is available next time it's requested.

  6. The viewer decrypts the object.

How to Require HTTPS for Communication between Viewers, CloudFront, and Your Origin

You can configure CloudFront to require HTTPS for communication between viewers and CloudFront and, optionally, between CloudFront and your origin.

Note

To ensure that objects are encrypted from the origin to CloudFront edge caches and from edge caches to viewers, use only HTTPS. If you ever configure CloudFront to get objects from your origin using HTTP, CloudFront adds the objects to the edge cache and continues to serve them to viewers until the objects expire, or until you remove or replace them. For more information about removing or replacing objects in a distribution, see Adding, Removing, or Replacing Objects in a Distribution.

If you want to use alternate domain names (for example, example.com) instead of the domain name that CloudFront assigns to your distribution, also see Using Alternate Domain Names and HTTPS.

To Require HTTPS for Communication between Viewers, CloudFront, and Your Origin

  1. (Optional) If you want CloudFront to use HTTPS when communicating with a custom origin, get and install an SSL certificate from a third-party certificate authority such as VeriSign or DigiCert (if you don't already have one).

    Important

    If you configure CloudFront to use HTTPS when communicating with your origin in step 3, CloudFront verifies that your certificate was issued by an established third-party certificate authority. CloudFront supports the same certificate authorities as Mozilla; for the current list, see Mozilla Included CA Certificate List. You cannot use a self-signed certificate.

    If you're using an Amazon S3 bucket, Amazon S3 provides an SSL certificate.

    For more information about getting and installing an SSL certificate, refer to the documentation for your HTTP server software and to the documentation for the third-party certificate authority.

  2. Configure your distribution either to redirect HTTP requests to HTTPS or to require that viewers use HTTPS when communicating with CloudFront. To do this in the CloudFront console, create or update one or more cache behaviors in your distribution to have one of the following settings for Viewer Protocol Policy:

    • Redirect to HTTPS: If a user sends an HTTP request instead of an HTTPS request, CloudFront returns an HTTP status code of 301 (Moved Permanently) along with the new HTTPS URL. The viewer then resubmits the request to CloudFront using the HTTPS URL.

      Note

      When a viewer makes an HTTP request that is redirected to an HTTPS request, CloudFront charges for both requests. For the HTTP request, the charge is only for the request and for the headers that CloudFront returns to the viewer. For the HTTPS request, the charge is for the request, and for the headers and the object returned by your origin.

    • HTTPS Only: If a user sends an HTTP request instead of an HTTPS request, CloudFront returns an HTTP status code of 403 (Forbidden) and does not return the object.

    For information about using the CloudFront console to update a web distribution, see Listing, Viewing, and Updating CloudFront Distributions.

    For information about using the CloudFront API to update a web distribution, go to PUT Distribution Config in the Amazon CloudFront API Reference. If you're using the API, see the ViewerProtocolPolicy element.

  3. (Optional) To require that CloudFront uses HTTPS when communicating with your origin, create or update one or more origins in your distribution to have the following settings:

    • CloudFront Console: For Origin Protocol Policy, specify Match Viewer.

    • CloudFront API: For OriginProtocolPolicy, specify match-viewer.

    When your origin is an Amazon S3 bucket, Match Viewer is the default setting and cannot be changed.

    Important

    When you're using a custom origin, the SSL certificate on your origin includes a domain name in the Common Name field and possibly several more in the Subject Alternative Names field. (CloudFront supports wildcard characters in certificate domain names.) One of the domain names in the certificate must match the domain name that you specify for Origin Domain Name. If the domain names don't match, the following sequence occurs when an end user submits an HTTPS request for an object:

    1. CloudFront forwards the request to the applicable origin based on the settings in your cache behaviors.

    2. The origin returns an SSL certificate.

    3. CloudFront inspects the certificate and determines that the domain names in the certificate don't match the value of Origin Domain Name in your distribution.

    4. CloudFront returns an HTTP status code 502 (bad gateway) to the end user.

  4. Confirm the following:

    • The path pattern in each cache behavior applies only to the requests for which you want viewers to use HTTPS.

    • The cache behaviors are listed in the desired order. For more information, see Path Pattern.

    • The cache behaviors are routing requests to the origins for which you have configured an Origin Protocol Policy of Match Viewer, if applicable.

    • If you're using a custom origin and you configured CloudFront to use HTTPS when communicating with the origin, the origin must have a valid certificate signed by a third-party certificate authority.

  5. Test the configuration before you use it in a production environment.

Using Alternate Domain Names and HTTPS

By default, you can deliver your content to viewers over HTTPS by using your CloudFront distribution domain name in your URLs, for example, https://d111111abcdef8.cloudfront.net/image.jpg. For more information, see How to Require HTTPS for Communication between Viewers, CloudFront, and Your Origin.

If you want your viewers to use HTTPS and you want to use your own domain name in the URLs for your objects (for example, https://www.example.com/image.jpg), you need to perform several additional steps, as explained in this topic.

Important

When you add a certificate to your distribution, CloudFront immediately propagates the certificate to all of its edge locations. As new edge locations become available, CloudFront will propagate the certificate to those locations, too. You cannot restrict the edge locations to which CloudFront propagates your certificates.

Choosing How CloudFront Serves HTTPS Requests

If you want your users to use HTTPS and to use alternate domain names for your objects, you need to choose how CloudFront serves HTTPS requests. When you configure CloudFront to use alternate domain names, CloudFront can serve HTTPS requests either by using a dedicated IP address in each edge location or by using Server Name Indication (SNI).

Serving HTTPS Requests Using Dedicated IP Addresses (Works for All Clients)

If you configure CloudFront to serve HTTPS requests using dedicated IP addresses, CloudFront associates your alternate domain name with a dedicated IP address in each CloudFront edge location. When a viewer submits an HTTPS request for your content, DNS routes the request to the IP address for your distribution in the applicable edge location. CloudFront uses the IP address to identify your distribution and to determine which SSL certificate to return to the viewer. The viewer and CloudFront perform SSL negotiation using your SSL certificate, and CloudFront returns the requested content to the viewer. This method works for every HTTPS request, regardless of the browser or other viewer that the user is using.

Important

If you configure CloudFront to serve HTTPS requests using dedicated IP addresses, you incur an additional monthly charge. The charge begins when you associate your SSL certificate with a distribution and you enable the distribution. For more information about CloudFront pricing, see Amazon CloudFront Pricing.

Serving HTTPS Requests Using SNI (Works for Most Clients)

If you configure CloudFront to serve HTTPS requests using Server Name Indication (SNI), CloudFront associates your alternate domain name with an IP address for each edge location, but the IP address is not dedicated to your distribution. When a viewer submits an HTTPS request for your content, DNS routes the request to the IP address for the applicable edge location. However, because the IP address isn't dedicated to your distribution, CloudFront can't determine, based on the IP address, which domain the request is for.

SSL negotiation occurs very early in the process of establishing an HTTPS connection. If CloudFront can't immediately determine which domain the request is for, it drops the connection. Using a dedicated IP address is one way to associate a request with a domain. The other is Server Name Indication (SNI), which is an extension to the TLS protocol that is supported by most modern browsers. Browsers that support SNI automatically get the domain name from the request URL and add it to a new field in the request header. When CloudFront receives an HTTPS request from a browser that supports SNI, it finds the domain name in the request header and responds to the request with the applicable SSL certificate. The viewer and CloudFront perform SSL negotiation, and CloudFront returns the requested content to the viewer.

For a current list of the browsers that support SNI, see the Wikipedia entry Server Name Indication.

If you want to use SNI but some of your users' browsers don't support SNI, you have several options:

  • Configure CloudFront to serve HTTPS requests by using dedicated IP addresses instead of SNI.

  • Use the CloudFront SSL certificate instead of a custom certificate. This requires that you use the CloudFront domain name for your distribution in the URLs for your objects, for example, https://d111111abcdef8.cloudfront.net/logo.png.

    You also need to change the SSL certificate that CloudFront is using from a custom certificate to the default CloudFront certificate:

  • If you can control which browser your users use, have them upgrade their browser to one that supports SNI.

  • Use HTTP instead of HTTPS.

Requirements and Limits on Using SSL Certificates with CloudFront

Note the following requirements for your certificate:

  • Your certificate must be issued by a recognized certificate authority (CA). Self-signed certificates are not accepted.

  • Your certificate must be in X.509 PEM format.

  • In the .pem file, list all of the intermediate certificates in the certificate chain, beginning with one for the CA that signed the certificate for your domain. Typically, you'll find a file on your CA's website that lists intermediate and root certificates in the proper chained order.

    Important

    Do not include the root certificate, intermediate certificates that are not in the trust path, or your CA's public key certificate.

    Here's an example:

    -----BEGIN CERTIFICATE-----
    Intermediate certificate 2
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    Intermediate certificate 1
    -----END CERTIFICATE-----
  • The private key must match the public key that is in the certificate. It must also be an RSA private key in PEM format, where the PEM header is BEGIN RSA PRIVATE KEY and the footer is END RSA PRIVATE KEY. The private key cannot be encrypted with a password.

  • You must have permission to use and upload the SSL certificate, including permission from the certificate authority that issued the certificate to upload it onto a content delivery network.

  • The maximum size of the public key in an SSL certificate is 2048 bits. For information about how to determine the size of the public key, see Determining the Size of the Public Key in an SSL Certificate.

  • CloudFront supports all types of certificates including domain-validated certificates, extended validation (EV) certificates, high-assurance certificates, wildcard certificates (*.example.com), subject alternative name (SAN) certificates (example.com and example.net), and so on.

  • You are responsible for monitoring certificate expiration dates and for renewing SSL certificates that you upload and use with CloudFront.

In addition, note the following limits on using SSL certificates with CloudFront:

  • You can associate a maximum of one SSL certificate with each CloudFront distribution.

  • You can upload a maximum of 10 SSL certificates to the IAM certificate store for each AWS account. To request a higher limit, go to Request IAM limit increase.

  • If you want to use the same certificate with multiple CloudFront distributions that were created with different accounts, you must upload the certificate to the IAM certificate store once for each AWS account.

  • If you want to use the same certificate both for CloudFront and for other AWS services, you must upload the certificate twice: once for CloudFront and once for the other services. For information about how to upload the certificate for CloudFront, see the following procedure.

  • When you're using a custom origin, the SSL certificate on your origin includes a domain name in the Common Name field and possibly several more in the Subject Alternative Names field. (CloudFront supports wildcard characters in certificate domain names.) One of the domain names in the certificate must match the domain name that you specify for Origin Domain Name. If the domain names don't match, CloudFront returns an HTTP status code 502 (bad gateway) to the end user.

  • If you want to serve HTTPS requests using dedicated IP addresses, note the following:

To use alternate domain names with HTTPS

  1. If you want to serve HTTPS requests using SNI, skip to step 2.

    If you want to serve HTTPs requests using dedicated IP addresses, request permission for your AWS account. We'll update your account as soon as possible. For more information and to request permission, see Custom SSL Certificates for Amazon CloudFront.

    Important

    By default, when you request permission to use an alternate domain name with HTTPS, AWS updates your account so you can associate two custom SSL certificates with your CloudFront distributions. Typically, you'll use the second certificate only temporarily, when you have more than one distribution and you need to rotate certificates. If you need to permanently associate two or more certificates with your distributions, indicate how many certificates you need and describe the circumstances in your request.

  2. Use the AWS CLI to upload your SSL certificate to the IAM certificate store. If you don't already have your certificate, see Creating, Uploading, and Deleting Server Certificates in Using IAM.

    If you already have your certificate, use the following AWS CLI command to upload a signed certificate:

    aws iam upload-server-certificate --server-certificate-name CertificateName --certificate-body file://public_key_certificate_file --private-key file://privatekey.pem --certificate-chain file://certificate_chain_file --path /cloudfront/path/

    Note the following:

    • You must upload your certificate to the IAM certificate store using the same AWS account that you used to create your CloudFront distribution.

    • When you upload your certificate to IAM, the value of the -path parameter (certificate path) must start with /cloudfront/, for example, /cloudfront/production/ or /cloudfront/test/. The path also must end with a /.

    • If you plan to use the CloudFront console to create or update your distribution, the value that you specify for the --server-certificate-name parameter in the AWS CLI is the value that will appear in the SSL Certificate list in the CloudFront console.

    • If you plan to use the CloudFront API to create or update your distribution, make note of the alphanumeric string that the AWS CLI returns, for example AS1A2M3P4L5E67SIIXR3J. This is the value that you will specify in the IAMCertificateId element. You don't need the IAM ARN, which is also returned by the CLI.

    For more information about the AWS CLI, go to the AWS Command Line Interface User Guide and the AWS Command Line Interface Reference.

  3. Update your distribution to include your alternate domain names, to specify which SSL certificate you want to use, and to specify whether you want CloudFront to use dedicated IP addresses or SNI to serve HTTPS requests. You also need to add or update DNS records. For more information and a procedure, see Using Alternate Domain Names (CNAMEs).

    Caution

    After you associate your SSL certificate with your CloudFront distribution, do not delete the certificate from the IAM certificate store until you remove the certificate from all distributions and until the status of the distributions has changed to Deployed.

Determining the Size of the Public Key in an SSL Certificate

When you're using CloudFront alternate domain names and HTTPS, the size of the public key in an SSL certificate cannot exceed 2048 bits. (This is not the number of characters in the public key.) You can determine the size of the public key by running the following OpenSSL command:

openssl x509 -in path and filename of SSL certificate -text -noout 

where:

  • -in specifies the path and filename of your SSL certificate.

  • -text causes OpenSSL to display the length of the public key in bits.

  • -noout prevents OpenSSL from displaying the public key.

Example output:

Public-Key: (2048 bit)

Rotating SSL Certificates

Occasionally you'll need to replace one SSL certificate with another, because, for example, the expiration date is approaching. The process depends on whether you have associated your SSL certificate with one or more CloudFront distributions under the same AWS account:

  • SSL certificate associated with one distribution: You can just update your distribution and replace the old certificate with the new one. For more information, see Listing, Viewing, and Updating CloudFront Distributions.

  • SSL certificate associated with two or more distributions under the same AWS account: By default, when you request permission to use an alternate domain name with HTTPS, you can associate only two SSL certificates with the CloudFront distributions under one AWS account. Typically, you'll use the second certificate only when you have more than one distribution and you need to rotate certificates. One certificate is associated with distributions that you haven't updated yet, and the other certificate is associated with distributions that you have updated. Perform the following procedure.

    Important

    While you are rotating certificates, you might incur an additional, pro-rated charge for using the second certificate. We recommend that you update your distributions promptly to minimize the additional charge.

To rotate SSL certificates for two or more CloudFront distributions

  1. If you configured CloudFront to use dedicated IP addresses to serve HTTPS requests and you have already associated the maximum number of SSL certificates permitted by AWS for your account, request permission to associate an additional certificate. Send an email to cloudfront-ssl-request@amazon.com, and explain that you are rotating certificates.

  2. Update your distributions one at a time to use a new certificate.

    If you submitted a request to AWS in Step 1, wait until you receive notification that your AWS account has been updated.

    For more information, see Listing, Viewing, and Updating CloudFront Distributions.

  3. (Optional) After you have updated all of your CloudFront distributions, you can delete the old certificate from the IAM certificate store.

    Caution

    Do not delete an SSL certificate from the IAM certificate store until you remove it from all distributions and until the status of the distributions that you have updated has changed to Deployed.

Reverting from a Custom SSL Certificate to the Default CloudFront Certificate

If you configured CloudFront to use a custom SSL certificate and you want to change your configuration to use CloudFront's SSL certificate, the process depends on whether you've used your distribution to distribute your content:

  • If you have not used your distribution to distribute your content, you can just change the configuration. For more information, see Listing, Viewing, and Updating CloudFront Distributions.

  • If you have used your distribution to distribute your content, you need to create a new CloudFront distribution and change the URLs for your objects to reduce or eliminate the amount of time that your content is unavailable. Perform the following procedure.

To revert to the default CloudFront certificate

  1. Create a new CloudFront distribution with the desired configuration. For SSL Certificate, choose Default CloudFront Certificate (*.cloudfront.net).

    For more information, see Task List for Creating a Web Distribution.

  2. For objects that you're distributing using CloudFront, update the URLs in your application to use the domain name that CloudFront assigned to the new distribution. For example, change https://www.example.com/images/logo.png to https://d111111abcdef8.cloudfront.net/images/logo.png.

  3. Either delete the distribution that is associated with a custom SSL certificate, or update the distribution to change the value of SSL Certificate to Default CloudFront Certificate (*.cloudfront.net). For more information, see Listing, Viewing, and Updating CloudFront Distributions.

    Important

    Until you complete this step, Amazon Web Services continues to charge you for using a custom SSL certificate.

  4. (Optional) Use the AWS CLI to delete your custom SSL certificate from the IAM certificate store. This is the same application that you used to add the custom SSL certificate to the IAM certificate store:

    1. Run the AWS CLI command list-signing-certificates to get the certificate ID of the certificate that you want to delete. For more information, see list-signing-certificates in the AWS Command Line Interface Reference.

    2. Run the AWS CLI command delete-signing-certificateto delete the certificate. For more information, see delete-signing-certificate in the AWS Command Line Interface Reference.

Switching from a Custom SSL Certificate with Dedicated IP Addresses to SNI

If you configured CloudFront to use a custom SSL certificate with dedicated IP addresses, you can switch to using a custom SSL certificate with SNI instead. The following procedure shows you how.

Important

This update to your CloudFront configuration has no effect on viewers that support SNI; they can access your content before and after the change, as well as while the change is propagating to CloudFront edge locations. Viewers that don't support SNI cannot access your content after the change. For more information, see Choosing How CloudFront Serves HTTPS Requests.

To switch from a custom SSL certificate with dedicated IP addresses to SNI

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

  2. In the top pane of the CloudFront console, select the distribution that you want to view or update.

  3. Click Distribution Settings.

  4. On the General tab, click Edit.

  5. Change the setting of Custom SSL Client Support to Only Clients that Support Server Name Indication (SNI).

  6. Click Yes, Edit.

Charges for HTTPS Connections

You always incur a surcharge for HTTPS requests. For more information, see Amazon CloudFront Pricing.