Verzeichnis mit Passwort schützen (.htpasswd)

Ein Verzeichnis oder eine Staging-Seite mit .htaccess und .htpasswd schützen – für Apache und nginx, mit sicheren Hash-Verfahren.

Eine Staging-Version kurz vor dem Livegang, ein Vorschau-Link für Kunden oder ein Verwaltungsbereich ohne eigenes Login: Oft soll ein Verzeichnis nicht öffentlich sein, ein komplettes Benutzerkonzept wäre aber übertrieben. Dafür ist der Passwortschutz per .htpasswd gedacht. Der Webserver fragt Benutzername und Passwort ab, bevor er überhaupt eine Datei ausliefert – unabhängig davon, ob dahinter WordPress, eine Symfony-Anwendung oder statisches HTML steckt.

Diese Anleitung erklärt, wie das Verfahren funktioniert, welches Hash-Verfahren Sie verwenden sollten und wie Sie den Schutz in Apache und nginx einrichten. Am Ende finden Sie die häufigsten Fehler und ihre Ursachen.

So funktioniert der Passwortschutz

Technisch steckt dahinter die HTTP-Authentifizierung „Basic“, beschrieben in RFC 7617. Ruft jemand eine geschützte Adresse auf, antwortet der Server mit dem Status 401 und der Browser zeigt sein Anmeldefenster. Danach schickt der Browser bei jeder Anfrage den Header Authorization: Basic … mit Benutzername und Passwort mit.

Diese Angaben sind nur Base64-kodiert, nicht verschlüsselt. Jeder, der die Verbindung mitlesen kann, kann sie zurückverwandeln. Basic Auth ist deshalb nur über HTTPS sicher. Leiten Sie http:// grundsätzlich auf https:// um, bevor der Passwortschutz greift.

Zwei Eigenschaften sollten Sie kennen: Es gibt keine Abmeldung – der Browser merkt sich die Zugangsdaten, bis er geschlossen wird. Und es gibt keinen Schutz vor vielen Fehlversuchen. Ein langes, zufälliges Passwort ist deshalb Pflicht, nicht Kür. Der Passwort-Generator erzeugt eines direkt im Browser.

Ein angenehmer Nebeneffekt: Suchmaschinen erhalten ebenfalls den Status 401 und nehmen die Seiten nicht in den Index auf. Für Staging-Umgebungen ist das genau richtig und zuverlässiger als eine robots.txt, die nur eine Bitte ist.

Die Datei .htpasswd und die Hash-Verfahren

Die Datei .htpasswd enthält pro Zeile einen Benutzer, getrennt durch einen Doppelpunkt vom Hash seines Passworts:

redaktion:$2y$10$5LcRexEgEbk0lj2fRj9K2O/e00pwcsJ0WxjfBBlO7rbP1ZilFpnra
kunde:$apr1$KO67C8Af$SnLrrzsUIDD7LXpbSvoMG.

Am Anfang des Hashes erkennt der Server das Verfahren:

VerfahrenErkennbar anBewertung
bcrypt$2y$empfohlen; Apache ab 2.4.4, nginx abhängig vom System
APR1-MD5$apr1$kompatibel mit Apache und nginx, aber veraltet
SHA-1{SHA}ohne Salt, nicht mehr verwenden
crypt (DES)13 Zeichen ohne Präfixnur die ersten 8 Zeichen zählen, nicht mehr verwenden
Klartext–Apache nur unter Windows, nginx mit {PLAIN}; vermeiden

Wie schwach SHA-1 hier ist, lässt sich nachvollziehen: Berechnen Sie im Hash-Generator den SHA-1-Wert eines Passworts mit der Ausgabe Base64, erhalten Sie genau den Wert hinter {SHA}. Gleiche Passwörter ergeben also immer gleiche Hashes, und solche Prüfsummen lassen sich in großer Zahl in kurzer Zeit durchprobieren. bcrypt dagegen verwendet für jedes Passwort ein eigenes Salt und ist absichtlich langsam.

Die Zahl nach $2y$ ist der Kostenfaktor. Jede Stufe verdoppelt den Rechenaufwand. Weil der Server das Passwort bei jeder Anfrage prüft – auch für jedes Bild und jede CSS-Datei –, ist ein sehr hoher Wert spürbar. 10 ist ein guter Mittelweg.

Den Eintrag erzeugen Sie mit dem .htpasswd-Generator, der bcrypt, APR1-MD5 und SHA-1 beherrscht und passende Konfigurations-Schnipsel gleich mitliefert. Auf der Kommandozeile geht es mit dem Programm htpasswd aus dem Apache-Paket:

# neue Datei anlegen (-c überschreibt eine vorhandene Datei!)
htpasswd -c -B -C 10 /var/www/kunde/.htpasswd redaktion

# weiteren Benutzer hinzufügen oder Passwort ändern
htpasswd -B -C 10 /var/www/kunde/.htpasswd kunde

# Benutzer löschen bzw. Passwort prüfen
htpasswd -D /var/www/kunde/.htpasswd kunde
htpasswd -v /var/www/kunde/.htpasswd redaktion

-B wählt bcrypt, -C den Kostenfaktor. Ohne -C verwendet htpasswd den niedrigen Standardwert 5.

Apache: Schutz per .htaccess

Legen Sie in das zu schützende Verzeichnis eine Datei .htaccess mit diesem Inhalt:

AuthType Basic
AuthName "Staging"
AuthUserFile /var/www/kunde/.htpasswd
Require valid-user
  • AuthName ist der Bereichsname. Manche Browser zeigen ihn im Anmeldefenster an.
  • AuthUserFile braucht den absoluten Pfad im Dateisystem – nicht die URL und nicht einen Pfad relativ zur .htaccess. Ein relativer Pfad wird relativ zum ServerRoot von Apache aufgelöst und führt fast immer ins Leere.
  • Require valid-user lässt jeden Benutzer aus der Datei herein. Mit Require user redaktion beschränken Sie den Zugang auf bestimmte Namen.

Legen Sie die .htpasswd möglichst außerhalb des Webroots ab, also in einem Verzeichnis, das nicht per URL erreichbar ist. In den Beispielen liegt die Website in /var/www/kunde/public, die .htpasswd eine Ebene darüber. Apache sperrt Dateien, die mit .ht beginnen, zwar in der Standardkonfiguration, darauf sollten Sie sich aber nicht verlassen. Den absoluten Pfad finden Sie bei Shared Hosting in der Verwaltungsoberfläche des Hosters. Wenn nicht, hilft eine kurzzeitig hochgeladene PHP-Datei mit <?php echo __DIR__; – löschen Sie sie danach wieder.

Wenn Sie Zugriff auf die Serverkonfiguration haben, gehören dieselben Anweisungen besser in einen <Directory>-Block. Das ist schneller, und die .htaccess kann nicht versehentlich überschrieben werden. Die Einzelheiten beschreibt die Apache-Dokumentation zur Authentifizierung.

Nur einzelne Dateien schützen

Soll nur eine Datei geschützt sein, etwa eine Vorschau, umschließen Sie die Anweisungen mit <Files>:

<Files "vorschau.php">
    AuthType Basic
    AuthName "Vorschau"
    AuthUserFile /var/www/kunde/.htpasswd
    Require valid-user
</Files>

Ausnahmen für bestimmte IP-Adressen

Im Büro oder für ein Monitoring-System ist die Passwortabfrage oft lästig. Mit Apache 2.4 genügt dann eine der beiden Bedingungen:

AuthType Basic
AuthName "Staging"
AuthUserFile /var/www/kunde/.htpasswd
<RequireAny>
    Require ip 203.0.113.10
    Require ip 198.51.100.0/24
    Require valid-user
</RequireAny>

Steht der Server hinter einem Proxy oder CDN, sieht Apache unter Umständen nur dessen Adresse. Dann muss zuerst die echte Besucher-IP ermittelt werden, etwa mit mod_remoteip.

nginx: auth_basic

nginx liest keine .htaccess-Dateien. Der Schutz steht direkt in der Serverkonfiguration, im server- oder in einem location-Block:

location / {
    auth_basic           "Staging";
    auth_basic_user_file /etc/nginx/htpasswd/kunde;
}

# nur ein Verzeichnis, mit IP-Ausnahme
location /admin/ {
    satisfy any;
    allow 203.0.113.10;
    deny  all;
    auth_basic           "Verwaltung";
    auth_basic_user_file /etc/nginx/htpasswd/kunde;
}

Das Dateiformat ist dasselbe wie bei Apache. nginx versteht laut Dokumentation APR1-MD5, {SHA}, {SSHA} und {PLAIN} sowie alles, was die crypt()-Funktion des Betriebssystems kennt. Ob bcrypt funktioniert, hängt also vom System ab: Viele aktuelle Linux-Distributionen unterstützen es, verlassen sollten Sie sich darauf aber nicht. Testen Sie den Zugang nach dem Einrichten. Klappt bcrypt nicht, ist APR1-MD5 der kompatible Ausweg.

Wichtig: Anders als Apache sperrt nginx Dateien wie .htpasswd nicht von sich aus. Liegt die Datei im Webroot, kann sie jeder herunterladen. Bei nginx gehört sie deshalb immer außerhalb, zum Beispiel nach /etc/nginx/. Nach einer Änderung der Konfiguration prüfen Sie sie mit nginx -t und laden sie dann neu.

Typische Fehler

  • 500 Internal Server Error: Meist ein Tippfehler in der .htaccess, eine nicht vorhandene .htpasswd oder ein Pfad, den Apache nicht findet. Das Fehlerprotokoll des Servers nennt die genaue Ursache, etwa „Could not open password file“.
  • Relativer oder falscher Pfad: AuthUserFile .htpasswd funktioniert nicht. Verwenden Sie den vollständigen Pfad ab /.
  • Keine Passwortabfrage: Ist für das Verzeichnis AllowOverride None gesetzt, ignoriert Apache die .htaccess vollständig – die Seite bleibt offen. Nötig ist mindestens AllowOverride AuthConfig.
  • Datei im Webroot: Prüfen Sie, ob https://ihre-domain.de/.htpasswd erreichbar ist. Es sollte ein 403 oder 404 kommen, niemals der Inhalt.
  • Falsche Rechte: Der Webserver-Benutzer muss die Datei lesen können. Für alle anderen sollte sie nicht lesbar sein, etwa mit chmod 640 und der Gruppe des Webservers.
  • Login „funktioniert nicht“ oder bleibt bestehen: Der Browser merkt sich die Zugangsdaten. Testen Sie Änderungen in einem privaten Fenster. Auch ein Tippfehler im Benutzernamen führt zu abgelehnten Anmeldungen – Groß- und Kleinschreibung zählt.

Kurz zusammengefasst

  • Basic Auth nur über HTTPS einsetzen und ein langes, zufälliges Passwort verwenden.
  • bcrypt mit Kostenfaktor 10 wählen, bei Problemen unter nginx APR1-MD5.
  • .htpasswd außerhalb des Webroots ablegen und mit absolutem Pfad einbinden.
  • Apache: AuthType Basic, AuthName, AuthUserFile, Require valid-user. nginx: auth_basic und auth_basic_user_file.
  • Beim Livegang den Schutz auf der Live-Domain entfernen, auf der Staging-Umgebung dagegen beibehalten.

Tools zum Thema

Weitere Anleitungen