How to set up HSTS on your Hugo Netlify site

HSTS helps make your HTTPS website even more secure.

Ron Erdos • Updated October 14, 2020

What is HSTS and why should you care?

HSTS, which stands for “HTTP Strict Transport Security” is a way to add extra security to HTTPS websites. It helps prevent attackers from circumventing the security features of HTTPS.

For a full description, check out Wikipedia's HSTS page.

Google’s HSTS Preload List

Although not an official part of the HSTS spec, Google maintains an opt-in list of sites using HSTS.

The reason Google does this is so that sites can use HSTS on a user’s first visit.

If Google’s HSTS list did not exist, HSTS would only truly kick in upon a user’s second and subsequent visits, leaving a security hole in the user’s first visit.

The way Google activates HSTS on a user’s first visit to a site is by including a list of all known HSTS sites in the source code of its Chrome browser. Other browsers, including Firefox, Edge, Safari and Opera also use Google’s HSTS preload list.

How to check whether a website is on Google’s HSTS Preload list

You can check whether your site is using HSTS or not at Google’s HSTS Preload website.

Before I added HSTS to this site, I checked it and got the following result:

Status: moonbooth.com is not preloaded.

Eligibility: In order for moonbooth.com to be eligible for preloading, the errors below must be resolved:

Error: No includeSubDomains directive
The header must contain the includeSubDomains directive.

Error: No preload directive
The header must contain the preload directive.

When I saw that, of course I wanted to add HSTS. Here’s how I did it.

How to make a Hugo website hosted on Netlify eligible for Google’s HSTS preload list

Before jumping into the specifics, here’s a bit of background:

Okay, that said, here’s how I set up HSTS on my Netlify Hugo site in netlify.toml:

[[headers]]
  for = "/*"
  [headers.values]
	Strict-Transport-Security = "max-age=63072000; includeSubDomains; preload"

NB: That max-age of 63072000 is two years. Google’s minimum is one year, but it appears that Netlify wants two years. I don’t have any subdomains on this site, but I’m running includeSubDomains, again, because Netlify appears to want it (see link in this paragraph).

I saved, committed, and pushed those changes to Netlify. Time to see if it worked!

I went back to Google’s HSTS Preload site and checked my site again.

This time, I saw a better picture:

Status: moonbooth.com is not preloaded.

Eligibility: moonbooth.com is eligible for the HSTS preload list.

And a “submit” button, followed by the following agreement request:

I am the site owner of moonbooth.com or have their permission to preload HSTS. (If this is not the case, moonbooth.com may be sending the HSTS preload directive by accident. Please contact hstspreload@chromium.org to let us know.)

I understand that preloading moonbooth.com through this form will prevent all subdomains and nested subdomains from being accessed without a valid HTTPS certificate:
*.moonbooth.com
*.*.moonbooth.com

I hammered that “submit” button and saw this joyful sight:

Success
moonbooth.com is now pending inclusion in the HSTS preload list!

Please make sure that moonbooth.com continues to satisfy all preload requirement, or it will be removed. Please revisit this site over the next few weeks to check on the status of your domain.

Also consider scanning for TLS issues using SSL Labs.

Wrapping up

I’ll update this post if/when I’ve been formally included in Google’s HSTS preload list. Good luck adding HSTS to your Hugo site!

UPDATE 15 DEC 2020: Okay, so I forgot to check earlier, but moonbooth.com is now on Google's HSTS preload list:

Status: moonbooth.com is currently preloaded

Boom! Now moonbooth.com is extra secure.

"Thanks so much for your work ... I'm migrating my WordPress blog to Hugo and it's been really helpful." — Francisco S., engineer and blogger

"I love your content. The information that you provide have been very useful in the development of my personal website." — Mattia C., engineer and researcher

The planets in our solar system