Security Headers Without Breaking Your Site

Security headers change browser behavior. Adding a strict policy without testing can stop scripts, fonts, media, or login popups that the product depends on. A safer rollout starts with an inventory of what the page loads and which cross-origin interactions it actually needs.

Take one representative page and list scripts, styles, images, fonts, frames, and outgoing connections. Repeat for the unusual flows: video playback, a checkout, a popup login, and an error page. The homepage alone rarely exercises every dependency. Keep the inventory small enough to review instead of allowing every origin indefinitely.

Observe before enforcing CSP

Content-Security-Policy-Report-Only:
  default-src 'self';
  object-src 'none';
  base-uri 'self'

A report-only policy reveals violations without blocking the resource. Use the observations to understand dependencies and remove unnecessary ones. Report-only is a diagnostic stage; it does not provide the protection of an enforced policy. A reporting endpoint also needs operational care because reports are untrusted input and can contain sensitive URLs.

For inline scripts, prefer a deliberate nonce or hash strategy when the application requires them. Do not solve every violation by adding broad unsafe allowances. Test the delivered HTML and response headers together: a correct-looking configuration file does not establish what the browser received.

Treat transport and isolation separately

HSTS tells returning HTTPS clients to use secure transport for a host. Confirm HTTPS reliability before choosing a long lifetime, and think carefully before including subdomains. Cross-origin opener and embedder policies solve different problems. They can affect popup relationships and resource loading, so enable them only with a clear feature or threat model and a tested dependency graph.

For a small documentation site, a correct content type, nosniff, a considered referrer policy, and a narrowly tested CSP are often useful starting work. The example values in the reference are not a bundle that every application should copy unchanged.

Keep a browser test alongside the policy

Check normal navigation, keyboard controls, downloads, media seeking, and any third-party handoff in the browsers you support. Inspect failures with the enforced policy enabled. Store the final policy with the source, document intentional exceptions, and review those exceptions when dependencies change. A header scanner can catch omissions, but it cannot tell whether the product’s important workflows still work.

Reference tables to keep nearby

• Browser Security Headers Reference — Security-related HTTP response headers, small example policies, and deployment checks for ordinary websites.

Primary sources

These are the specifications and project documentation behind the examples. Check the relevant implementation and version before applying a pattern.

• MDN HTTP header reference
• W3C Content Security Policy