# 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.

Website: https://skriptbox.com/de/anleitungen/verzeichnis-mit-passwort-schuetzen

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](https://www.rfc-editor.org/rfc/rfc7617). 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](https://skriptbox.com/de/tools/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](https://skriptbox.com/de/tools/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](https://skriptbox.com/de/tools/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](https://httpd.apache.org/docs/2.4/howto/auth.html).

### 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](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html) 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

- [.htpasswd-Generator](https://skriptbox.com/de/tools/htpasswd-generator.md) – .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](https://skriptbox.com/de/tools/passwort-generator.md) – Sichere Passwörter und Passphrasen kostenlos erzeugen – direkt im Browser, ohne Übertragung.
- [Hash-Generator](https://skriptbox.com/de/tools/hash-generator.md) – MD5, SHA-1, SHA-256, SHA-512 und CRC32 für Texte und Dateien berechnen, HMAC erzeugen und Prüfsummen vergleichen – ohne Upload.
