Skip to main content

NGINX Basic Auth mit htpasswd: Vollständige Konfigurationsanleitung

Dieser Artikel ist eine Übersetzung des englischen Originals.


Die NGINX-Basisauthentifizierung bietet eine einfache und dennoch effektive Möglichkeit, den Zugriff auf Ihre Webressourcen einzuschränken. Ob Sie eine Staging-Site schützen, ein Admin-Panel absichern oder eine zusätzliche Sicherheitsebene für sensible Bereiche hinzufügen möchten – das Verständnis der korrekten Konfiguration der nginx-htpasswd-Authentifizierung ist für jeden Systemadministrator unerlässlich.

In dieser umfassenden Anleitung erfahren Sie alles über die Implementierung von nginx Basic Auth – von der Erstellung von Passwortdateien mit htpasswd bis hin zu fortgeschrittenen Konfigurationen zum Schutz von WordPress-Admin-Bereichen und Staging-Umgebungen.

So funktioniert die NGINX-Basisauthentifizierung

Bevor Sie in die Konfiguration einsteigen, lohnt es sich zu verstehen, was im Hintergrund passiert. Wenn ein Client eine geschützte Ressource anfordert, prüft NGINX auf den Header Authorization. Fehlt dieser, gibt NGINX eine 401-Unathorized-Antwort mit dem Header WWW-Authenticate: Basic realm="Your Realm" zurück, wodurch der Browser aufgefordert wird, einen Anmeldedialog anzuzeigen.

Der Browser sendet die Anmeldedaten dann als Base64-kodierten username:password-String. NGINX dekodiert diesen und vergleicht den Passwort-Hash mit den Einträgen in Ihrer htpasswd-Datei.

Betrachtet man den NGINX-Quellcode (ngx_http_auth_basic_module.c), erfolgt die Authentifizierung in der Access-Phase – nach dem URL-Rewriting, aber vor der Inhaltsgenerierung. Dies ist wichtig, denn es bedeutet, dass die Authentifizierung unabhängig davon erzwungen wird, welcher Content-Handler die Anfrage verarbeitet. Weitere Informationen zur Übereinstimmung von Location-Blöcken finden Sie in unserer Anleitung zur NGINX-Location-Priorität.

Unterstützte Passwort-Hash-Formate

NGINX unterstützt mehrere Passwort-Hash-Formate über seine Funktion ngx_crypt():

Format Präfix Sicherheitsstufe Hinweise
APR1 MD5 $apr1$ Mittel Apache-kompatibel, 1000 Iterationen
bcrypt $2y$ Hoch CPU-intensiv, empfohlen
SHA-512 $6$ Hoch System-crypt, konfigurierbare Runden
SHA-256 $5$ Hoch System-crypt, konfigurierbare Runden
SHA-1 {SHA} Niedrig Veraltet, vermeiden
Plain {PLAIN} Keine T Nur für die Entwicklung

Der NGINX-Quellcode setzt Passwort-Puffer nach der Verwendung explizit auf Null (ngx_explicit_memzero), um die Offenlegung von Speicherinhalten zu verhindern – ein Detail, das zeigt, dass die Entwickler Sicherheit ernst nehmen.

Installation von htpasswd

Das Dienstprogramm htpasswd ist im Paket der Apache-HTTP-Server-Tools enthalten. Trotz seines Apache-Ursprungs ist es das Standardwerkzeug zum Erstellen von Passwortdateien, die mit der NGINX-Basisauthentifizierung kompatibel sind.

Auf RHEL/Rocky Linux/AlmaLinux:

dnf install httpd-tools

Auf Debian/Ubuntu:

apt install apache2-utils

Auf Alpine Linux:

apk add apache2-utils

Erstellen Ihrer ersten htpasswd-Datei

Der Befehl htpasswd erstellt und verwaltet Passwortdateien. So erstellen Sie eine neue Datei mit Ihrem ersten Benutzer:

htpasswd -c /etc/nginx/.htpasswd admin

Das Flag -c erstellt eine neue Datei (und überschreibt eine vorhandene). Sie werden aufgefordert, das Passwort einzugeben und zu bestätigen:

New password:
Re-type new password:
Adding password for user admin

Wichtig: Verwenden Sie -c nur beim Erstellen einer neuen Datei. Bei einer vorhandenen Datei werden alle anderen Benutzer gelöscht.

Hinzufügen weiterer Benutzer

Um weitere Benutzer zu einer vorhandenen Datei hinzuzufügen, lassen Sie das Flag -c weg:

htpasswd /etc/nginx/.htpasswd developer

Nicht-interaktive Passworterstellung

Für Skripte und Automatisierung verwenden Sie das Flag -b, um das Passwort auf der Befehlszeile anzugeben:

htpasswd -b /etc/nginx/.htpasswd api_user MySecurePassword123

Sicherheitshinweis: Dadurch wird das Passwort in Ihrer Shell-Historie und Prozessliste offengelegt. Für bessere Sicherheit in Skripten verwenden Sie das Flag -i, um von stdin zu lesen:

echo "MySecurePassword123" | htpasswd -i /etc/nginx/.htpasswd api_user

Auswahl eines Passwort-Hash-Algorithmus

Standardmäßig verwendet htpasswd APR1-MD5-Hashing. Für bessere Sicherheit sollten Sie bcrypt oder SHA-512 in Betracht ziehen:

Bcrypt (empfohlen für maximale Sicherheit):

htpasswd -B /etc/nginx/.htpasswd secure_user

Der resultierende Hash sieht so aus: secure_user:$2y$05$...

Sie können den bcrypt-Kostenfaktor anpassen (höher = langsamer, aber sicherer):

htpasswd -B -C 10 /etc/nginx/.htpasswd secure_user

SHA-512 (hervorragende Sicherheit mit konfigurierbaren Runden):

htpasswd -5 /etc/nginx/.htpasswd secure_user

Das Hash-Präfix ist $6$ für SHA-512. Sie können die Anzahl der Runden angeben:

htpasswd -5 -r 10000 /etc/nginx/.htpasswd secure_user

Anzeigen und Verwalten von Benutzern

Um zu sehen, welche Benutzer in Ihrer htpasswd-Datei vorhanden sind:

cat /etc/nginx/.htpasswd

Die Ausgabe zeigt Benutzernamen und ihre gehashten Passwörter:

admin:$apr1$vZoPBgxo$aLU58eCINcYB/7JWTF3Kd0
developer:$2y$05$K20V4yqxtMD/yYK8JDYCoOuojts.5.lEUftl7DeTJxAewWU/K0JKS

Um einen Benutzer zu löschen:

htpasswd -D /etc/nginx/.htpasswd developer

Um das Passwort eines Benutzers zu aktualisieren, fügen Sie ihn einfach erneut hinzu (ohne -c):

htpasswd /etc/nginx/.htpasswd admin

OpenSSL-Alternative zur Passwortgenerierung

Wenn htpasswd nicht verfügbar ist, können Sie OpenSSL verwenden, um kompatible Passwort-Hashes zu generieren. Dies ist besonders nützlich auf minimalen Systemen oder wenn Sie Passwörter programmatisch generieren müssen.

Generieren eines APR1-MD5-Hashes:

openssl passwd -apr1 "yourpassword"

Ausgabe: $apr1$1MFCM5cr$D4jG4xLTYqmSIsGkVg.wl/

openssl passwd -6 "yourpassword"

Erstellen einer vollständigen htpasswd-Zeile:

echo "admin:$(openssl passwd -apr1 'yourpassword')" > /etc/nginx/.htpasswd

Jedes Mal, wenn Sie openssl passwd ausführen, wird aufgrund des zufälligen Salts ein anderer Hash generiert – dies ist erwartetes und korrektes Verhalten. Das Salt ist im Hash selbst eingebettet.

Grundlegende NGINX-Konfiguration für den Passwortschutz

Konfigurieren wir nun NGINX so, dass Ihre htpasswd-Datei verwendet wird. Die beiden wesentlichen Direktiven sind:

  • auth_basic — Legt den Authentifizierungsbereich fest (der Name, der im Anmeldedialog des Browsers angezeigt wird)
  • auth_basic_user_file — Pfad zu Ihrer htpasswd-Datei

SCHUTZ EINES GESAMTEN SERVER-BLOCKS

server {
    listen 80;
    server_name staging.example.com;

    root /var/www/staging;

    auth_basic "Staging Environment";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        try_files $uri $uri/ =404;
    }
}

Jede Anfrage an diesen Server erfordert eine Authentifizierung.

SCHUTZ EINES BESTIMMTEN LOCATION-BLOCKS

server {
    listen 80;
    server_name example.com;

    root /var/www/html;

    location / {
        # Öffentlicher Zugriff
        try_files $uri $uri/ =404;
    }

    location /admin {
        auth_basic "Admin Area";
        auth_basic_user_file /etc/nginx/.htpasswd;
        try_files $uri $uri/ =404;
    }
}

D EAKTIVIEREN DER AUTHENTIFIZIERUNG FÜR BESTIMMTE LOCATIONS

Wenn Sie den Großteil eines Verzeichnisses schützen, aber bestimmte Dateien öffentlich zugänglich machen möchten, verwenden Sie auth_basic off:

location /admin {
    auth_basic "Admin Area";
    auth_basic_user_file /etc/nginx/.htpasswd;
    try_files $uri $uri/ =404;
}

# Öffentlichen Zugriff auf eine bestimmte Datei erlauben
location = /admin/health-check.php {
    auth_basic off;
    try_files $uri =404;
}

WordPress-Admin-Bereiche schützen

WordPress-Websites sind häufige Ziele für Brute-Force-Angriffe. Das Hinzufügen von nginx-Basisauthentifizierung schafft eine leistungsstarke zusätzliche Barriere, bevor Angreifer überhaupt wp-login.phperreichen.

Vollständige WordPress-Schutzkonfiguration

server {
    listen 80;
    server_name example.com;

    root /var/www/wordpress;
    index index.php;

    # Hauptseite - öffentlicher Zugriff
    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    # wp-login.php schützen
    location = /wp-login.php {
        auth_basic "WordPress Login";
        auth_basic_user_file /etc/nginx/.htpasswd;

        include fastcgi_params;
        fastcgi_pass unix:/run/php-fpm/www.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    # wp-admin-Verzeichnis schützen
    location /wp-admin {
        auth_basic "WordPress Admin";
        auth_basic_user_file /etc/nginx/.htpasswd;

        location ~ .php$ {
            include fastcgi_params;
            fastcgi_pass unix:/run/php-fpm/www.sock;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        }
    }

    # WICHTIG: admin-ajax.php ohne Authentifizierung erlauben
    # Viele Plugins und Themes verwenden AJAX im Frontend
    location = /wp-admin/admin-ajax.php {
        auth_basic off;

        include fastcgi_params;
        fastcgi_pass unix:/run/php-fpm/www.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    # PHP-Verarbeitung für andere Dateien
    location ~ .php$ {
        include fastcgi_params;
        fastcgi_pass unix:/run/php-fpm/www.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

Warum admin-ajax.php ausschließen? WordPress verwendet admin-ajax.php für Frontend-AJAX-Anfragen – Kontaktformulare, Live-Suche, Warenkorb-Funktionalität und unzählige Plugin-Funktionen sind darauf angewiesen. Eine Authentifizierungspflicht würde diese Funktionen für reguläre Besucher beeinträchtigen.

xmlrpc.php schützen

Der XML-RPC-Endpunkt ist ein weiterer häufiger Angriffsvektor. Wenn Sie ihn nicht verwenden (die meisten modernen WordPress-Installationen tun das nicht), blockieren Sie ihn vollständig:

location = /xmlrpc.php {
    deny all;
    return 444;
}

Wenn Sie XML-RPC benötigen (für Jetpack oder die WordPress-Mobile-App), schützen Sie es mit Basisauthentifizierung:

location = /xmlrpc.php {
    auth_basic "XML-RPC Access";
    auth_basic_user_file /etc/nginx/.htpasswd;

    include fastcgi_params;
    fastcgi_pass unix:/run/php-fpm/www.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Staging- und Entwicklungsumgebungen schützen

Staging-Umgebungen enthalten oft sensible Daten oder Funktionen, die noch nicht für die Öffentlichkeit bestimmt sind. Basisauthentifizierung ist eine effektive Möglichkeit, den Zugriff ohne komplexe Änderungen auf Anwendungsebene einzuschränken.

Vollständiger Schutz der Staging-Umgebung

server {
    listen 80;
    server_name staging.example.com;

    root /var/www/staging;
    index index.php index.html;

    # Authentifizierung für alles erforderlich
    auth_basic "Staging - Authorized Personnel Only";
    auth_basic_user_file /etc/nginx/.htpasswd_staging;

    # Ihre normalen location-Blöcke folgen
    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ .php$ {
        include fastcgi_params;
        fastcgi_pass unix:/run/php-fpm/www.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

Unterschiedliche Anmeldedaten für unterschiedliche Umgebungen

Verwalten Sie separate htpasswd-Dateien für unterschiedliche Zwecke:

# Produktions-Admin-Zugriff
htpasswd -cB /etc/nginx/.htpasswd_admin admin

# Zugriff auf Staging-Umgebung (geteilt mit QA-Team)
htpasswd -cB /etc/nginx/.htpasswd_staging qa_team
htpasswd -B /etc/nginx/.htpasswd_staging developer1
htpasswd -B /etc/nginx/.htpasswd_staging developer2

# Client-Vorschau-Zugriff
htpasswd -cB /etc/nginx/.htpasswd_preview client

Kombination von Basic Auth mit SSL/TLS

Die Basisauthentifizierung überträgt Anmeldeinformationen in Base64-Kodierung – diese lassen sich bei Abfangen leicht dekodieren. Verwenden Sie bei der Implementierung von Basic Auth immer HTTPS. Eine vollständige Anleitung zur Härtung Ihrer TLS-Konfiguration finden Sie in unserem Artikel zur NGINX TLS 1.3-Härtung.

Sichere HTTPS-Konfiguration mit Basic Auth

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

server {
    listen 443 ssl http2;
    server_name secure.example.com;

    ssl_certificate /etc/letsencrypt/live/secure.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/secure.example.com/privkey.pem;

    # Modern SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    root /var/www/secure;

    # Now basic auth is transmitted over encrypted connection
    auth_basic "Secure Area";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        try_files $uri $uri/ =404;
    }
}

Die Weiterleitung von HTTP zu HTTPS stellt sicher, dass Anmeldeinformationen niemals über eine unverschlüsselte Verbindung gesendet werden.

IP-basierter Zugriff mit Basic-Auth-Fallback

Für interne Anwendungen möchten Sie möglicherweise den Zugriff ohne Authentifizierung von vertrauenswürdigen IP-Adressen erlauben, während von allen anderen Standorten Anmeldeinformationen verlangt werden.

location /admin {
    satisfy any;

    # Allow without auth from office IP
    allow 203.0.113.50;
    # Allow without auth from VPN range
    allow 10.8.0.0/24;
    deny all;

    # Require auth from all other IPs
    auth_basic "Admin Area";
    auth_basic_user_file /etc/nginx/.htpasswd;

    try_files $uri $uri/ =404;
}

Die Direktive satisfy any bedeutet, dass die Anfrage zugelassen wird, wenn entweder die IP auf der Whitelist steht oder gültige Anmeldeinformationen bereitgestellt werden. Verwenden Sie satisfy all, wenn Sie beide Bedingungen verlangen möchten.

Fehlerbehebung bei häufigen Problemen

Authentifizierung wird nicht erzwungen

Wenn Anfragen ohne Anmeldeinformationen erfolgreich sind, prüfen Sie:

  1. Dateiberechtigungen: Der NGINX-Worker-Prozess (üblicherweise der Benutzer nginx) muss die htpasswd-Datei lesen können:
chmod 644 /etc/nginx/.htpasswd
chown root:nginx /etc/nginx/.htpasswd
  1. Dateipfad: Verwenden Sie absolute Pfade in auth_basic_user_file

  2. Location-Abgleich: Stellen Sie sicher, dass Ihr geschützter Location-Block tatsächlich der angeforderten URL entspricht

  3. SELinux (RHEL/Rocky/Alma): Die htpasswd-Datei benötigt den richtigen Kontext:

restorecon -v /etc/nginx/.htpasswd

Fehler „Passwort stimmt nicht überein“

Prüfen Sie das NGINX-Fehlerprotokoll:

tail -f /var/log/nginx/error.log

Häufige Ursachen:
– Das Passwort wurde geändert, aber NGINX nicht neu geladen
– Das Hash-Format wird von der crypt-Bibliothek des Systems nicht unterstützt
– Sonderzeichen im Passwort verursachen Probleme beim Shell-Escaping

401-Antwort trotz korrekter Anmeldeinformationen

Überprüfen Sie, ob das Passwort funktioniert:

# Test with curl
curl -u admin:yourpassword http://localhost/protected-area/

Wenn es mit curl funktioniert, aber nicht im Browser, leeren Sie den Browser-Cache und die gespeicherten Anmeldeinformationen.

Sicherheits-Best-Practices

Dateiberechtigungen

Speichern Sie htpasswd-Dateien außerhalb des Web-Roots und beschränken Sie die Berechtigungen:

# Create secure directory
mkdir -p /etc/nginx/auth
chmod 750 /etc/nginx/auth

# Create htpasswd file with restricted permissions
htpasswd -cB /etc/nginx/auth/.htpasswd admin
chmod 640 /etc/nginx/auth/.htpasswd
chown root:nginx /etc/nginx/auth/.htpasswd

Starke Passwörter verwenden

Basic-Auth-Passwörter sollten stark sein, da sie Web-Ressourcen schützen:

# Generate a secure random password
openssl rand -base64 16

Tarifbegrenzung implementieren

Kombinieren Sie Basic Auth mit DER NGINX-Tarifbegrenzung, um Brute-Force-Angriffe zu verhindern:

# Define rate limiting zone
limit_req_zone $binary_remote_addr zone=auth_limit:10m rate=5r/m;

location /admin {
    # Apply strict rate limiting
    limit_req zone=auth_limit burst=3 nodelay;

    auth_basic "Admin Area";
    auth_basic_user_file /etc/nginx/.htpasswd;

    try_files $uri $uri/ =404;
}

Dies begrenzt Authentifizierungsversuche auf 5 pro Minute pro IP-Adresse.

Authentifizierungsversuche protokollieren

Die Variable $remote_user enthält den authentifizierten Benutzernamen. Fügen Sie sie in Ihr Protokollformat ein:

log_format auth_log '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent"';

access_log /var/log/nginx/auth_access.log auth_log;

Zusätzliche Sicherheitsebenen

Für Produktionsumgebungen sollten Sie das OWASP ModSecurity Core Rule Set in Betracht ziehen, um vor gängigen Web-Angriffen jenseits der Umgehung der Authentifizierung zu schützen.

Testen Ihrer Konfiguration

Testen Sie die NGINX-Konfiguration immer vor dem Neuladen:

nginx -t

Bei Erfolg laden Sie NGINX neu:

systemctl reload nginx

Überprüfen Sie mit curl, ob die Authentifizierung funktioniert:

# Should return 401
curl -I http://localhost/admin/

# Sollte 200 zurückgeben
curl -I -u admin:password http://localhost/admin/

Fazit

NGINX-Basic-Auth mit htpasswd bietet eine unkomplizierte und effektive Methode, um den Zugriff auf Webressourcen zu beschränken. Sie sollte zwar die Authentifizierung auf Anwendungsebene für Benutzerkonten nicht ersetzen, ist aber ideal für:

  • Den Schutz von Staging- und Entwicklungsumgebungen
  • Das Hinzufügen einer zusätzlichen Sicherheitsebene für Admin-Bereiche
  • Die Beschränkung des Zugriffs auf interne Tools und Dashboards
  • Schnelle Zugriffskontrolle ohne Änderungen an der Anwendung

Denken Sie daran, bei der Implementierung von Basic Auth immer HTTPS zu verwenden, starke Hashing-Algorithmen wie bcrypt zu wählen und die Authentifizierung mit Rate Limiting für Defense in Depth zu kombinieren. Mit der richtigen Konfiguration bleibt nginx Basic Auth ein wertvolles Werkzeug in Ihrem Arsenal für Web-Sicherheit.

Für die Authentifizierung auf Systemebene mit Linux-Benutzern und -Gruppen lesen Sie unseren Leitfaden zur NGINX PAM-Authentifizierung. Weitere NGINX-Sicherheitsthemen finden Sie in unseren Leitfäden zur NGINX-Reverse-Proxy-Konfiguration und zur Fehlerbehebung bei 502 Bad Gateway.

Basic Auth am Edge. Basic Auth am Edge funktioniert heute; die Regression, auf die Sie achten sollten, ist der Tag, an dem jemand den htpasswd-Speicherort ändert, vergisst, NGINX neu zu laden, oder auth_basic aus einem verschachtelten Location-Block entfernt. GetPageSpeed Amplify führt geplante gixy-Scans über jeden Host aus und verknüpft die Ergebnisse mit Live-Laufzeitmetriken von NGINX. Drop-in-kompatibel mit dem veralteten nginx-amplify-agent (EOL Januar 2026).