CloudFront Viewer mTLS — Verifying the Client at the Edge

The Problem

The companion feature answered “how does the originknow a request really came from CloudFront?” Viewer mTLS answers the mirror question: how does CloudFront — and the app behind it — know the client is who it claims to be, cryptographically, at the edge, before spending any backend compute?

The standard answers are the same compromises, one layer up. An API key / bearer tokenin a header is a static secret that leaks the way a shared-secret origin header did — copyable from a log line, a proxy, a phone, an ex-employee’s notes — and rotating it across a fleet of callers is a coordinated, therefore rare, event. An IP allowlist / WAF rule proves network provenance, not identity, and is brittle for roaming clients or device fleets. Application-layer auth only fires afterthe request has already traversed CloudFront, the cache, and the origin handshake — you pay full transit cost just to say “no”.

Before November 2025 you could not terminate client-certificate authentication at CloudFront at all. You either pushed mTLS down to an ALB or API Gateway behindthe distribution — losing the edge, because an untrusted client still transits the CDN and burns an origin handshake before rejection — or bolted a token check onto a CloudFront Function, re-creating the bearer-token pattern. AWS then shipped viewer mTLS: CloudFront validates the viewer’s X.509 client certificate against a trust store (a CA bundle you control) at the edge POP, before the request is cached or forwarded.

This post analyses the feature from an architect’s seat — the trust model, where it sits relative to API keys and WAF, the three enforcement modes, the genuinely hard revocation-at-global-scale problem, and the operational cost that actually matters (distributing and rotating client certs across a fleet, not the CloudFront config) — using a deliberately minimal lab: client → CloudFront (viewer mTLS, mode = required) → a private S3 origin via OAC, with a self-signed CA issuing one client leaf.

Architecture & Data Flow

The whole lab proves one boundary: the client→CloudFront hop is mutually authenticated at the edge, so a request without a trusted client certificate is rejected during the TLS handshake — globally, before any compute, cache, or origin fetch. Everything else is two tiny S3 buckets — the cheapest possible scaffolding to observe that handshake.

Client (holds client certificate + key)
   │
   │  ① TLS handshake — presents client certificate
   ▼
CloudFront distribution     ──②  validate cert chain ──▶   CloudFront Trust Store
viewer_mtls_config=required       at the edge POP                │
(GLOBAL)                                                         │ ingests + pins
   │                                                             │ CA-bundle version
   │  ③  OAC-signed (SigV4) origin fetch                         ▼
   ▼                                                      S3 CA-bundle bucket
S3 origin bucket (private, OAC-only) ──▶ index.html      (ca-bundle.pem · versioned · SSE)

No valid client cert + mode=required  ⇒  TLS handshake REJECTED at the edge
(the request is never cached, forwarded, or billed past the rejected connection).

Solid numbered arrows ①–③ are the request path; the dashed arrow is the trust store ingesting and version-pinning its CA bundle. CloudFront and the trust store are global; the two S3 buckets are regional. There is no VPC, ALB, or EC2.

Phase 1 — Offline PKI bootstrap (one-shot, before the first plan)

A script mints a self-signed root CA (P-256, 7-day) and signs one leaf with EKU clientAuth — the viewer’s identity; a build-time assertion rejects an over-scoped leaf that also claims serverAuth. Only the public CA certificate (no private key) is uploaded to S3 as the trust source; the client leaf + key go to the caller out-of-band; the CA private key is shreded after signing, so the trust store is immutable. Unlike origin mTLS, there is no ACM import — the trust store ingests the bundle straight from S3. Private keys never enter the repo or Terraform state.

Phase 2 — The trust store and the gate (native HCL)

The trust store is built from the S3 bundle, pinned to an exact object versionso overwriting the bucket can’t silently change what the edge trusts. The distribution’s viewer_mtls_config turns the gate on. The whole thing is native Terraform — aws_cloudfront_trust_store and viewer_mtls_config shipped in the AWS provider within ~2 months of launch, so there is no CloudFormation escape-hatchhere (the contrast with the origin-mTLS lab is the whole story of the “Provider timing” decision below).

# modules/cloudfront_viewer_mtls/main.tf — pure native HCL, no escape-hatch.
resource "aws_cloudfront_trust_store" "this" {
  name = "${var.name_prefix}-trust-store"

  ca_certificates_bundle_source {
    ca_certificates_bundle_s3_location {
      bucket  = aws_s3_bucket.ca_bundle.id
      key     = aws_s3_object.ca_bundle.key
      region  = var.aws_region
      version = aws_s3_object.ca_bundle.version_id  # pin exact version — no silent re-trust
    }
  }
}

resource "aws_cloudfront_distribution" "this" {
  # ... origin (private S3 via OAC), default_cache_behavior ...

  # The point of the lab: the edge REJECTS any handshake whose client cert
  # does not chain to the trust-store CA — globally, before any compute.
  viewer_mtls_config {
    mode = "required"   # required | optional | passthrough
    trust_store_config {
      trust_store_id                 = aws_cloudfront_trust_store.this.id
      advertise_trust_store_ca_names = true
      ignore_certificate_expiry      = false
    }
  }

  viewer_certificate {
    cloudfront_default_certificate = true   # default *.cloudfront.net cert
  }
}

Phase 3 — The runtime handshake

1. A viewer opens TLS to the nearest CloudFront POP and presents its client certificate.
2. CloudFront validates the chain against a trust-store CA at the edge. With mode = required, a missing or untrusted certificate fails the handshake outright — the request is never cached, forwarded, or billed past the rejected connection.
3. On success, CloudFront performs an OAC-signed (SigV4) fetch from the private S3 origin and returns the object. The bucket policy grants s3:GetObject only to this distribution’s OAC principal (scoped by AWS:SourceArn) — the origin is never publicly reachable.

DOMAIN=$(terraform output -raw cloudfront_domain_name)

# With a cert that chains to the trust-store CA → 200 + the page from S3
curl --cert certs/client.pem --key certs/client.key "https://$DOMAIN/"

# Without a client cert → TLS handshake REJECTED at the edge (never reaches the origin)
curl "https://$DOMAIN/"

The boundary worth noticing: client identity is enforced at the TLS layer, at a globally distributed edge, before any layer-7 logic or compute runs — the earliest and most widely distributed enforcement point AWS offers.

Design Decisions

Extended Knowledge

Trust store mechanics at the edge

The trust store is a CloudFront-level object built from a PEM CA bundle in S3. Each edge POP performs X.509 path validation on the presented client certificate — signature chain to a bundle CA, validity period, and (if configured) revocation — and does not match subject or hostname, so any unexpired, unrevoked certificate under a trusted CA is accepted. Two knobs shape behaviour: advertise_trust_store_ca_names makes CloudFront list the trusted CA names in the TLS CertificateRequest so a client holding several certs presents the right one; ignore_certificate_expiry is an escape hatch for clock-skew scenarios and should normally stay false. Versioning the bundle bucket means rolling back a bad bundle is a pointer flip, not a re-mint.

The “trust both ways” matrix

Five controls, each answering a different question. Crucially, viewer mTLS is authentication of the connection’s client identity, not authorization: it tells you who connected, never what they may do. Pair it with WAF and application authz.

The complete bidirectional design is viewer mTLS + (origin mTLS or OAC) — a mutually authenticated path front to back, with no static secret on the wire.

Revocation at global scale

OCSP stapling pushes freshness to the client/CA; a CRL is awkward to consult per handshake across hundreds of POPs; a serial denylist in CloudFront KeyValueStore (read by a CloudFront Function right after the handshake) gives near-real-time revocation at the cost of an extra moving part. The deeper call is often to avoid standing revocation infrastructure entirely by issuing short-lived client certificates and re-enrolling frequently — revocation latency stops mattering when certs expire in hours. Treat the client-cert rotation cadence as an SLO with its own alarms.

Where viewer mTLS is not the answer

It authenticates a connection’s client identity; it does not authorize actions, does not replace session management, and does not help when the client is an anonymous public browser (you can’t enroll the whole internet with certs). It shines for closed audiences— B2B partners, device fleets, internal service-to-edge calls — where you control enrollment. A frequent design error is treating “presented a valid cert” as “is fully authorized”; the cert identifies the principal, and a separate policy still decides scope. The feature also requires a paid CloudFront plan (Business / Premium / PAYG), not the Free plan.

Security & Cost Posture

Security highlights

• Identity at the edge: client identity is verified at the TLS layer, before cache or compute — the earliest, most globally distributed enforcement point available; the private key never leaves the client
• Both S3 buckets: private, SSE-encrypted, versioned, public access fully blocked; the origin is OAC-only (bucket policy scoped by AWS:SourceArn); the CA bundle is pinned to an exact object version
• Single-purpose CA whose private key is shredded after signing — only the public CA cert is uploaded; keys never enter Terraform state or the repo
• Forwarded cert-metadata headers (when used) must be edge-trusted-only — strip any client-supplied lookalike, or a client forges its own identity claim

Accepted lab risks — and their production preconditions

Recorded in the spec with explicit prod-blocking preconditions: a self-signed CA (production → ACM Private CA or a third-party CA with a renewal runbook + a DaysToExpiry alarm); no WAF on the edge (production → a WAFv2 web ACL, scope CLOUDFRONT in us-east-1); no revocation (production → OCSP, a KeyValueStore denylist, or short-lived certs); and no access / real-time logs — the same detective-controls blind spot the origin lab flagged. The preventive posture is solid; the evidence trail is the production gap.

Cost model

The headline is the contrast with the origin-mTLS sibling: no ALB, no EC2, so effectively no fixed run-rate. The footprint is CloudFront request/transfer pennies + a tiny S3 cost + the trust store (no hourly charge). An 8-hour lab day rounds to a few cents, and even left running there is no ALB/EC2 drip — teardown is hygiene, not financial urgency. The structural levers are unchanged: avoiding AWS Private CA (~$400/month) with a self-signed CA, and the paid CloudFront plan as a flat prerequisite, not a per-request surcharge.

Takeaways

References

• Trust goes both ways: Amazon CloudFront now supports viewer mTLS — AWS News Blog
• Companion post — CloudFront mTLS to Origins (the other direction)
• aws_cloudfront_trust_store & viewer_mtls_config — Terraform Registry
• RFC 5280 — Internet X.509 PKI Certificate and CRL Profile (EKU semantics)