HTTP Security Headers: Essential Configuration Guide

TL;DR

• Bottom line: Seven HTTP response headers form the essential security baseline -- HSTS, CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy, and Cross-Origin policies -- and every production site should set all of them.
• Key tool/command: curl -sI https://your-site.com | grep -iE "strict-transport|content-security|x-content-type|x-frame|referrer-policy|permissions-policy"
• Watch out for: Setting HSTS includeSubDomains when not all subdomains support HTTPS -- this locks out legitimate traffic with no easy undo.
• Works with: All web servers (Nginx, Apache, Caddy, IIS), all frameworks (Express/Helmet, Django, Spring Boot, ASP.NET), and all CDNs (Cloudflare, AWS CloudFront, Fastly).

Constraints

• HSTS header MUST only be sent over HTTPS -- never on HTTP responses
• HSTS with includeSubDomains requires ALL subdomains to support HTTPS -- misconfiguration blocks legitimate traffic
• HSTS preload is irreversible in practice -- once submitted to browser preload lists, removal takes months
• CSP with unsafe-inline defeats XSS protection -- use nonce-based or hash-based policies instead
• X-XSS-Protection MUST be set to 0 -- the filter is deprecated and can introduce vulnerabilities in older browsers
• Nginx add_header directives in inner blocks override ALL headers from outer blocks -- use include snippets

Quick Reference

Essential Security Headers

Headers to Remove (Information Disclosure)

Deprecated Headers (Do Not Use)

Decision Tree

START: What web server or framework are you using?
├── Nginx?
│   ├── YES → Use add_header in https server block; create /etc/nginx/snippets/security-headers.conf
│   └── NO ↓
├── Apache?
│   ├── YES → Enable mod_headers; use Header always set in VirtualHost or .htaccess
│   └── NO ↓
├── Caddy?
│   ├── YES → Use header directive in Caddyfile; HTTPS is automatic, add HSTS manually
│   └── NO ↓
├── Express/Node.js?
│   ├── YES → npm install helmet; app.use(helmet()) sets 11 headers with sane defaults
│   └── NO ↓
├── Django?
│   ├── YES → Configure SecurityMiddleware: SECURE_HSTS_SECONDS, SECURE_CONTENT_TYPE_NOSNIFF, etc.
│   └── NO ↓
├── CDN/Edge (Cloudflare, AWS)?
│   ├── YES → Configure via edge rules or transform rules
│   └── NO ↓
└── DEFAULT → Set headers at the reverse proxy level for consistent coverage

Step-by-Step Guide

1. Audit existing security headers

Before adding headers, check what your site currently sends. Use curl or an online scanner. [src4]

# Check all security headers at once
curl -sI https://your-site.com | grep -iE \
  "strict-transport|content-security|x-content-type|x-frame|referrer-policy|permissions-policy"

Verify: You should see each header listed. Missing headers indicate gaps to address.

2. Set Strict-Transport-Security (HSTS)

Start with a short max-age and increase after confirming HTTPS works on all subdomains. [src2]

# Start conservative (5 minutes), ramp up to 2 years
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload

Verify: curl -sI https://your-site.com | grep -i strict-transport should show the header.

3. Deploy Content-Security-Policy

Start in report-only mode to avoid breaking your site. Progressively tighten the policy. [src1]

# Phase 1: Report-only (no enforcement)
Content-Security-Policy-Report-Only: default-src 'self'; report-uri /csp-report

# Phase 2: Enforce
Content-Security-Policy: default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'none'

Verify: Open DevTools > Console. CSP violations appear as errors.

4. Set remaining essential headers

These headers are straightforward and rarely cause breakage. Apply all at once. [src3]

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
X-XSS-Protection: 0
Permissions-Policy: geolocation=(), camera=(), microphone=(), payment=(), usb=()

Verify: curl -sI https://your-site.com should show all headers. Score A+ on securityheaders.com.

5. Remove information disclosure headers

Strip server identification headers to reduce fingerprinting surface. [src1]

# Nginx: hide server version
server_tokens off;

Verify: curl -sI https://your-site.com | grep -iE "server:|x-powered-by" should show no version info.

Code Examples

Express/Node.js: Helmet.js (recommended)

const express = require('express');     // ^4.18.0
const helmet = require('helmet');       // ^8.0.0
const app = express();

// Default: sets 11 headers with secure defaults
app.use(helmet());

// Custom: override specific headers
app.use(helmet({
  strictTransportSecurity: {
    maxAge: 63072000,
    includeSubDomains: true,
    preload: true
  },
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'"],
      objectSrc: ["'none'"],
      baseUri: ["'none'"],
      frameAncestors: ["'none'"]
    }
  },
  referrerPolicy: { policy: 'strict-origin-when-cross-origin' }
}));

Django: SecurityMiddleware Settings

# settings.py -- Django SecurityMiddleware handles most headers
SECURE_HSTS_SECONDS = 63072000
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD = True
SECURE_CONTENT_TYPE_NOSNIFF = True
X_FRAME_OPTIONS = 'DENY'
SECURE_REFERRER_POLICY = 'strict-origin-when-cross-origin'
SECURE_SSL_REDIRECT = True

Nginx: Security Headers Snippet

# /etc/nginx/snippets/security-headers.conf
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
add_header Content-Security-Policy "default-src 'self'; script-src 'self'; object-src 'none'" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "DENY" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header X-XSS-Protection "0" always;
add_header Permissions-Policy "geolocation=(), camera=(), microphone=()" always;
server_tokens off;

Apache: VirtualHost Configuration

# Enable mod_headers: a2enmod headers
Header always set Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"
Header always set Content-Security-Policy "default-src 'self'; script-src 'self'; object-src 'none'"
Header always set X-Content-Type-Options "nosniff"
Header always set X-Frame-Options "DENY"
Header always set Referrer-Policy "strict-origin-when-cross-origin"
Header always set X-XSS-Protection "0"
Header always set Permissions-Policy "geolocation=(), camera=(), microphone=()"
Header always unset X-Powered-By
ServerTokens Prod

Caddy: Caddyfile Configuration

(security-headers) {
    header {
        Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"
        Content-Security-Policy "default-src 'self'; script-src 'self'; object-src 'none'"
        X-Content-Type-Options "nosniff"
        X-Frame-Options "DENY"
        Referrer-Policy "strict-origin-when-cross-origin"
        X-XSS-Protection "0"
        Permissions-Policy "geolocation=(), camera=(), microphone=()"
        -Server
    }
}

example.com {
    import security-headers
    root * /var/www/html
    file_server
}

Anti-Patterns

Wrong: Setting HSTS on HTTP responses

# BAD -- HSTS on port 80 is ignored by browsers and wastes bytes
server {
    listen 80;
    add_header Strict-Transport-Security "max-age=63072000" always;
}

Correct: HSTS only on HTTPS

# GOOD -- HSTS on HTTPS only; HTTP redirects to HTTPS
server {
    listen 80;
    return 301 https://$host$request_uri;
}
server {
    listen 443 ssl;
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;
}

Wrong: CSP with unsafe-inline

# BAD -- unsafe-inline allows injected scripts to execute, defeating CSP
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'

Correct: Nonce-based CSP

# GOOD -- only scripts with matching nonce execute
Content-Security-Policy: default-src 'self'; script-src 'nonce-abc123def456' 'strict-dynamic'

Wrong: X-XSS-Protection set to 1

# BAD -- the legacy XSS filter can be abused to selectively disable scripts
X-XSS-Protection: 1; mode=block

Correct: X-XSS-Protection disabled

# GOOD -- disable legacy filter; rely on CSP for XSS protection
X-XSS-Protection: 0

Wrong: Nginx headers in location blocks override server block headers

# BAD -- adding a header in location silently drops ALL server-level headers
server {
    add_header X-Frame-Options "DENY" always;
    add_header X-Content-Type-Options "nosniff" always;
    location /api {
        add_header Cache-Control "no-store";
        # X-Frame-Options and X-Content-Type-Options are now GONE for /api
    }
}

Correct: Use include snippet for consistent headers

# GOOD -- snippet ensures all headers present in every context
server {
    include snippets/security-headers.conf;
    location /api {
        include snippets/security-headers.conf;
        add_header Cache-Control "no-store";
    }
}

Wrong: HSTS preload without testing

# BAD -- submitting to preload list before verifying all subdomains use HTTPS
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload

Correct: Gradual HSTS rollout

# GOOD -- start small, verify, then increase
# Week 1: Strict-Transport-Security: max-age=300
# Week 2: Strict-Transport-Security: max-age=86400; includeSubDomains
# Month 2: Strict-Transport-Security: max-age=63072000; includeSubDomains
# Month 3+: Strict-Transport-Security: max-age=63072000; includeSubDomains; preload

Common Pitfalls

• HSTS locks out subdomains: Setting includeSubDomains when dev/staging subdomains don't have HTTPS makes them unreachable. Fix: Audit all subdomains for HTTPS support before enabling includeSubDomains. [src2]
• Nginx header inheritance broken: Any add_header in a location block drops all headers from parent server block. Fix: Use an include snippet in every block that adds headers. [src7]
• CSP breaks inline scripts: Strict CSP without auditing inline scripts breaks functionality. Fix: Start with Content-Security-Policy-Report-Only and review violations. [src1]
• Permissions-Policy syntax confusion: Old Feature-Policy used geolocation 'none' but Permissions-Policy uses geolocation=(). Mixing formats silently fails. Fix: Use only Permissions-Policy with new syntax. [src5]
• Missing always in Nginx: Without always, headers only appear on 2xx/3xx responses. Error pages lack security headers. Fix: Always use add_header ... always;. [src7]
• HSTS on HTTP port: HSTS on port 80 has no effect -- browsers only process it over HTTPS. Fix: Configure HSTS only in the HTTPS server block. [src2]
• Double headers from proxy and backend: Both reverse proxy and backend set same headers, causing duplicates. Fix: Set headers at one layer only. [src6]
• X-Frame-Options vs CSP frame-ancestors: X-Frame-Options only supports DENY/SAMEORIGIN. For granular control, use CSP frame-ancestors. Both can coexist. Fix: Use CSP frame-ancestors for new deployments; keep X-Frame-Options for legacy browsers. [src1]

Diagnostic Commands

# Audit all security headers
curl -sI https://your-site.com | grep -iE \
  "strict-transport|content-security|x-content-type|x-frame|referrer-policy|permissions-policy|x-xss|cross-origin|x-powered-by|server:"

# Check HSTS preload eligibility: https://hstspreload.org
# Mozilla Observatory: https://developer.mozilla.org/en-US/observatory
# securityheaders.com: https://securityheaders.com/?q=your-site.com
# CSP Evaluator: https://csp-evaluator.withgoogle.com/

# Check HSTS cache in Chrome: chrome://net-internals/#hsts

# Verify Nginx config before reload
nginx -t && nginx -s reload

# Check Apache modules (need mod_headers)
apachectl -M | grep headers

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• HSTS preload submits your domain to a hardcoded list in all major browsers -- if you later need HTTP, you cannot easily undo this
• CSP report-uri is deprecated in favor of report-to (Reporting API), but report-to is not yet supported in all browsers -- use both during transition
• Permissions-Policy is a W3C Draft and available directives change between browser versions -- check MDN for current support
• Cross-Origin-Embedder-Policy: require-corp breaks cross-origin resources without Cross-Origin-Resource-Policy -- audit third-party resources first
• The Server header cannot always be fully removed -- some web servers add it after application-level headers
• Security headers at the CDN/edge level may override or duplicate origin server headers -- configure at one layer only