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:
| Verfahren | Erkennbar an | Bewertung |
|---|---|---|
| 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äfix | nur 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
AuthNameist der Bereichsname. Manche Browser zeigen ihn im Anmeldefenster an.AuthUserFilebraucht den absoluten Pfad im Dateisystem – nicht die URL und nicht einen Pfad relativ zur.htaccess. Ein relativer Pfad wird relativ zumServerRootvon Apache aufgelöst und führt fast immer ins Leere.Require valid-userlässt jeden Benutzer aus der Datei herein. MitRequire user redaktionbeschrä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.htpasswdoder 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 .htpasswdfunktioniert nicht. Verwenden Sie den vollständigen Pfad ab/. - Keine Passwortabfrage: Ist für das Verzeichnis
AllowOverride Nonegesetzt, ignoriert Apache die.htaccessvollständig – die Seite bleibt offen. Nötig ist mindestensAllowOverride AuthConfig. - Datei im Webroot: Prüfen Sie, ob
https://ihre-domain.de/.htpasswderreichbar 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 640und 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.
.htpasswdaußerhalb des Webroots ablegen und mit absolutem Pfad einbinden.- Apache:
AuthType Basic,AuthName,AuthUserFile,Require valid-user. nginx:auth_basicundauth_basic_user_file. - Beim Livegang den Schutz auf der Live-Domain entfernen, auf der Staging-Umgebung dagegen beibehalten.
Tools zum Thema
- .htpasswd-Generator .htpasswd-Dateien mit bcrypt, APR1-MD5 oder SHA-1 erzeugen und prüfen – mit fertiger Konfiguration für Apache und nginx, ohne Übertragung.
- Passwort-Generator Sichere Passwörter und Passphrasen kostenlos erzeugen – direkt im Browser, ohne Übertragung.
- Hash-Generator MD5, SHA-1, SHA-256, SHA-512 und CRC32 für Texte und Dateien berechnen, HMAC erzeugen und Prüfsummen vergleichen – ohne Upload.
Weitere Anleitungen
- Sonderzeichen im Datenbank-Passwort Warum @, :, / oder # im Passwort die DATABASE_URL zerbrechen und wie Sie das Passwort richtig kodieren – für Symfony, Laravel, Doctrine und Docker.
- Weiterleitungen beim Website-Relaunch So planen Sie 301-Weiterleitungen für einen Relaunch: alte Adressen sammeln, Ziele zuordnen, Ketten vermeiden und das Ergebnis prüfen.
- Welche Favicons braucht eine Website? Welche Favicon-Dateien und Größen eine Website heute wirklich braucht – favicon.ico, SVG, Apple-Touch-Icon und Web-Manifest – samt HTML-Code.
- Bilder fürs Web optimieren Bilder richtig verkleinern und komprimieren: passende Größen, WebP, AVIF oder JPEG, Qualität, responsive Bilder und Lazy Loading.
- Barrierefreie Farben: Kontrast nach WCAG Was das Kontrastverhältnis nach WCAG bedeutet, welche Werte für Text und Bedienelemente gelten und wie Sie zu schwache Farben korrigieren.
- UUID v4, v7 oder ULID als Primärschlüssel? Wann sich UUIDs als Primärschlüssel lohnen, warum v7 und ULID für Datenbanken besser sind als v4 und wie Sie sie speichern.
- JWT sicher verwenden Typische Sicherheitsfehler mit JSON Web Tokens und wie Sie sie vermeiden: alg none, schwache Schlüssel, fehlende Prüfungen und Speicherort.