You open the site and the page is white. The browser console is full of Refused to load the script and no request reaches the server. Or worse: you've set the Strict-Transport-Security header with a one-year max-age, and now one of the subdomains that only has HTTP has gone offline. The problem is almost always in the header value, not its name. This text is a reference for values: every security header with its exact syntax, its real effect, and the risk you take on by enabling it incorrectly.
What a security header is and what the browser does with it
A security header is a line in the HTTP response that tells the browser which resource to load, which not to, and under what conditions. The browser enforces this line, not your server. That means if the value is wrong, the server works fine and only the user sees nothing. This is what makes debugging it harder than a 500 error.
To see the current value, send a raw request:
curl -sI https://example.com | grep -iE 'strict-transport|content-security|x-frame|x-content-type|referrer|permissions'
If the output is empty, no security header is set. If you see a value, copy it somewhere before changing it. Restoring a broken CSP without the previous version is not a pleasant job.
Recommended value for each security header
Strict-Transport-Security
Forces the browser to use only HTTPS for a specified period. Syntax:
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
max-age is in seconds; 31536000 means one year. Only set includeSubDomains when all subdomains have valid HTTPS. This is where people make mistakes: they set the header on the main domain with includeSubDomains and then remember that an old subdomain for an internal panel is on HTTP. The result is that the panel won't open in any up-to-date browser, and there's no way back, because the browser won't trust HTTP until the max-age expires. If you're not sure, start with max-age=300 and after a week without problems, raise the number.
Only add preload when you intend to submit to the preload list; removal from that list takes months.
Content-Security-Policy
The hardest and most feature-rich header. It determines where scripts, styles, images, and frames are allowed to load from. A conservative and usable value:
Content-Security-Policy: default-src 'self'; script-src 'self' https://cdn.example.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; frame-ancestors 'self'; base-uri 'self'; form-action 'self'
Two points you'll run into in practice. First, 'unsafe-inline' in script-src renders almost all XSS protection useless; if you have WordPress or any other CMS that injects inline scripts, use a nonce instead of opening up 'unsafe-inline'. Second, frame-ancestors replaces X-Frame-Options and takes priority in today's browsers.
Never start a CSP directly on production with default-src 'none'. First enforce the same policy with Content-Security-Policy-Report-Only, read the reports for a few days, then apply it. The difference between the two is just one word, and the difference in their outcome can be a site going offline.
X-Content-Type-Options
X-Content-Type-Options: nosniff
It has only one valid value: nosniff. It prevents MIME sniffing, meaning the browser doesn't guess the file type from its content. If uploaded files are served with the wrong extension, this header prevents an image from turning into an executable script. The cost is that if your server sends the wrong Content-Type, the file no longer works "by force" and you have to fix the server header.
Referrer-Policy
Referrer-Policy: strict-origin-when-cross-origin
This is the default value in new browsers, but writing it explicitly is necessary on older sites that have a weaker value. If referrer data matters to you in analytics, don't set no-referrer; that value removes everything and blinds incoming traffic in your reports. For sites that have sensitive links (password reset tokens) in the URL, no-referrer on that specific path makes sense, not on the whole domain.
Permissions-Policy
Permissions-Policy: geolocation=(), camera=(), microphone=()
It closes access to browser APIs. Empty parentheses mean for no one, including the domain itself. If you have a chat widget or map on the site, set geolocation=(self) rather than ().
Value comparison table
| Header | Recommended value | Risk of incorrect activation |
|---|---|---|
| Strict-Transport-Security | max-age=31536000; includeSubDomains | HTTP subdomains locked until expiry |
| Content-Security-Policy | default-src 'self' + explicit sources | White page, breaking analytics scripts |
| X-Content-Type-Options | nosniff | Files with wrong Content-Type no longer load |
| Referrer-Policy | strict-origin-when-cross-origin | Loss of referrer data in analytics |
| Permissions-Policy | geolocation=(), camera=() | Interactive widgets stop working |
Where to set it: web server or application
If you have Nginx, put the headers in the server block, not in the application code. The advantage is that it also applies to static files, where PHP or Node doesn't run at all:
add_header Content-Security-Policy "default-src 'self'" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
Don't leave out the word always. Without it, Nginx doesn't add the header to error responses (4xx and 5xx), and those error pages remain unprotected too.
In Apache, the equivalent is Header always set in .htaccess or the vhost config. If you're on WordPress and don't want to touch the theme code, the complete guide to configuring security headers for a WordPress site covers the plugin and config path step by step.
One practical limitation that rarely comes up but is annoying: if you use a CDN, some headers are rewritten or removed by the CDN. Always test with curl -sI from outside the network, not from inside the server.
The correct order of work on a live site
- Save the current value of all headers with
curl -sI. - Apply the low-risk headers first:
X-Content-Type-OptionsandReferrer-Policy. - Put CSP in
Report-Onlymode and review the reports. - Start HSTS with
max-age=300, and after a week of health, raise it to one year. - After each change, manually test a key page and a form.
If your site is the target of volumetric attacks, a security header won't stop that; that layer is elsewhere. DDoS protection operates at the network layer and complements these headers, not replaces them.
For sites that have a login form or admin panel, a security header is only half the job. Take enabling two-factor authentication seriously, because CSP doesn't prevent password theft.
If you have an SSL error or an incomplete chain, fix that first; HSTS on a faulty certificate only makes the problem more permanent. Troubleshooting SSL errors in the browser is the right starting point. And if you want to know which IPs are attacking your site, blocking malicious IPs explains control panel and firewall methods.
Frequently asked questions
Can a security header slow down the site?
No, it has no direct effect on speed. The header only adds a few bytes to the response. The only indirect effect is that if CSP blocks a resource, the browser makes the request again, and that extra round trip increases load time. That too is a sign of a wrong CSP, not an inherent cost of the header.
Why did the page go white after setting CSP?
Because you set default-src to 'self' or 'none' and your site loads a script or font from another domain (CDN, Google Fonts, analytics service). The browser console shows the exact blocked address. Add that domain to the relevant directive, rather than removing the whole CSP.
What's the difference between X-Frame-Options and frame-ancestors?
X-Frame-Options is older and accepts only three values: DENY, SAMEORIGIN, and ALLOW-FROM, the last of which isn't supported in many browsers. frame-ancestors inside CSP is newer, accepts multiple domains, and takes priority. If you set both, new browsers enforce frame-ancestors.
Should I enable all headers at once?
No. Add each header separately and test the site after each one. Enabling several headers at once, when something breaks, turns finding the culprit from a few minutes into a few hours. The recommended order is given in the previous section.
If only one thing stays with you from this text, let it be this: test the max-age value in HSTS and default-src in CSP on a subdomain before applying them to production. Reverting these two is harder than any other header.