Quelltext der Seite Vaultwarden: HTTPS mit Reverse Proxy (Caddy, nginx, OPNsense)

{{Steckbrief
| gilt_fuer   = Vaultwarden 1.37.x hinter Caddy 2, nginx oder dem Caddy-Plugin auf OPNsense; Zertifikate von Let's Encrypt oder eigener CA
| bereich     = IT-Security
| dauer       = ca. 30–60 Minuten
| rechte      = Root auf dem Proxy-Host bzw. Administrator der OPNsense
| stand       = Oktober 2026
}}
'''Vaultwarden mit HTTPS über einen Reverse Proxy''' zu betreiben ist die vom Projekt empfohlene Variante: Der Proxy übernimmt Zertifikat und TLS, Vaultwarden selbst lauscht nur unverschlüsselt im internen Netz. Die eingebaute TLS-Funktion des Web-Frameworks Rocket gilt laut Projekt als unausgereift und ist nicht für den Produktivbetrieb gedacht. Diese Anleitung zeigt fertige Konfigurationen für Caddy und nginx, den Einsatz der OPNsense als Proxy, die richtige Weitergabe der Client-IP und den Betrieb einer nur intern erreichbaren Instanz mit öffentlichem Zertifikat.

[[Datei:Vaultwarden-ReverseProxy.png|thumb|center|750px|Vaultwarden hinter einem Reverse Proxy: Clients verbinden sich per HTTPS auf Port 443 mit Caddy, nginx oder OPNsense; der Proxy leitet per HTTP an Vaultwarden auf Port 80 bzw. 127.0.0.1:8000 weiter, inklusive WebSocket-Upgrade für /notifications/hub; Header X-Real-IP mit der echten Client-IP, IP_HEADER_TRUSTED_PROXIES legt vertrauenswürdige Proxys fest; vollständige Zertifikatskette für Android; /admin nur aus dem internen Netz; interne Instanz mit Let's-Encrypt-DNS-Challenge.]]

== Anforderungen an den Reverse Proxy für Vaultwarden ==
* '''Gültiges Zertifikat mit vollständiger Kette''': Android-Geräte bringen nicht alle Zwischenzertifikate mit und lehnen Server ohne Kette ab. Bei certbot <code>fullchain.pem</code> verwenden, nicht <code>cert.pem</code>. Selbst signierte Zertifikate machen auf vielen Plattformen Probleme.
* '''WebSockets weiterleiten''': Seit 1.29.0 laufen die Live-Benachrichtigungen über denselben Port wie die Webseite (<code>/notifications/hub</code>). Der separate Port 3012 wurde mit 1.31.0 entfernt. Der Proxy muss die Header <code>Upgrade</code> und <code>Connection</code> weitergeben.
* '''Echte Client-IP weitergeben''': Vaultwarden liest standardmäßig den Header <code>X-Real-IP</code>. Ohne ihn stehen in Log und Ratenbegrenzung nur die IP des Proxys – Fail2ban sperrt dann den falschen.
* '''Große Anfragen zulassen''': Anhänge und Sends können bis zu 500 MB groß sein. Die nginx-Vorlage des Projekts setzt <code>client_max_body_size 525M</code>.
* '''Eigene Subdomain''': Vaultwarden läuft am besten unter einer eigenen Subdomain wie <code>vault.firma.de</code>. Ein Unterpfad wie <code>/vault/</code> ist möglich, muss dann aber auch in <code>DOMAIN</code> stehen.

== Variante A: Caddy im selben Compose-Projekt ==
[[Caddy]] holt das [[Let's Encrypt]]-Zertifikat automatisch. In der compose.yaml aus [[Vaultwarden: Installation mit Docker Compose]] den Port-Eintrag von Vaultwarden entfernen und Caddy ergänzen:
<syntaxhighlight lang="yaml">
  caddy:
    image: caddy:2
    container_name: caddy
    restart: unless-stopped
    ports:
      - 80:80
      - 443:443
      - 443:443/udp
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./caddy-data:/data
      - ./caddy-config:/config
</syntaxhighlight>
'''Caddyfile''':
<syntaxhighlight lang="text">
vault.firma.de {
  encode zstd gzip

  # Admin-Panel nur aus privaten Netzen
  @admin {
    path /admin*
    not remote_ip private_ranges
  }
  respond @admin 403

  reverse_proxy vaultwarden:80 {
    header_up X-Real-IP {remote_host}
  }
}
</syntaxhighlight>
* Für die HTTP-01-Challenge muss Port 80 aus dem Internet erreichbar sein.
* Caddy leitet WebSockets ohne zusätzliche Einstellungen weiter.
* Beide Container liegen im automatisch erzeugten Compose-Netz; nur Caddy ist von außen erreichbar.

== Variante B: nginx ==
Vaultwarden lauscht auf <code>127.0.0.1:8000</code>, das Zertifikat kommt z. B. von certbot. Gekürzt nach der Vorlage des Projekts:
<syntaxhighlight lang="nginx">
upstream vaultwarden-default {
  zone vaultwarden-default 64k;
  server 127.0.0.1:8000;
  keepalive 2;
}
map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      "";
}
server {
  listen 80;
  listen [::]:80;
  server_name vault.firma.de;
  return 301 https://$host$request_uri;
}
server {
  listen 443 ssl;
  listen [::]:443 ssl;
  http2 on;
  server_name vault.firma.de;

  ssl_certificate     /etc/letsencrypt/live/vault.firma.de/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/vault.firma.de/privkey.pem;
  add_header Strict-Transport-Security "max-age=31536000;" always;

  client_max_body_size 525M;

  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection $connection_upgrade;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;

  location / {
    proxy_pass http://vaultwarden-default;
  }

  location /admin {
    allow 10.0.0.0/8;
    allow 192.168.0.0/16;
    deny all;
    proxy_pass http://vaultwarden-default;
  }
}
</syntaxhighlight>
* Bei <code>504 Gateway Timeout</code> die Timeouts erhöhen (<code>proxy_read_timeout</code> u. a.).
* Allgemeine Hinweise zu nginx: [[Nginx]].

== Variante C: OPNsense als Reverse Proxy ==
Steht Vaultwarden hinter einer OPNsense, kann deren Caddy-Plugin Zertifikat und Weiterleitung übernehmen. Einrichtung siehe [[OPNsense - Caddy Reverse Proxy]]. Für Vaultwarden gilt:
* Domain <code>vault.firma.de</code> mit automatischem Let's-Encrypt-Zertifikat anlegen, Handler auf die interne IP und den Port von Vaultwarden.
* Für den Pfad <code>/admin*</code> einen eigenen Handler mit Zugriffsliste nur für das Admin-Netz anlegen.
* In Vaultwarden die OPNsense als vertrauenswürdigen Proxy eintragen (siehe nächster Abschnitt), weil sie aus einem anderen Netz zugreift als ein lokaler Proxy.

== Client-IP und vertrauenswürdige Proxys ==
{| class="wikitable"
! Einstellung !! Standard !! Bedeutung
|-
| <code>IP_HEADER</code> || <code>X-Real-IP</code> || Header, aus dem Vaultwarden die Client-IP liest; <code>none</code> nutzt die Verbindungs-IP
|-
| <code>IP_HEADER_TRUSTED_PROXIES</code> || <code>local</code> || von welchen Adressen der Header akzeptiert wird; <code>local</code> = alle nicht öffentlichen Adressen
|}
* Der Header wird nur von den hier eingetragenen Proxys übernommen, sonst könnte jeder Client seine IP fälschen und die Ratenbegrenzung umgehen.
* '''Seit 1.37.4''' gilt bei <code>IP_HEADER=X-Forwarded-For</code> die '''rechteste''' Adresse, die kein vertrauenswürdiger Proxy ist (vorher die linkeste). Bei mehreren Proxys hintereinander – z. B. CDN vor nginx – alle eintragen.
* Bei Cloudflare <code>IP_HEADER=CF-Connecting-IP</code> setzen.
* Die WebSocket-Verbindung zeigt im Log immer die IP des Proxys. Das ist bekannt und kein Fehler.

== Nur intern erreichbare Instanz ==
Viele Unternehmen stellen Vaultwarden nicht ins Internet, sondern nur ins LAN und VPN. Auch dann braucht es ein Zertifikat, dem alle Geräte vertrauen:
* '''Let's Encrypt per DNS-01-Challenge''': Der Proxy beweist den Besitz der Domain über einen DNS-Eintrag; der Server muss dafür nicht aus dem Internet erreichbar sein. Caddy braucht dafür einen Build mit dem Modul des DNS-Anbieters, die OPNsense nutzt den [[OPNsense - ACME-Client für Let's Encrypt-Zertifikate|ACME-Client]].
* Intern löst ein DNS-Override <code>vault.firma.de</code> auf die private IP auf.
* Mitarbeiter unterwegs verbinden sich per VPN, z. B. [[WireGuard]].
* Nachteil: Smartphones ohne VPN synchronisieren unterwegs nicht. Die Apps arbeiten dann mit der zuletzt synchronisierten, lokal verschlüsselten Kopie weiter.

== Prüfen ==
<syntaxhighlight lang="bash">
# Zertifikatskette anzeigen
openssl s_client -showcerts -connect vault.firma.de:443 -servername vault.firma.de </dev/null
# Antwort von Vaultwarden
curl -sI https://vault.firma.de/alive
</syntaxhighlight>
* In den Entwicklerwerkzeugen des Browsers (Reiter Netzwerk, Filter WS) muss <code>/notifications/hub</code> den Status '''101''' liefern.
* Das Admin-Panel unter ''Diagnostics'' zeigt, ob die Domäne stimmt und der Header <code>X-Real-IP</code> ankommt.
* Öffentlich erreichbare Server mit SSL Labs prüfen und dort ''Do not show the results on the boards'' aktivieren.

== Hinweise ==
* '''Zugriffsprotokolle''': Die WebSocket-Anfrage enthält ein Zugriffstoken im Parameter <code>access_token</code>. Proxy-Logs, die an zentrale Systeme gehen, sollten diesen Wert schwärzen.
* '''Admin-Panel''' nie öffentlich erreichbar lassen, siehe [[Vaultwarden: Absichern und härten]].
* Bei Aufbau von Reverse Proxys, Zertifikatsverwaltung und Linux-Servern unterstützt Sie das [https://www.max-it.de/it-services/linux-consulting/ Linux-Consulting von m.a.x. it].

== Siehe auch ==
* [[Vaultwarden]] – Überblick und alle Artikel der Reihe
* [[Reverse Proxy]]
* [[OPNsense - NGINX Reverse Proxy und WAF]]
* [[HTTPS]]

== Links und Quellen ==
* [https://github.com/dani-garcia/vaultwarden/wiki/Proxy-examples Vaultwarden-Wiki: Proxy examples]
* [https://www.max-it.de/it-services/linux-consulting/ Linux-Consulting von m.a.x. it]

{{Uebermax}}
[[Kategorie:IT-Security]]