HSTS mit Nginx einführen und prüfen

Zuerst Version und Antwortweg klären

Nginx setzt HSTS über add_header. Der Browser verarbeitet die Richtlinie nach Empfang über gültiges HTTPS. Eine bereits bekannte Richtlinie kann anschließend den unverschlüsselten HTTP-Einstieg zum erfassten Host verhindern. Die HSTS-Grundlagen erklären Erstkontakt, Hostbezug und Subdomains.

Ermitteln Sie vor einer Änderung:

• die eingesetzte Nginx-Version, beispielsweise mit nginx -v;
• den HTTPS-server-Block und die eingebundenen Konfigurationsdateien;
• vorhandene add_header-Regeln in http, server und den relevanten location-Blöcken;
• einen vorgeschalteten CDN- oder Proxy-Dienst und die Stelle, an der die HTTPS-Verbindung des Browsers endet;
• die betroffenen Hosts, etwa example.com und www.example.com, sowie mögliche übergeordnete HSTS- oder Preload-Richtlinien.

Die Versionsangaben unten bezeichnen die dokumentierte Verfügbarkeit einzelner Direktiven. Sie sind keine Empfehlung, alte Nginx-Versionen weiterzubetreiben. Nginx: Kommandozeilenparameter, Header-Modul

Browser, CDN und Nginx haben unterschiedliche Rollen

Das ist ein schematischer Aufbau, keine Bestandsaufnahme Ihrer Website. Ohne vorgeschaltete Ebene verbindet sich der Browser direkt mit Nginx. Legen Sie für jede relevante Antwort fest, welche Ebene den HSTS-Header setzt. Nginx: Proxy-Modul

Mit einer kurzen HSTS-Richtlinie beginnen

HSTS setzt funktionierendes HTTPS und eine verlässliche Zertifikatserneuerung voraus. Ergänzen Sie die folgende Direktive im bereits funktionierenden HTTPS-server-Block für den betreffenden Host:

add_header Strict-Transport-Security "max-age=300" always;

Die 300 Sekunden entsprechen 5 Minuten. Dieser Einstieg enthält weder includeSubDomains noch preload. Ein kurzer Wert begrenzt die Bindung neu gelernter Richtlinien; er verkürzt keine älteren Einträge in Browsern, die den neuen Header noch nicht empfangen haben. Die Direktive ist ein Ausschnitt, keine vollständige Webserverkonfiguration.

always wird seit Nginx 1.7.5 unterstützt. Ohne diesen Parameter fügt add_header den Header nur bei den dokumentierten Statuscodes hinzu. Mit always gilt die Direktive unabhängig vom Antwortstatus, also auch bei passenden 4xx- oder 5xx-Antworten. Das löst aber weder ein Vererbungsproblem noch fügt es einen Header zu einer Antwort hinzu, die eine andere Ebene unabhängig von Nginx erzeugt. Nginx: add_header

HTTP zu HTTPS weiterleiten

Falls Sie HTTP auf Port 80 anbieten, richten Sie eine Weiterleitung ein. Das folgende Beispiel betrifft nur example.com und setzt voraus, dass derselbe Host unter HTTPS funktioniert:

server {
    listen 80;
    server_name example.com;
    return 301 https://example.com$request_uri;
}

Ersetzen Sie den Beispielhost bewusst und behandeln Sie weitere Hosts separat. Ein Wechsel von der Basisdomain zu www ist eine zusätzliche Weiterleitung; für eine spätere Preload-Einreichung muss der HTTP-zu-HTTPS-Schritt zunächst auf demselben Host erfolgen. Senden Sie den HSTS-Header über HTTPS; Browser ignorieren ihn über unverschlüsseltes HTTP. Preload-Anforderungen, RFC 6797, Abschnitt 8.1

TLS bleibt eine eigene Konfiguration

HSTS wählt keine TLS-Version und keinen Cipher aus. TLS 1.0 und 1.1 sind durch RFC 8996 abgelöst; die Auswahl moderner TLS-Versionen gehört zur Transportkonfiguration. Für einen entsprechend unterstützten Nginx-/TLS-Build lautet die Direktive beispielsweise:

ssl_protocols TLSv1.2 TLSv1.3;

Das ist keine vollständige TLS-Härtung. Prüfen Sie Buildunterstützung, Zertifikate und die übrigen TLS-Einstellungen gesondert. HTTP/2 ist keine Voraussetzung für HSTS; eine zusätzliche http2 on-Direktive gehört deshalb nicht in dieses minimale HSTS-Beispiel. Nginx: ssl_protocols, RFC 8996, RFC 9325, Abschnitt 3.1

Headervererbung nach Nginx-Version prüfen

Im Standardmodell erbt ein untergeordneter Konfigurationskontext die add_header-Direktiven der höheren Ebene nur dann, wenn er selbst keine add_header-Direktive enthält. Schon eine Regel für einen anderen Header kann daher die geerbte HSTS-Regel verdrängen. always ändert diese Vererbung nicht. Nginx: Headervererbung

Angenommen, im HTTPS-server-Block steht die HSTS-Direktive aus dem Einstieg. Eine vorhandene Unterkonfiguration enthält:

location /assets/ {
    add_header X-Content-Type-Options nosniff always;
}

Erwartung unter Standardvererbung: Diese eigene add_header-Regel unterbricht die Übernahme der HSTS-Regel aus dem server-Block. Das Beispiel illustriert das Problem; es ist keine Empfehlung, Ihre bisherige location-Konfiguration zu ersetzen.

Eine Lösung unter diesem Modell besteht darin, alle in diesem Kontext benötigten Header ausdrücklich zusammenzuführen. Für die beiden gezeigten Regeln sähe der Ausschnitt so aus:

location /assets/ {
    add_header Strict-Transport-Security "max-age=300" always;
    add_header X-Content-Type-Options nosniff always;
}

Behalten Sie dabei die tatsächlich benötigte Auslieferungslogik der vorhandenen location bei. Wenn Sie den HSTS-Wert an mehreren Stellen führen, müssen spätere Änderungen alle relevanten Stellen erreichen. Prüfen Sie auch Fehlerseiten und interne Weiterleitungen, die einen anderen Kontext verwenden können.

Ab Nginx 1.29.3: add_header_inherit

Seit 1.29.3 kann add_header_inherit die Vererbungsregeln ändern:

Ein möglicher Ausschnitt für einen unterstützten Build lautet:

add_header_inherit merge;

Die Einstellung kann sich ihrerseits in tiefere Kontexte vererben. Prüfen Sie deshalb die vollständige betroffene Hierarchie. Ergänzen Sie merge nicht blind zu einem Aufbau, der HSTS schon in jedem Unterkontext wiederholt: So können doppelte Header entstehen. Standardvererbung, ausdrückliche Wiederholung und merge wurden hier auf Nginx 1.30.5 ausgeführt. Die Verfügbarkeit seit 1.29.3 ist eine Herstellerangabe; ältere Nginx-Binaries wurden nicht ausgeführt. Nginx: add_header_inherit

Bei Reverse Proxy und CDN eine klare Zuständigkeit festlegen

Steht Nginx vor einer Anwendung, kann deren HSTS-Header bereits in der weitergereichten Antwort enthalten sein. add_header ist keine allgemeine Ersetzungsregel für einen gleichnamigen Upstream-Header. Wenn Nginx die Richtlinie bewusst zentral setzt, kann ein weitergereichter HSTS-Header im passenden Proxykontext unterdrückt werden:

proxy_hide_header Strict-Transport-Security;

Diese Direktive entfernt nur das angegebene Feld aus der weitergereichten Proxyantwort; sie setzt selbst keinen neuen HSTS-Header. Die eigene add_header-Regel und ihre Vererbung müssen weiterhin passen. Der Ausschnitt gilt für proxy_pass-Antworten; andere Upstream-Module oder CDN-Regeln sind gesondert zu behandeln. Nginx: proxy_hide_header

Prüfen Sie auf der browserseitigen Antwort, dass die vorgesehene Richtlinie eindeutig ankommt. Mehrere Strict-Transport-Security-Felder werden nicht zu einer stärksten Richtlinie zusammengerechnet; RFC 6797 schreibt die Verarbeitung des ersten Felds vor. Verlassen Sie sich daher nicht auf die Reihenfolge widersprüchlicher Header. RFC 6797, Abschnitt 8.1

Eine vorgeschaltete Ebene kann zusätzlich eigene Cache-, Redirect- oder Fehlerantworten liefern. Ein korrekt gesetzter Header am Origin belegt deren Inhalt nicht. Prüfen Sie die öffentlich verwendete Adresse und den bekannten Ursprung einer Antwort getrennt.

Konfiguration laden und Antworten vergleichen

Prüfen Sie die geänderte Konfiguration zunächst in Ihrer isolierten Testumgebung. Vor einem Reload muss nginx -t erfolgreich sein. Auf einem System, dessen Nginx-Dienst über systemd verwaltet wird, können Syntaxprüfung und Reload so verknüpft werden:

sudo nginx -t && sudo systemctl reload nginx

Ein erfolgreicher Reload lädt die neue Konfiguration und lässt alte Worker bestehende Verbindungen geordnet abschließen. Verwaltet Ihr System den Dienst anders, verwenden Sie dessen vorgesehenen Reloadweg. Ein bestandener Syntaxtest beweist noch nicht, welcher Header über CDN, Proxy und Anwendung beim Browser ankommt. Nginx: Kontrolle und Reload

Prüfen Sie eine HTTPS-Antwort zunächst ohne automatisches Folgen von Weiterleitungen:

curl --silent --show-error --dump-header - --output /dev/null https://example.com/

Der Befehl verwendet einen GET-Aufruf, zeigt die Antwortheader und verwirft den Antwortkörper. Er schaltet die Zertifikatsprüfung nicht ab. Die Beispieladresse ersetzen Sie durch einen eigenen beziehungsweise autorisiert zu prüfenden Host. Suchen Sie in der vollständigen Ausgabe nach Status, Location und Strict-Transport-Security; prüfen Sie auch, ob derselbe Header mehrfach vorkommt. curl: Optionen

Für das Einstiegsbeispiel lautet die erwartete Headerzeile; genau dieser Wert erschien auch in der passenden lokalen HTTPS-Probe:

Strict-Transport-Security: max-age=300

Rufen Sie bei einer Weiterleitung das ausgewiesene Ziel anschließend getrennt auf. Notieren Sie für jeden Schritt den Host. Prüfen Sie HTTP separat, wenn dieser Dienst angeboten wird:

curl --silent --show-error --dump-header - --output /dev/null http://example.com/

Antwortmatrix für die eigene Prüfung

Die Tabelle ist eine Prüfvorlage für Ihre Umgebung. Die Statuscodes setzen die jeweils beschriebene Testantwort voraus. Die tatsächlichen Pfade müssen Sie aus Ihrer Anwendung wählen; Fehlerfälle absichtlich nur in einer isolierten Umgebung auslösen. Die getrennte lokale Probe darunter ersetzt diese Bestandsaufnahme nicht.

Tabelle: Prüfvorlage bei einer Anfangsrichtlinie mit max-age=300.

Die Matrix ist kein Vollständigkeitsnachweis. Ergänzen Sie weitere relevante Hosts, Pfade, Cachezustände und Antwortstellen. Ein Unterschied zwischen Erwartung und Antwort ist eine konkrete Frage an die Konfiguration, keine automatische Diagnose einer Sicherheitslücke.

Browserzustand und externe Werkzeuge ergänzend prüfen

In den Browser-Entwicklerwerkzeugen können Sie im Netzwerkbereich die tatsächlich aufgerufene URL und ihre Antwortheader ansehen. Ein dort sichtbarer Header zeigt diese Antwort, nicht sämtliche gespeicherten HSTS-Regeln des Browsers.

Browserinterne HSTS-Ansichten können beim Einordnen dynamischer und vorgeladener Regeln helfen; Verfügbarkeit und Bedienung hängen von der Version ab. hstspreload.org verweist für Chrome auf chrome://net-internals/#hsts. Ein einzelner Feldname oder eine lokale Löschung ist keine allgemeine Prüfung aller Besucherzustände. HSTS Preload: Status

Der SSL Labs Server Test ist ein ergänzendes externes Werkzeug zur SSL-/TLS-Analyse. Sein Ergebnis ersetzt weder diese Antwortmatrix noch eine Bestandsaufnahme aller Subdomains.

Gemessene Antworten im lokalen Nginx-Labor

Die folgenden Befunde stammen aus 48 eigenen HTTP-Abrufen über sechs getrennte Konfigurationen von Nginx 1.30.5. Nginx und ein synthetischer Upstream lauschten ausschließlich auf Loopback-Ports. Für HTTPS vertraute der Testclient gezielt einer eigenen eintägigen CA und prüfte den Zertifikatsnamen. Es gab weder eine globale TLS-Ausnahme noch einen Eintrag im System-Truststore.

Gemessen wurde die HTTP-Antwort, nicht das Lernen einer HSTS-Richtlinie im Browser. Gerade eine Loopback-IP ist kein geeigneter Beleg für einen Browser-HSTS-Eintrag. Auch eigenständige CDN-Fehlerseiten, echte Zertifikatserneuerung und Ihre konkrete Anwendung bleiben außerhalb dieser Probe. Übertragen Sie deshalb die passende Regel und die Prüfmethode, nicht einen behaupteten Gesamterfolg.

Speicherdauer erhöhen und Preload getrennt entscheiden

Nach erfolgreicher Prüfung können Sie die Speicherdauer schrittweise erhöhen, beispielsweise von max-age=300 auf max-age=604800 und später max-age=2592000. Das sind 5 Minuten, 1 Woche und 30 Tage. Beobachten Sie die betroffenen Webangebote und warten Sie vor der nächsten Erhöhung mindestens die bisherige Dauer ab. Ein späterer Wert wie max-age=31536000 bindet neu empfangende Browser für 365 Tage. Empfehlungen zur Einführung

includeSubDomains kommt erst nach einer eigenen Bestandsprüfung infrage. Es erfasst untergeordnete Hosts, auch intern genutzte Webangebote. Ein Header auf www.example.com erweitert die Richtlinie nicht auf example.com oder benachbarte Hosts.

Preload ist kein obligatorischer Abschlussschritt. hstspreload.org empfiehlt es heute nicht allgemein. Falls Sie sich bewusst dafür entscheiden, müssen ein gültiges Zertifikat, HTTPS für alle betroffenen Subdomains und ein HSTS-Header auf der Basisdomain mit mindestens max-age=31536000, includeSubDomains und preload vorliegen. Bei offenem Port 80 muss HTTP zunächst zu HTTPS desselben Hosts führen; eine weitere HTTPS-Weiterleitung muss selbst den Header tragen. Die Einreichung und die spätere Verteilung an Browser sind getrennt vom Setzen des Headers. Preload-Anforderungen und Einordnung

Rücknahme: heutige Antwort ist nicht jeder Browserzustand

Das Bearbeiten der Nginx-Datei allein ändert keine ausgelieferten Antworten. Erst nach einem erfolgreichen Reload wird die geänderte Konfiguration aktiv; bisherige Worker können bestehende Verbindungen noch mit der alten Konfiguration abschließen. Browser müssen einen neuen Header empfangen, bevor sich ihr dynamischer Eintrag entsprechend ändert. Ein über gültiges HTTPS empfangenes max-age=0 kann diesen Eintrag löschen. Eine übergeordnete includeSubDomains-Richtlinie oder ein weiterhin vorhandener Preload-Eintrag kann trotzdem gelten.

Scheitert die TLS-Verbindung, kann der Browser die Löschanweisung nicht über gültiges HTTPS empfangen. Ein fehlender Header entfernt die gespeicherte Richtlinie ebenfalls nicht. Eine Preload-Entfernung benötigt einen eigenen Vorgang und die Verteilung an Browser; eine allgemeine Frist lässt sich dafür nicht versprechen. RFC 6797, Abschnitt 8, Preload-Entfernung

Eine nachvollziehbare Betriebsübergabe erstellen

Halten Sie fest, welche Nginx-Version und Konfigurationsstellen geprüft wurden, welche Hosts und Pfade die Matrix abdeckt und wo CDN oder Proxy eigene Antworten erzeugen. Ergänzen Sie Messzeitpunkt, empfangene Header, offene Subdomains, Zertifikatszuständigkeit und die letzte funktionierende Konfiguration.

Benennen Sie einen konkreten Anlass für die nächste Prüfung: etwa Änderungen an location-Blöcken, Fehlerseiten, Proxyregeln oder der HSTS-Reichweite. Ein einzelner Headerbefund kann bereits genügen, um eine Abweichung zu klären. Er belegt keine vollständige TLS-Sicherheit, keinen Angriffsschutz für die ganze Website und keine regulatorische Konformität.

Passende nächste Schritte

Der Web Security Check kann öffentlich erreichbare Konfigurationsmerkmale untersuchen. Verwenden Sie den begrenzten Befund als Ausgangspunkt für eine konkrete Prüfung; er ersetzt keine vollständige Matrix Ihrer Antwortpfade.