How to Use Custom Domain with CloudFront: Step-by-Step Guide

To use a custom domain with CloudFront, first create or import an SSL certificate in AWS Certificate Manager (ACM) for your domain. Then, configure your CloudFront distribution to use this certificate and update your domain's DNS to point to the CloudFront distribution's domain name.

Syntax

Here is the basic setup pattern to use a custom domain with CloudFront:

• CertificateArn: The ARN of your SSL certificate in ACM.
• Aliases: Your custom domain names (e.g., www.example.com).
• DefaultCacheBehavior: Defines how CloudFront handles requests.
• OriginDomainName: The source of your content (e.g., S3 bucket or web server).

json

{
  "DistributionConfig": {
    "Aliases": {
      "Quantity": 1,
      "Items": ["www.example.com"]
    },
    "ViewerCertificate": {
      "ACMCertificateArn": "arn:aws:acm:region:account:certificate/your-certificate-id",
      "SSLSupportMethod": "sni-only"
    },
    "Origins": {
      "Quantity": 1,
      "Items": [
        {
          "Id": "origin1",
          "DomainName": "your-bucket.s3.amazonaws.com"
        }
      ]
    },
    "DefaultCacheBehavior": {
      "TargetOriginId": "origin1",
      "ViewerProtocolPolicy": "redirect-to-https",
      "TrustedSigners": {
        "Enabled": false,
        "Quantity": 0
      }
    },
    "Enabled": true
  }
}

Example

This example shows how to create a CloudFront distribution with a custom domain cdn.example.com using an ACM certificate and an S3 bucket as origin.

bash

aws cloudfront create-distribution --distribution-config '{
  "CallerReference": "unique-string-12345",
  "Aliases": {
    "Quantity": 1,
    "Items": ["cdn.example.com"]
  },
  "DefaultRootObject": "index.html",
  "Origins": {
    "Quantity": 1,
    "Items": [{
      "Id": "S3-origin",
      "DomainName": "example-bucket.s3.amazonaws.com",
      "S3OriginConfig": {"OriginAccessIdentity": ""}
    }]
  },
  "DefaultCacheBehavior": {
    "TargetOriginId": "S3-origin",
    "ViewerProtocolPolicy": "redirect-to-https",
    "AllowedMethods": {
      "Quantity": 2,
      "Items": ["GET", "HEAD"]
    },
    "ForwardedValues": {
      "QueryString": false,
      "Cookies": {"Forward": "none"}
    }
  },
  "ViewerCertificate": {
    "ACMCertificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/abcd1234-5678-90ab-cdef-EXAMPLE11111",
    "SSLSupportMethod": "sni-only",
    "MinimumProtocolVersion": "TLSv1.2_2021"
  },
  "Enabled": true
}'

Output

{
  "Distribution": {
    "Id": "E1234567890ABC",
    "Status": "InProgress",
    "DomainName": "d1234abcd.cloudfront.net"
  }
}

Common Pitfalls

• Not using ACM in the us-east-1 region: CloudFront requires SSL certificates to be in the us-east-1 region.
• DNS not updated: Forgetting to create a CNAME or alias record in your DNS to point your custom domain to the CloudFront domain.
• Certificate not validated: Using a certificate that is not issued or validated will cause CloudFront to fail.
• Using the wrong SSL support method: For most cases, use sni-only unless you need legacy client support.

json

Wrong example:
{
  "ViewerCertificate": {
    "ACMCertificateArn": "arn:aws:acm:region:account:certificate/your-cert",
    "SSLSupportMethod": "vip"
  }
}

Right example:
{
  "ViewerCertificate": {
    "ACMCertificateArn": "arn:aws:acm:us-east-1:account:certificate/your-cert",
    "SSLSupportMethod": "sni-only"
  }
}

Quick Reference

• Use ACM certificates in us-east-1 for CloudFront.
• Set Aliases to your custom domain names.
• Update your DNS with a CNAME or alias record to CloudFront's domain.
• Use sni-only for SSL support method unless legacy support is needed.
• Enable HTTPS by setting ViewerProtocolPolicy to redirect-to-https.

Key Takeaways

Always use an ACM SSL certificate in the us-east-1 region for CloudFront custom domains.

Configure your CloudFront distribution with your custom domain in the Aliases section.

Update your DNS to point your custom domain to the CloudFront distribution domain name.

Set ViewerProtocolPolicy to redirect HTTP requests to HTTPS for secure connections.

Validate your SSL certificate before attaching it to CloudFront to avoid deployment errors.