beginnerintermediateadvanced

Django · Settings and Configuration

Security settings

Concepts: 2

SECRET_KEY, DEBUG, host validation, cookie security, and the HTTPS/HSTS/reverse-proxy settings that only matter once real traffic is involved.

This section

Django Tutorial 1 - Project Settings and Configuration - Hacked ExistenceHackedExistence

Cookies and host validation

The settings that guard against a forged Host header, a leaked signing key, or a stolen session cookie.

coreintermediate

SECRET_KEY signs sessions and tokens and must stay secret; DEBUG must be False in production; ALLOWED_HOSTS/CSRF_TRUSTED_ORIGINS reject requests claiming the wrong host; the SESSION_COOKIE_*/CSRF_COOKIE_* settings control how those two cookies can be read, sent, and reused cross-site.

Think of it as

SECRET_KEY is the master signature Django stamps on every session and CSRF token — leak it, and an attacker can forge both. DEBUG is a door left open for developers to see full stack traces, deliberately propped shut in production. ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS are guest lists checked before a request is trusted at all; the SESSION_COOKIE_*/CSRF_COOKIE_* pairs are the fine print on the cookies themselves — who can read them (HTTPONLY), when they're sent (SECURE, SAMESITE).

python

import os

SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
DEBUG = os.environ.get("DJANGO_DEBUG", "False") == "True"
ALLOWED_HOSTS = os.environ.get("DJANGO_ALLOWED_HOSTS", "").split(",")

What we're doing: Configure ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS together for a production site served over HTTPS behind a real domain.

settings/production.pypython

ALLOWED_HOSTS = ["example.com", "www.example.com"]
CSRF_TRUSTED_ORIGINS = ["https://example.com", "https://www.example.com"]

SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True

1: ALLOWED_HOSTS checks the Host header on every request — a mismatch returns a 400 before any view runs.
2: CSRF_TRUSTED_ORIGINS is separate and requires a full scheme (https://) — it governs which Origin/Referer a POST is trusted from, not which Host is served.

Why this works: ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS solve two different attacks — Host header injection (cache poisoning, password-reset link poisoning) and cross-site request forgery — and Django deliberately keeps them as separate settings rather than inferring one from the other, since a legitimate reverse-proxy setup can need different values for each.

Setting DEBUG = False without ever configuring ALLOWED_HOSTS

Wrong

python

DEBUG = False
# ALLOWED_HOSTS left at the default []

Better

python

DEBUG = False
ALLOWED_HOSTS = ["example.com", "www.example.com"]

What you see: Every single request returns "Bad Request (400)" — the site appears completely down, with no view ever running.

Why: ALLOWED_HOSTS defaults to an empty list, and Django enforces the check specifically when DEBUG is False (as a safety net, since DEBUG = True skips it) — an empty list matches nothing, so every request's Host header fails validation before routing even starts.

Fails open vs. fails closed

SECRET_KEY / DEBUG

fail OPEN toward insecurity if forgotten

ALLOWED_HOSTS

fails CLOSED — empty means every request 400s

SECRET_KEY, DEBUG, host, and cookie security settings

SECRET_KEY, DEBUG, host, and cookie security settings
Setting	Default	Controls
SECRET_KEY	"" (must be set)	signs sessions, CSRF tokens, password reset links
DEBUG	False	verbose error pages with full tracebacks — never True in production
ALLOWED_HOSTS	[] (empty list)	which Host headers Django accepts requests for
CSRF_TRUSTED_ORIGINS	[] (empty list)	origins trusted for unsafe (POST) cross-origin requests
SESSION_COOKIE_SECURE	False	session cookie only sent over HTTPS when True
CSRF_COOKIE_SECURE	False	CSRF cookie only sent over HTTPS when True
SESSION_COOKIE_HTTPONLY	True	blocks JavaScript from reading the session cookie
SESSION_COOKIE_SAMESITE	"Lax"	whether the session cookie is sent on cross-site requests
CSRF_COOKIE_SAMESITE	"Lax"	whether the CSRF cookie is sent on cross-site requests

Together

python

ALLOWED_HOSTS = ["example.com", "www.example.com"]
CSRF_TRUSTED_ORIGINS = ["https://example.com"]
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True

Remember: SECRET_KEY must never be committed and DEBUG must be False in production — both fail open toward insecurity if forgotten, unlike ALLOWED_HOSTS, which fails closed (400s everything) if left empty.

HTTPS and reverse proxies

Forcing HTTPS, committing to it via HSTS, and the one setting that requires trusting infrastructure outside Django.

HTTPS redirect, HSTS, and proxy settings

coreadvanced

SECURE_SSL_REDIRECT forces every HTTP request to HTTPS; SECURE_HSTS_SECONDS tells browsers to skip HTTP entirely for future visits; SECURE_PROXY_SSL_HEADER tells Django to trust a proxy header for "was this HTTPS" — and is dangerous if the proxy doesn't strip that header from untrusted clients first.

Think of it as

SECURE_SSL_REDIRECT is a doorman turning away anyone who didn't arrive over HTTPS. SECURE_HSTS_SECONDS goes further — it hands returning visitors' browsers a standing instruction ("never even try HTTP here again") for the given duration. SECURE_PROXY_SSL_HEADER is different in kind: it doesn't enforce anything, it tells Django to believe a header the proxy sets — which is only safe if the proxy guarantees no outside client can set that same header itself.

python

# only if the reverse proxy is verified to strip this header from clients
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")

What we're doing: Roll out HSTS safely — starting with a short duration before committing to the full year-long, preload-eligible configuration.

settings/production.pypython

SECURE_HSTS_SECONDS = 3600  # 1 hour — confirm nothing breaks first

# once confirmed working over several deploys:
# SECURE_HSTS_SECONDS = 31536000  # 1 year
# SECURE_HSTS_INCLUDE_SUBDOMAINS = True
# SECURE_HSTS_PRELOAD = True

1: A short duration limits the damage window if HTTPS turns out to be misconfigured — browsers that already received the header will refuse plain HTTP for that long, no way to undo it early.

Why this works: SECURE_HSTS_SECONDS is a one-way commitment for however many seconds it specifies — once a browser receives the header, it will not attempt HTTP again until that duration elapses, even if the site's HTTPS setup breaks in the meantime. Starting short and raising it only after confirming HTTPS works reliably avoids locking out real visitors from a misconfigured production rollout.

Setting SECURE_PROXY_SSL_HEADER without the proxy stripping client-supplied X-Forwarded-Proto

Wrong

python

SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
# but the reverse proxy passes through any X-Forwarded-Proto
# a client sends, instead of overwriting it

Better

python

# nginx.conf (or equivalent) — always overwrite, never pass through
# proxy_set_header X-Forwarded-Proto $scheme;

# settings.py — now safe, since the proxy guarantees the header's value
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")

What you see: request.is_secure() returns True for a request that was actually plain HTTP end-to-end, if a client simply sends its own X-Forwarded-Proto: https header — silently defeating CSRF cookie security and any code branching on is_secure().

Why: Django trusts SECURE_PROXY_SSL_HEADER completely once set — it has no way to tell a proxy-set value of X-Forwarded-Proto from a client-forged one. The setting is only safe when the reverse proxy is configured to unconditionally overwrite that header on every request it forwards, never merely add to whatever a client already sent.

Enforcement vs. trust

SECURE_SSL_REDIRECT / HSTS

+Django itself enforces HTTPS
+HSTS tells browsers to skip HTTP next time
+A one-way commitment for its duration

SECURE_PROXY_SSL_HEADER

−Django trusts a header, enforces nothing
−Safe only if the proxy strictly overwrites it
−Wrong config lets a client fake "was HTTPS"

HTTPS redirect, HSTS, and proxy settings

HTTPS redirect, HSTS, and proxy settings
Setting	Default	Controls
SECURE_SSL_REDIRECT	False	redirects every HTTP request to HTTPS when True
SECURE_HSTS_SECONDS	0	seconds browsers should remember to only use HTTPS
SECURE_HSTS_INCLUDE_SUBDOMAINS	False	extends the HSTS policy to all subdomains
SECURE_HSTS_PRELOAD	False	allows submission to browsers' built-in HSTS preload list
SECURE_PROXY_SSL_HEADER	None	which proxy header/value Django trusts as "this was HTTPS"

Together

python

SECURE_SSL_REDIRECT = True
SECURE_HSTS_SECONDS = 3600  # start short; raise once confirmed
SECURE_HSTS_INCLUDE_SUBDOMAINS = True

Remember: SECURE_SSL_REDIRECT/HSTS settings enforce HTTPS going forward; SECURE_PROXY_SSL_HEADER is different — it makes Django trust a header, safe only if the proxy strictly overwrites it for every request.