In Django, how do you roll out HSTS with SECURE_HSTS_SECONDS, SECURE_HSTS_INCLUDE_SUBDOMAINS and SECURE_HSTS_PRELOAD without locking users out?

seniorshould knowfreq 40%

answer

only on HTTPS responses
start with an hour
subdomains inherit the promise
preload is hard to undo

basics

~10 s

Set SECURE_HSTS_SECONDS to a small value such as 3600, confirm every page works over HTTPS, then raise it to about a year. Add includeSubDomains only when every subdomain is HTTPS, and preload last.

solid answer

~30 s

SecurityMiddleware adds Strict-Transport-Security: max-age=<SECURE_HSTS_SECONDS> to HTTPS responses when the setting is non-zero and the header is not already present; SECURE_HSTS_INCLUDE_SUBDOMAINS appends includeSubDomains and SECURE_HSTS_PRELOAD appends preload. Browsers then refuse plain HTTP to the host for max-age seconds and will not let users click past certificate errors. So I roll it out in stages: 3600 seconds first, confirm nothing breaks, then 31536000 (one year). I add includeSubDomains only after checking every subdomain serves HTTPS, and preload last, because being on browser preload lists is slow to undo. If the header never appears behind a proxy, is_secure() is false and SECURE_PROXY_SSL_HEADER is missing.

`SecurityMiddleware` adds `Strict-Transport-Security: max-age=<SECURE_HSTS_SECONDS>` to HTTPS responses when the setting is non-zero and the header is not already present; `SECURE_HSTS_INCLUDE_SUBDOMAINS` appends `includeSubDomains` and `SECURE_HSTS_PRELOAD` appends `preload`. Browsers then refuse plain HTTP to the host for `max-age` seconds and will not let users click past certificate errors. So I roll it out in stages: 3600 seconds first, confirm nothing breaks, then 31536000 (one year). I add `includeSubDomains` only after checking every subdomain serves HTTPS, and `preload` last, because being on browser preload lists is slow to undo. If the header never appears behind a proxy, `is_secure()` is false and `SECURE_PROXY_SSL_HEADER` is missing.

code

python · 10 lines

python

# Stage 1: trial
SECURE_HSTS_SECONDS = 3600

# Stage 2, after verification:
# SECURE_HSTS_SECONDS = 31536000
# SECURE_HSTS_INCLUDE_SUBDOMAINS = True   # only once every subdomain serves HTTPS
# SECURE_HSTS_PRELOAD = True              # only if you intend to submit to preload lists

# Header on HTTPS responses at stage 2:
# Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

go deeper

for a junior

Recall that SECURE_HSTS_SECONDS turns HSTS on and that 0, the default, means no header.

for a middle

Explain when SecurityMiddleware adds the header (non-zero seconds, HTTPS request, header absent) and what the two flags append.

for a senior

Run a staged rollout, audit subdomains before includeSubDomains, treat preload as nearly irreversible, and diagnose a missing header behind a proxy.

for a principal

Set domain-wide policy: who may add subdomains, how certificates are monitored, and whether the organisation commits to preload.

What HSTS is

HTTP Strict Transport Security (HSTS) is a response header, Strict-Transport-Security, that tells a browser: for the next max-age seconds, only ever connect to this host over HTTPS. After seeing it, the browser rewrites http:// links to https:// before sending anything, which defeats attacks that intercept the first plain-HTTP request and keep the victim on HTTP. Browsers that honour it also refuse to let users bypass certificate errors for that host.

How Django sends it

SecurityMiddleware.process_response() adds the header when:

SECURE_HSTS_SECONDS is non-zero (the default is 0, meaning off);
request.is_secure() is true;
the response does not already have a Strict-Transport-Security header.

The value is built from three settings:

Setting	Default	Adds
`SECURE_HSTS_SECONDS`	`0`	`max-age=<seconds>`
`SECURE_HSTS_INCLUDE_SUBDOMAINS`	`False`	`; includeSubDomains`
`SECURE_HSTS_PRELOAD`	`False`	`; preload`

The two flags have no effect while SECURE_HSTS_SECONDS is 0. Because the header is added only to secure requests, a Django app behind a TLS-terminating proxy without SECURE_PROXY_SSL_HEADER never sends it; Django's own documentation calls out this symptom.

Why it can lock users out

HSTS is enforced by the browser, and the browser remembers it. If you later need plain HTTP (a certificate lapses, a subdomain is HTTP-only, a staging host shares the domain), every browser that saw the header refuses to connect for the rest of max-age, and users cannot click through the warning. You cannot recall the header; you can only send max-age=0 over HTTPS to browsers that come back.

A staged rollout

Prepare. Serve everything over HTTPS, including assets and redirects; turn on SECURE_SSL_REDIRECT or redirect at the edge.
Short trial. SECURE_HSTS_SECONDS = 3600. Django's documentation suggests one hour for testing.
Observe. Check that nothing on the site, including embedded resources and other hosts you link to under the same name, needs plain HTTP.
Long max-age. Raise to 31536000 (one year), a common production value, so infrequent visitors stay protected.
Subdomains. Inventory every subdomain (intranet tools, mail-related hosts, legacy apps). Only when all serve HTTPS, set SECURE_HSTS_INCLUDE_SUBDOMAINS = True.
Preload, optionally. SECURE_HSTS_PRELOAD = True only adds the preload directive; getting into browsers' built-in lists is a separate submission to the list maintainers. Once listed, browsers enforce HTTPS even on the first visit, and removal takes a long time to reach users.

Common mistakes

Starting at one year. Any mistake then lasts a year for every visitor.
includeSubDomains on the apex without an inventory. An HTTP-only subdomain becomes unreachable in browsers that visited the main site.
Expecting the header in development. The dev server is plain HTTP, so is_secure() is false and nothing is sent; that is correct behaviour, not a bug.
Setting the header at both proxy and Django. Django will not add a second one if a view set it, but a proxy may add another after Django; choose one layer.
Letting certificates lapse. Under HSTS, an expired certificate is a hard outage, not a warning users can bypass.

Verifying in tests

The test client can simulate an HTTPS request with secure=True, which makes is_secure() true without any proxy header:

python

from django.test import TestCase, override_settings


@override_settings(SECURE_HSTS_SECONDS=3600)
class HstsTests(TestCase):
    def test_sent_on_https_only(self):
        secure = self.client.get("/", secure=True)
        self.assertEqual(secure.headers["Strict-Transport-Security"], "max-age=3600")
        plain = self.client.get("/")
        self.assertNotIn("Strict-Transport-Security", plain.headers)

This confirms the exact header string each stage of the rollout will send, and that plain-HTTP responses stay without it.

Where it fits

HSTS complements, not replaces, the HTTPS redirect. The redirect handles a user's very first visit (unless preloaded); HSTS makes the browser skip plain HTTP afterwards. Cookie-level Secure flags are configured separately.

## What HSTS is **HTTP Strict Transport Security (HSTS)** is a response header, `Strict-Transport-Security`, that tells a browser: for the next `max-age` seconds, only ever connect to this host over HTTPS. After seeing it, the browser rewrites `http://` links to `https://` before sending anything, which defeats attacks that intercept the first plain-HTTP request and keep the victim on HTTP. Browsers that honour it also refuse to let users bypass certificate errors for that host. ## How Django sends it `SecurityMiddleware.process_response()` adds the header when: 1. `SECURE_HSTS_SECONDS` is non-zero (the default is `0`, meaning off); 2. `request.is_secure()` is true; 3. the response does not already have a `Strict-Transport-Security` header. The value is built from three settings: | Setting | Default | Adds | |---|---|---| | `SECURE_HSTS_SECONDS` | `0` | `max-age=<seconds>` | | `SECURE_HSTS_INCLUDE_SUBDOMAINS` | `False` | `; includeSubDomains` | | `SECURE_HSTS_PRELOAD` | `False` | `; preload` | The two flags have no effect while `SECURE_HSTS_SECONDS` is `0`. Because the header is added only to secure requests, a Django app behind a TLS-terminating proxy without `SECURE_PROXY_SSL_HEADER` never sends it; Django's own documentation calls out this symptom. ## Why it can lock users out HSTS is enforced by the **browser**, and the browser remembers it. If you later need plain HTTP (a certificate lapses, a subdomain is HTTP-only, a staging host shares the domain), every browser that saw the header refuses to connect for the rest of `max-age`, and users cannot click through the warning. You cannot recall the header; you can only send `max-age=0` over HTTPS to browsers that come back. ## A staged rollout 1. **Prepare.** Serve everything over HTTPS, including assets and redirects; turn on `SECURE_SSL_REDIRECT` or redirect at the edge. 2. **Short trial.** `SECURE_HSTS_SECONDS = 3600`. Django's documentation suggests one hour for testing. 3. **Observe.** Check that nothing on the site, including embedded resources and other hosts you link to under the same name, needs plain HTTP. 4. **Long max-age.** Raise to `31536000` (one year), a common production value, so infrequent visitors stay protected. 5. **Subdomains.** Inventory every subdomain (intranet tools, mail-related hosts, legacy apps). Only when all serve HTTPS, set `SECURE_HSTS_INCLUDE_SUBDOMAINS = True`. 6. **Preload, optionally.** `SECURE_HSTS_PRELOAD = True` only adds the `preload` directive; getting into browsers' built-in lists is a separate submission to the list maintainers. Once listed, browsers enforce HTTPS even on the first visit, and removal takes a long time to reach users. ## Common mistakes - **Starting at one year.** Any mistake then lasts a year for every visitor. - **includeSubDomains on the apex without an inventory.** An HTTP-only subdomain becomes unreachable in browsers that visited the main site. - **Expecting the header in development.** The dev server is plain HTTP, so `is_secure()` is false and nothing is sent; that is correct behaviour, not a bug. - **Setting the header at both proxy and Django.** Django will not add a second one if a view set it, but a proxy may add another after Django; choose one layer. - **Letting certificates lapse.** Under HSTS, an expired certificate is a hard outage, not a warning users can bypass. ## Verifying in tests The test client can simulate an HTTPS request with `secure=True`, which makes `is_secure()` true without any proxy header: ```python from django.test import TestCase, override_settings @override_settings(SECURE_HSTS_SECONDS=3600) class HstsTests(TestCase): def test_sent_on_https_only(self): secure = self.client.get("/", secure=True) self.assertEqual(secure.headers["Strict-Transport-Security"], "max-age=3600") plain = self.client.get("/") self.assertNotIn("Strict-Transport-Security", plain.headers) ``` This confirms the exact header string each stage of the rollout will send, and that plain-HTTP responses stay without it. ## Where it fits HSTS complements, not replaces, the HTTPS redirect. The redirect handles a user's very first visit (unless preloaded); HSTS makes the browser skip plain HTTP afterwards. Cookie-level `Secure` flags are configured separately.

Your production responses have no Strict-Transport-Security header even though SECURE_HSTS_SECONDS is set. What do you check?
First whether Django considers the request secure. `SecurityMiddleware` adds HSTS only when `request.is_secure()` is true, so behind a TLS-terminating proxy you need a correct `SECURE_PROXY_SSL_HEADER`. Then check that `SecurityMiddleware` is in `MIDDLEWARE` and that nothing strips the header after Django.
How do you back out HSTS if you must serve a host over plain HTTP again?
Send `Strict-Transport-Security: max-age=0` over HTTPS, for example by setting `SECURE_HSTS_SECONDS` to a tiny value and removing the flags. Only browsers that revisit over HTTPS learn it; others keep enforcing until their stored max-age expires, which is why the rollout starts short.

HSTS is like telling the post office to forward all your mail by registered delivery for a year: it protects you from interception, but if you move to an address that cannot sign for parcels, you cannot cancel the instruction until the year runs out.

saying these in an interview costs you the question

SecurityMiddleware sends HSTS on every response, HTTP included.
SECURE_HSTS_PRELOAD = True adds the site to browser preload lists.
HSTS can be switched off instantly by removing the setting.
includeSubDomains is safe to add before auditing subdomains.
Starting with a one-year max-age is fine because HSTS is easy to undo.

In Django, how do you roll out HSTS with SECURE_HSTS_SECONDS, SECURE_HSTS_INCLUDE_SUBDOMAINS and SECURE_HSTS_PRELOAD without locking users out?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~3 min

What HSTS is

How Django sends it

Why it can lock users out

A staged rollout

Common mistakes

Verifying in tests

Where it fits

▾common follow-ups2 questions

▾analogy~20 s

▾red flags5 flags

What HSTS is

How Django sends it

Why it can lock users out

A staged rollout

Common mistakes

Verifying in tests

Where it fits

answer

go deeper