CloudFront Response Headers Policies: Security Headers, SEO Tags, and CORS

What response headers policies do

A response headers policy in CloudFront lets you add, override, or remove HTTP response headers for every response — before CloudFront returns it to the client. The origin doesn't need to change. You configure the policy once and attach it to a cache behavior.

Common uses:

• Security headers: HSTS, Content-Security-Policy, X-Frame-Options, X-Content-Type-Options
• SEO directives: X-Robots-Tag: noindex for staging environments
• CORS headers: centralize CORS policy instead of configuring every origin individually
• Custom headers: add environment indicators, cache diagnostics, or client hints

Blocking search engine indexing for staging environments

The problem: Google indexes your staging environment, creating duplicate content that hurts your production site's SEO ranking.

The fix: add X-Robots-Tag: noindex, nofollow to all responses from the staging CloudFront distribution.

In Terraform:

resource "aws_cloudfront_response_headers_policy" "staging_noindex" {
  name = "staging-noindex"

  custom_headers_config {
    items {
      header   = "X-Robots-Tag"
      value    = "noindex, nofollow"
      override = true  # overwrite any X-Robots-Tag from the origin
    }
  }
}

resource "aws_cloudfront_distribution" "staging" {
  # ... origin and other config ...

  default_cache_behavior {
    target_origin_id           = "staging-origin"
    viewer_protocol_policy     = "redirect-to-https"
    response_headers_policy_id = aws_cloudfront_response_headers_policy.staging_noindex.id

    # ... other settings ...
  }
}

After updating the behavior, create a cache invalidation to clear any cached responses that don't have the header:

aws cloudfront create-invalidation \
  --distribution-id E1234567890ABC \
  --paths "/*"

Security headers policy

AWS provides a managed SecurityHeadersPolicy that adds standard security headers. You can also create custom policies:

resource "aws_cloudfront_response_headers_policy" "security" {
  name = "security-headers"

  security_headers_config {
    # Force HTTPS for 1 year; include subdomains
    strict_transport_security {
      access_control_max_age_sec = 31536000
      include_subdomains         = true
      preload                    = true
      override                   = true
    }

    # Prevent clickjacking
    frame_options {
      frame_option = "DENY"
      override     = true
    }

    # Prevent MIME type sniffing
    content_type_options {
      override = true
    }

    # Referrer policy
    referrer_policy {
      referrer_policy = "strict-origin-when-cross-origin"
      override        = true
    }

    # XSS protection (legacy, but still useful)
    xss_protection {
      mode_block  = true
      protection  = true
      override    = true
    }
  }

  # Custom CSP header (not in security_headers_config block)
  custom_headers_config {
    items {
      header   = "Content-Security-Policy"
      value    = "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.example.com; img-src *"
      override = true
    }
  }
}

CORS policy

For APIs accessed from browsers, centralize CORS headers in the response headers policy rather than in your Lambda or application code:

resource "aws_cloudfront_response_headers_policy" "cors" {
  name = "api-cors"

  cors_config {
    access_control_allow_credentials = true

    access_control_allow_headers {
      items = ["Authorization", "Content-Type", "X-Api-Key"]
    }

    access_control_allow_methods {
      items = ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
    }

    access_control_allow_origins {
      items = ["https://app.example.com", "https://www.example.com"]
    }

    access_control_max_age_sec = 86400  # cache preflight for 1 day
    origin_override            = true
  }
}

origin_override = true means the CloudFront policy's CORS headers overwrite any CORS headers your origin sends. Use false if you want your origin to control CORS and CloudFront to only add headers when the origin sends none.

// CloudFront Function: add environment indicator based on request path
function handler(event) {
    var response = event.response;
    var request = event.request;

    // Add cache diagnostics header
    response.headers['x-cache-status'] = {
        value: response.headers['x-cache'] ? response.headers['x-cache'].value : 'UNKNOWN'
    };

    // Add different CSP based on path
    if (request.uri.startsWith('/admin')) {
        response.headers['content-security-policy'] = {
            value: "default-src 'self'; script-src 'self'"
        };
    } else {
        response.headers['content-security-policy'] = {
            value: "default-src 'self' https://cdn.example.com"
        };
    }

    return response;
}

Managed response headers policies

AWS provides several pre-built policies available by name:

• SecurityHeadersPolicy: HSTS, X-Frame-Options SAMEORIGIN, X-Content-Type-Options nosniff, Referrer-Policy strict-origin-when-cross-origin, X-XSS-Protection
• CORSWithDefaultHeaders: standard CORS headers allowing all origins (not suitable for credentialed requests)
• CORSWithSecurityHeadersPolicy: CORS + security headers combined
• SimpleCORS: minimal CORS with Access-Control-Allow-Origin: *

# List available managed policies
aws cloudfront list-response-headers-policies \
  --type managed \
  --query 'ResponseHeadersPolicyList.Items[].{Name:ResponseHeadersPolicy.ResponseHeadersPolicyConfig.Name,Id:ResponseHeadersPolicy.Id}'

Use managed policies as a starting point for standard configurations and customize from there.