Enable mutual TLS for CloudFront distributions - Amazon CloudFront
Prerequisites and requirementsEnable mutual TLS (Console)Enable mutual TLS (AWS CLI)Viewer protocol policiesNext steps

Enable mutual TLS for CloudFront distributions

Prerequisites and requirements

CloudFront's mutual TLS verify mode requires all clients to present valid certificates during the TLS handshake and rejects connections without valid certificates. Before enabling mutual TLS on a CloudFront distribution, ensure you have:

  • Created a trust store with your Certificate Authority certificates

  • Associated the trust store with your CloudFront distribution

  • Ensured all distribution cache behaviors use an HTTPS-only viewer protocol policy

  • Ensured your distribution is using HTTP/2 (the default setting, Viewer mTLS is not supported on HTTP/3)

Note

Mutual TLS authentication requires HTTPS connections between viewers and CloudFront. You cannot enable mTLS on a distribution with any cache behaviors that support HTTP connections.

Enable mutual TLS (Console)

For new distributions

Viewer mTLS cannot be configured in the process of creating a new distribution in the CloudFront console. First create the distribution by any means (console, CLI, API), then edit the distribution settings to enable Viewer mTLS per the existing distributions instructions below.

For existing distributions

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

  2. From the distribution list, select the distribution you want to modify.

  3. Ensure the Viewer protocol policy is set to Redirect HTTP to HTTPS or HTTPS Only for all cache behaviors. (You can choose the Cache behaviors tab to view and update any cache behaviors with HTTP protocol policies.)

  4. Choose the General tab.

  5. In the Settings section, choose Edit.

  6. In the Connectivity section, find Viewer mutual authentication (mTLS).

  7. Toggle Enable mutual authentication to On.

  8. For Client certificate validation mode, select Required (all clients must present certificates) or Optional (clients can optionally present certificates).

  9. For Trust store, select your previously created trust store.

  10. (Optional) Toggle Advertise trust store CA names if you want CloudFront to send CA names to clients during the TLS handshake.

  11. (Optional) Toggle Ignore certificate expiration date if you want to allow connections with expired certificates.

  12. Choose Save changes.

Enable mutual TLS (AWS CLI)

For new distributions

The following example shows how to create a distribution configuration file (distribution-config.json) that includes mTLS settings:

{
  "CallerReference": "cli-example-1",
  "Origins": {
    "Quantity": 1,
    "Items": [
      {
        "Id": "my-origin",
        "DomainName": "example.com",
        "CustomOriginConfig": {
          "HTTPPort": 80,
          "HTTPSPort": 443,
          "OriginProtocolPolicy": "https-only"
        }
      }
    ]
  },
  "DefaultCacheBehavior": {
    "TargetOriginId": "my-origin",
    "ViewerProtocolPolicy": "https-only",
    "MinTTL": 0,
    "ForwardedValues": {
      "QueryString": false,
      "Cookies": {
        "Forward": "none"
      }
    }
  },
  "ViewerCertificate": {
    "CloudFrontDefaultCertificate": true
  },
  "ViewerMtlsConfig": {
    "Mode": "required", 
    "TrustStoreConfig": {
        "TrustStoreId": {TRUST_STORE_ID},
        "AdvertiseTrustStoreCaNames": true,
        "IgnoreCertificateExpiry": true
    }
  },
  "Enabled": true
}

Create the distribution with mTLS enabled using the following example command:

aws cloudfront create-distribution --distribution-config file://distribution-config.json

For existing distributions

Get the current distribution configuration using the following example command:

aws cloudfront get-distribution-config --id E1A2B3C4D5E6F7 --output json > dist-config.json

Edit the file to add mTLS settings. Add the following example section to your distribution configuration:

"ViewerMtlsConfig": {
    "Mode": "required", 
    "TrustStoreConfig": {
        "TrustStoreId": {TRUST_STORE_ID},
        "AdvertiseTrustStoreCaNames": true,
        "IgnoreCertificateExpiry": true
    }
}

Remove the ETag field from the file but save its value separately.

Update the distribution with the new configuration using the following example command:

aws cloudfront update-distribution \
    --id E1A2B3C4D5E6F7 \
    --if-match YOUR-ETAG-VALUE \
    --distribution-config file://dist-config.json

Viewer protocol policies

When using mutual TLS, all distribution cache behaviors must be configured with an HTTPS-only viewer protocol policy:

  • Redirect HTTP to HTTPS - Redirects HTTP requests to HTTPS before performing certificate validation.

  • HTTPS Only - Only accepts HTTPS requests and performs certificate validation.

Note

The HTTP and HTTPS viewer protocol policy is not supported with mutual TLS since HTTP connections cannot perform certificate validation.

Next steps

After enabling Viewer TLS on your CloudFront distribution, you can associate Connection Functions to implement custom certificate validation logic. Connection Functions allow you to extend the built-in mTLS authentication capabilities with custom validation rules, certificate revocation checking, and logging. For details on creating and associating Connection Functions, see Associate a CloudFront Connection Function.