Apache guide · Strict-Transport-Security

How to enable HSTS (Strict-Transport-Security) on Apache

Enable HSTS on Apache: send Strict-Transport-Security from the HTTPS virtual host only, with always, on every redirect and error page, without duplicates. Tested configs.

  • By
  • Updated
  • 5 min read
  • Tested on Apache httpd 2.4.58, 2.4.62 and 2.4.69
$ curl -sI https://example.com/missing
status
HTTP/2 404
server
Apache
strict-transport-security
max-age=31536000; includeSubDomains

Present on error pages too

In short5 points
  • Add Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains" to the <VirtualHost *:443>, and redirect port 80 to HTTPS with Redirect permanent.
  • Keep always: with Header set, Apache sends no HSTS header on 404 pages and redirects.
  • Every HTTPS virtual host needs the header, including one that only redirects example.com to www.example.com.
  • For a server-wide line, add the condition "expr=%{HTTPS} == 'on'" so plain HTTP responses do not carry it.
  • Behind mod_proxy_http, an application that sends HSTS too produces two headers. Put Header unset Strict-Transport-Security before the always line.

The short answer

Redirect port 80 to HTTPS, and add the header to the virtual host that listens on 443:

Apache
<VirtualHost *:80>
    ServerName example.com
    Redirect permanent / https://example.com/
</VirtualHost>

<VirtualHost *:443>
    ServerName example.com
    DocumentRoot "/var/www/example"
    SSLEngine on
    SSLCertificateFile    /etc/ssl/example.com/fullchain.pem
    SSLCertificateKeyFile /etc/ssl/example.com/privkey.pem

    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
</VirtualHost>
Shell
sudo apachectl configtest && sudo apachectl graceful

always keeps the header on error pages and redirects. The port 80 host has no header on purpose: browsers ignore HSTS over plain HTTP. Every snippet below was run on Apache httpd 2.4.58, 2.4.62 and 2.4.69 and checked with curl, on a page, a 404 and a redirect.

max-age=31536000 (one year) with includeSubDomains is what WebSec0 grades as a pass, but it is a final value, not a starting point. Read how to roll out HSTS without locking users out before you ship it, and check that every subdomain works over HTTPS.

Before you start

The Header directive comes from mod_headers. Check that it is loaded, then list your virtual hosts and any existing Header lines:

Shell
apachectl -M | grep headers
apachectl -S
grep -rn "Strict-Transport-Security" /etc/apache2/ /etc/httpd/ 2>/dev/null

If headers_module is missing, enable it with sudo a2enmod headers on Debian and Ubuntu, or uncomment its LoadModule line in httpd.conf.

You are looking for three things:

  • Every virtual host on 443. Each one needs the header, including hosts that only redirect.
  • An existing HSTS line, in another file, in .htaccess, or set by the application. Two headers cause trouble (step 5).
  • The port 80 hosts. They should only redirect.

Step 1: start with a short max-age

A long max-age stays in visitors’ browsers even if you remove the line. Start at five minutes:

Apache
Header always set Strict-Transport-Security "max-age=300; includeSubDomains"

Reload, browse your sites and subdomains, and watch your error rates. Then raise the value in steps, waiting a full max-age each time: 604800 (one week), 2592000 (30 days), then 31536000 (one year) or 63072000 (two years).

If a subdomain cannot serve HTTPS yet, leave includeSubDomains out until it can. WebSec0 grades a header without it as a warning, but a subdomain that stops loading is worse.

Step 2: keep it on error pages and redirects

Apache keeps two tables of response headers. Header set writes to the one used for successful responses; Header always set writes to the one that is also sent on errors and redirects. Our test with Header set:

HTTP
HTTP/1.1 200 OK
Strict-Transport-Security: max-age=31536000; includeSubDomains

HTTP/1.1 404 Not Found
(no Strict-Transport-Security header)

HTTP/1.1 301 Moved Permanently
(no Strict-Transport-Security header)

With Header always set, all three responses carried the header. A visitor’s first HTTPS response can be a 404 from an old link, or a redirect.

Step 3: cover every host and redirect

includeSubDomains only protects visitors whose browser has already seen the parent domain. A visitor who goes straight to www.example.com learns the policy from that host, so each HTTPS virtual host needs the header, including one that only redirects:

Apache
<VirtualHost *:80>
    ServerName example.com
    Redirect permanent / https://example.com/
</VirtualHost>

<VirtualHost *:80>
    ServerName www.example.com
    Redirect permanent / https://www.example.com/
</VirtualHost>

<VirtualHost *:443>
    ServerName example.com
    # SSLEngine and certificate lines...

    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
    Redirect permanent / https://www.example.com/
</VirtualHost>

<VirtualHost *:443>
    ServerName www.example.com
    # SSLEngine and certificate lines...

    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
</VirtualHost>

What our test returned:

Request Response
http://example.com/a 301 to https://example.com/a, no HSTS
http://www.example.com/a 301 to https://www.example.com/a, no HSTS
https://example.com/a 301 to https://www.example.com/a, with HSTS
https://www.example.com/ and a 404 With HSTS

Each port 80 host redirects to HTTPS on the same host first, then the HTTPS host moves visitors to www. Skipping that step, with http://example.com going straight to https://www.example.com, means browsers never receive HSTS for example.com. The HSTS preload list requires this order.

Step 4: one line for all virtual hosts

To set the header once, put it in the server configuration, outside any VirtualHost, with a condition so that plain HTTP responses do not carry it:

Apache
Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains" "expr=%{HTTPS} == 'on'"

Our test returned the header on the HTTPS host, its 404 included, and no header on the HTTP host.

Do not keep a Header set Strict-Transport-Security line in a virtual host as well. In our test, a server-wide Header always set combined with a Header set in the virtual host returned two identical HSTS headers on successful responses, because each line writes to a different table.

Step 5: one header behind a reverse proxy

Many frameworks send HSTS on their own. With mod_proxy_http and Header always set, our test returned both:

HTTP
HTTP/1.1 200 OK
Strict-Transport-Security: max-age=31536000; includeSubDomains
Strict-Transport-Security: max-age=300

Apache’s header came first, so browsers and WebSec0 applied it here, but the response is fragile and confusing. Remove the application’s header from the default table, then set yours in the always table:

Apache
<VirtualHost *:443>
    # ...
    ProxyPass "/" "http://127.0.0.1:8080/"
    Header unset Strict-Transport-Security
    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
</VirtualHost>

Our test then returned a single header, on pages and on 404s. The same pair of lines also handles CGI and mod_proxy_fcgi applications, whose headers Apache stores in the always table.

When Apache sits behind a load balancer or CDN that terminates TLS, it only sees plain HTTP. Send HSTS from the component that terminates TLS, or set the line in Apache without the %{HTTPS} condition. Make sure only one of the two sends it.

Verify it

Check a page, an error page and the redirects. Use your own host names:

Shell
curl -sI https://example.com/ | grep -i strict-transport-security
curl -sI https://example.com/does-not-exist | grep -i strict-transport-security
curl -sI http://example.com/ | grep -iE "^location|strict-transport-security"

The first two should print the header. The third should print a location: pointing to https://example.com/ and no HSTS header.

Count the headers to catch duplicates. The result should be 1:

Shell
curl -sI https://example.com/ | grep -ci '^strict-transport-security:'

Repeat for each host, then scan the site with WebSec0. The headers report shows the value it received and whether it passes.

Roll back

If a subdomain breaks after you enabled includeSubDomains, set the value to max-age=0, reload, and keep HTTPS running:

Apache
Header always set Strict-Transport-Security "max-age=0"

Our test returned max-age=0 on pages and 404s. Browsers forget the policy the next time they receive this header. Deleting the line instead leaves the old policy in place until it expires.

Troubleshooting

Symptom Likely cause Fix
Invalid command 'Header' mod_headers is not loaded a2enmod headers, or uncomment its LoadModule line.
Header missing on 404 pages or redirects Header set without always Write Header always set.
Header missing on www or another subdomain Only the main virtual host sends it Add it to every HTTPS virtual host, including redirects.
Two Strict-Transport-Security headers A proxied application sends one too, or a Header set and a Header always set coexist Header unset before Header always set, and keep one line per scope.
Header on http:// responses The line is server-wide or in the port 80 host Add "expr=%{HTTPS} == 'on'", or move it to the 443 host. Harmless, but browsers ignore it.
WebSec0 shows a warning max-age below 31536000 or no includeSubDomains Finish the rollout: one year with includeSubDomains.
Changes do not show up Reload skipped, or a CDN cached old headers apachectl configtest && apachectl graceful, then purge the CDN.

Server hub

Every header on Apache

Other web servers

Strict-Transport-Security on other servers

Questions

Frequently asked questions

Where do I put the HSTS header in Apache?

In the <VirtualHost *:443> block of each site, with Header always set. Do not put it in the port 80 virtual host: browsers ignore HSTS over plain HTTP, and that host should only redirect.

Why is HSTS missing on my 404 pages or redirects?

Header set writes to the table Apache uses for successful responses only. Error pages and redirects that Apache generates use the always table. Write Header always set.

Can I set HSTS once for all virtual hosts?

Yes, in the server configuration outside any VirtualHost, with the condition "expr=%{HTTPS} == 'on'". Do not combine it with a Header set line for the same header in a virtual host: our test returned two headers on successful responses.

My response has two Strict-Transport-Security headers. Which one counts?

Browsers apply the first one, and WebSec0 grades the first one too. Behind mod_proxy_http, Apache's always header came first in our test, and the application's after it. Add Header unset Strict-Transport-Security before the Header always set line to send one.

How do I turn HSTS off on Apache?

Change the value to max-age=0, reload, and keep serving HTTPS. Browsers drop the policy the next time they receive the header. Removing the line does not clear the policy browsers already stored.

Is mod_headers needed for HSTS?

Yes. The Header directive comes from mod_headers. Check it with apachectl -M | grep headers, and enable it with a2enmod headers on Debian and Ubuntu.

References

Sources

  1. Apache Module mod_headersApache HTTP Server Project
  2. Apache Module mod_alias: RedirectApache HTTP Server Project
  3. Expressions in Apache HTTP ServerApache HTTP Server Project

About the author

Portrait of Joshua Martinelle

Security engineer at Tenable

Security engineer at Tenable and web security researcher. He has disclosed more than 60 CVEs since 2020 and builds WebSec0.

Verify the change

Deployed it? Check it.

WebSec0 grades your TLS setup and security headers, including Strict-Transport-Security, in a few seconds. Free, no account.

Scan your site