PKR-Lab

300a0 - Vaultwarden — Passwort-Manager

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/3-apps-workloads/300a0-vaultwarden.md

Vaultwarden — Passwort-Manager

Cluster: TECH · Ordner argocd/apps/tech/vaultwarden/ · URL https://vault.tech.homeserver und https://vault-tech.pke-lab.de. kubectl-Befehle in diesem Doc gelten für den TECH-Cluster (Zugriff je Cluster).

Vaultwarden ist eine
leichtgewichtige Rust-Implementierung der Bitwarden-Server-API. Alle
offiziellen Bitwarden-Clients (Browser-Erweiterung, Mobile-Apps, Desktop-App,
CLI) können sich gegen einen selbst gehosteten Vaultwarden-Server verbinden,
ohne die schwere offizielle Bitwarden-Server-Suite (MSSQL, mehrere
Microservices) betreiben zu müssen.


Architektur

vault.tech.homeserver        →  Traefik    → vaultwarden (Port 80)
vault.pke-lab.de         →  Cloudflare Tunnel → vaultwarden (Port 80)
                                            └── PVC: data (2 Gi, local-path)

1. Erstdeployment

1.1 Admin-Token erzeugen (Argon2-Hash empfohlen)

Ein Klartext-ADMIN_TOKEN funktioniert, ist aber anfällig für
Timing-Angriffe. Vaultwarden empfiehlt stattdessen einen Argon2-PHC-Hash:

sudo docker run --rm -it vaultwarden/server:1.37.1 /vaultwarden hash

-it nicht vergessen — ohne TTY/stdin bricht der Passwort-Prompt mit
Os { code: 6, ... "No such device or address" } ab.

Das Kommando fragt interaktiv nach einem Passwort und gibt einen
$argon2id$...-Hash aus. Diesen Hash (nicht das Klartext-Passwort!) im
nächsten Schritt versiegeln.

1.2 SealedSecret-Ciphertext erzeugen

Über die Web-UI unter https://kubeseal-webgui.tech.homeserver:

  1. Öffnen und ausfüllen:
    • Namespace: vaultwarden
    • Secret-Name: vaultwarden-admin
    • Key: admin-token
    • Value: der $argon2id$...-Hash aus 1.1
  2. Encrypt klicken, den langen Base64-String kopieren.

Oder per CLI. Falls das lokale kubeconfig nicht auf den Home-Server zeigt
(z. B. von einer Workstation ohne Cluster-Zugriff), Public Key einmalig
vom Server holen und mit --cert an alle kubeseal-Aufrufe übergeben:

mkdir -p ~/homelab-certs
ssh -i ~/.ssh/id_ed25519 [email protected] \
  'sudo kubectl -n sealed-secrets get secret \
   -l sealedsecrets.bitnami.com/sealed-secrets-key=active \
   -o jsonpath="{.items[0].data.tls\.crt}" | base64 -d' \
  > ~/homelab-certs/sealed-secrets.pem

echo -n '$argon2id$...' \
  | kubeseal --raw \
      --cert ~/homelab-certs/sealed-secrets.pem \
      --namespace vaultwarden \
      --name vaultwarden-admin \
      --from-file=/dev/stdin

Mit direktem Cluster-Zugriff (kubeconfig zeigt auf den Home-Server) reicht
stattdessen:

echo -n '$argon2id$...' \
  | kubeseal --raw \
      --namespace vaultwarden \
      --name vaultwarden-admin \
      --controller-namespace sealed-secrets \
      --controller-name sealed-secrets-controller \
      --from-file=/dev/stdin

1.3 Ciphertext in values.yaml eintragen

argocd/apps/tech/vaultwarden/values.yaml öffnen und den Platzhalter ersetzen:

adminSecret:
  enabled: true
  secretName: vaultwarden-admin
  encryptedAdminToken: "AgB...langes-base64..."     # ← aus 1.2

Committen + pushen (macht der Nutzer selbst):

git add argocd/apps/tech/vaultwarden/values.yaml
git commit -m "feat(vaultwarden): set sealed admin token"
git push

ArgoCD übernimmt die Änderung innerhalb von ~3 Minuten (oder Refresh in
der ArgoCD-UI bei der vaultwarden-App klicken).

1.4 Verifizieren

SRV='ssh -i ~/.ssh/id_ed25519 ubuntu@homeserver'
$SRV 'sudo kubectl -n vaultwarden get pods,svc,ingress,pvc,sealedsecret,secret'
curl -sS https://vault.tech.homeserver/alive

Erwartet:


2. Ersten Account anlegen

  1. https://vault.tech.homeserver öffnen → Create Account.
  2. Master-Passwort setzen (idealerweise einen langen Passphrase-Satz, den
    man sich merken kann — das ist der einzige Schlüssel zum ganzen Tresor).
  3. Einloggen, im Web-Vault unter Account Settings → Security → Two-step
    Login
    2FA aktivieren (TOTP-App oder WebAuthn/Passkey).
  4. Danach SIGNUPS_ALLOWED: "false" in values.yaml setzen und
    pushen, damit der Server nicht dauerhaft offen für neue Registrierungen
    im Internet steht (der Tresor ist über vault.pke-lab.de extern
    erreichbar, siehe Architektur oben).

Nutzer-Inventar: Wer einen Account hat, wird zusätzlich (verschlüsselt,
außerhalb der App-DB) in capulus-ansible/group_vars/user_inventory_vault.yml
festgehalten — make user-inventory-edit zum Bearbeiten, siehe
capulus-core/4-planung/40080-multi-cluster-entw-prod-tech.md → Baustein 7
für den Zweck (Dokumentation, kein Ersatz für die eigentliche DB).


3. Clients verbinden

Alle offiziellen Bitwarden-Clients unterstützen einen "Self-hosted"-Server:

Intern im LAN funktioniert auch https://vault.tech.homeserver als Server-URL,
aber nur die pke-lab.de-Domain ist von unterwegs erreichbar.


4. Admin-Oberfläche

Unter https://vault.tech.homeserver/admin (LAN oder Tailnet) mit dem Klartext-Passwort
aus Schritt 1.1 einloggen. Auf dem öffentlichen Host vault-tech.pke-lab.de liefert
/admin 403: Ein zweiter Ingress mit einer Traefik-Middleware lässt dort nur
LAN und Tailnet zu (adminRestriction in values.yaml), Anfragen über den
Cloudflare-Tunnel kommen von der cloudflared-Pod-IP und werden abgewiesen. Alle
anderen Pfade (Web-Tresor, /api, /identity, Websocket) bleiben öffentlich.
Dort lassen sich u. a. Nutzer verwalten und Diagnosen einsehen.

Weitere Schichten für /admin:

Maßnahme Stand
Admin-Token als Argon2-PHC-Hash (Schritt 1.1) umgesetzt
2FA für alle Konten aktiv
Cloudflare-WAF-Regel „URI Path starts with /admin“ für vault-tech.pke-lab.de auf Block bewusst nicht gesetzt. Sie würde /admin schon am Cloudflare-Rand abweisen, bevor die Anfrage den Cluster erreicht. Die Traefik-Sperre (adminRestriction) deckt dasselbe ab. Die WAF-Regel ist eine optionale zweite Schicht, die im Cloudflare-Dashboard gesetzt wird (nicht im Repo), und gehört zur Zugangskontrolle des Tunnels (e0000)

SMTP für E-Mail-Versand (Passwort-Reset, Organisations-Einladungen) ist
seit dem netcup-Postfach-Setup fest in values.yaml hinterlegt (siehe
Abschnitt 4a) und muss dort nicht zusätzlich in der /admin-UI
gepflegt werden — ein dort manuell gesetzter SMTP-Wert würde ohnehin bei
jedem Pod-Neustart wieder auf den Env-Var-Wert zurückfallen.


4a. SMTP-Einladungsmails

Ohne SMTP-Konfiguration erzeugt Vaultwarden zwar einen Einladungs-Token,
verschickt aber keine E-Mail — das ist Standardverhalten von
Vaultwarden ohne SMTP_HOST. Konfiguriert ist das netcup-Postfach
[email protected]:

env:
  SMTP_HOST: mxe9f8.netcup.net
  SMTP_PORT: "465"
  SMTP_SECURITY: force_tls      # implizites TLS auf Port 465 (nicht STARTTLS)
  SMTP_FROM: [email protected]
  SMTP_FROM_NAME: Vaultwarden
  SMTP_USERNAME: [email protected]

smtpSecret:
  enabled: true
  secretName: vaultwarden-smtp
  encryptedSmtpPassword: "AgB...langes-base64..."

SMTP_PASSWORD kommt aus dem vaultwarden-smtp-SealedSecret
(templates/sealedsecret.yaml, Key smtp-password), analog zum
Admin-Token — gleicher kubeseal-Workflow wie in Schritt 1.2, nur mit
Namen vaultwarden-smtp und Postfach-Klartext-Passwort statt Argon2-Hash:

echo -n '<netcup-postfach-passwort>' \
  | kubeseal --raw \
      --namespace vaultwarden \
      --name vaultwarden-smtp \
      --controller-namespace sealed-secrets \
      --controller-name sealed-secrets-controller \
      --from-file=/dev/stdin

Bei Postfach-Passwort-Rotation: neuen Ciphertext erzeugen,
encryptedSmtpPassword ersetzen, committen + pushen. Das alte
vaultwarden-smtp-Secret im Cluster löschen, falls ArgoCD es nicht
automatisch prunt.

Verifizieren: Eine Organisations-Einladung im Web-Vault verschicken
und kubectl -n vaultwarden logs deploy/vaultwarden | grep -i smtp
prüfen — bei falschem Port/Security-Kombination (z. B. starttls auf
Port 465) schlägt der Verbindungsaufbau fehl und landet dort als Fehler.


5. Konfiguration (values.yaml)

Key Bedeutung Default
env.DOMAIN Öffentliche Basis-URL (Links, WebAuthn-Origin-Check) https://vault.pke-lab.de
env.SIGNUPS_ALLOWED Neue Registrierungen erlauben true (nach Account-Anlage auf false setzen)
env.WEBSOCKET_ENABLED Live-Sync zwischen Clients true
env.SMTP_HOST / SMTP_PORT / SMTP_SECURITY Mailserver für Einladungs-/Reset-Mails mxe9f8.netcup.net / 465 / force_tls
env.SMTP_FROM / SMTP_USERNAME Absenderadresse = Postfach-Login [email protected]
adminSecret.encryptedAdminToken Versiegelter Argon2-Hash für /admin — (Schritt 1)
adminRestriction.enabled / hosts / sourceRange Sperrt /admin auf den öffentlichen Hosts für alle Quellen außerhalb von sourceRange true / vault-tech.pke-lab.de / LAN und Tailnet
smtpSecret.encryptedSmtpPassword Versiegeltes netcup-Postfach-Passwort — (Abschnitt 4a)
persistence.size Datenspeicher (SQLite + Anhänge + Icon-Cache) 2Gi

6. Admin-Token rotieren

docker run --rm vaultwarden/server:1.37.1 /vaultwarden hash

Neuen Hash mit kubeseal versiegeln (Schritt 1.2), encryptedAdminToken in
values.yaml ersetzen, committen + pushen. Das alte vaultwarden-admin
Secret im Cluster löschen, falls ArgoCD es nicht automatisch prunt.


7. Warum kein NAS-Storage für die Haupt-PVC

Eine Migration von persistence.storageClassName auf die NFS-nas-
StorageClass (wie beim Großteil der übrigen Apps, siehe
capulus-core/2-betrieb-hardware/20000-nas-storage.md) wurde erwogen, aber bewusst
verworfen
: das NAS erzwingt inzwischen all_squash (kein
no_root_squash mehr verfügbar), was bei Vaultwardens SQLite-Datei zu
Permission-Problemen führt — siehe 60040. Die Haupt-PVC bleibt daher auf
local-path (Homeserver-System-SSD).

Stattdessen sichert ein nächtlicher backup-CronJob (eigene PVC, bewusst
storageClassName: nas, siehe backup-cronjob.yaml) die SQLite-Datenbank
per sqlite3 .backup (nutzt SQLites eigene Online-Backup-API, sicher auch
bei einer laufenden, offenen DB) auf das NAS — Details:
capulus-core/2-betrieb-hardware/20010-nas-backup.md.

Zusätzlich läuft ein verschlüsselter, versionierter restic-Backup (restic-backup.yaml, eine Backup-Ressource des capulus-operator, Einrichtung und Wiederherstellungstest: 20010). Der Spiegel oben bleibt, bis die Rolle vaultwarden_restore aus restic wiederherstellen kann.


8. Restore nach Redeploy / Disaster Recovery

Vaultwarden kennt keinen "User per API/Ansible anlegen"-Mechanismus, der
einen bestehenden Tresor mitbringt — Passwörter, Attachments und das
eigene 2FA/TOTP des Accounts ([email protected]) liegen alle
verschlüsselt in db.sqlite3 + rsa_key.pem. Der Account ist deshalb
nach einem Redeploy (z. B. verlorene local-path-PVC nach einem
Node-Wechsel) automatisch wieder vollständig da, sobald diese Dateien aus
dem NAS-Backup (siehe Abschnitt 7
und capulus-core/2-betrieb-hardware/20010-nas-backup.md) zurückkopiert sind — ein
separater Schritt, um den Nutzer "neu anzulegen", ist nicht nötig.

Dafür gibt es die Ansible-Rolle vaultwarden_restore
(capulus-ansible/roles/vaultwarden_restore/, Playbook
capulus-ansible/vaultwarden-restore.yml):

make vaultwarden-restore FORCE_RESTORE=true

Ablauf (alles automatisiert, läuft gegen den homeserver-Host, der
kubectl bereits lokal hat):

  1. vaultwarden-Deployment auf 0 Replicas skalieren (keine parallel
    schreibende Instanz während des Restores).
  2. Ein einmaliger Job (Manifest wird von Ansible gerendert und direkt per
    kubectl apply -f - angewendet — bewusst nicht Teil des Helm-Charts,
    damit ArgoCD ihn nicht als Dauerzustand verwaltet/prunt) mountet die
    vaultwarden-data-PVC (rw) und die vaultwarden-backup-PVC (ro) und
    spiegelt Letztere zurück auf Erstere.
  3. Deployment wieder auf 1 Replica skalieren, rollout status abwarten,
    /alive prüfen.

Sicherheitsgurt: Ohne FORCE_RESTORE=true (Default false) bricht die
Rolle sofort mit einer Fehlermeldung ab. Das Playbook ist bewusst nicht
Teil von site.yml/make install — ein automatischer Lauf bei jedem
normalen Deploy könnte sonst live Tresordaten mit einem älteren Backup-Stand
überschreiben. make vaultwarden-restore also nur gezielt nach einem
echten Redeploy oder Datenverlust ausführen, nie routinemäßig.

Wichtig: Das setzt voraus, dass die vaultwarden-backup-PVC auf der
NAS noch existiert und der letzte nächtliche backup-cronjob.yaml-Lauf
erfolgreich war (kubectl -n vaultwarden get jobs). Ist auch dieser Stand
verloren (z. B. NAS-Totalausfall), bleibt nur der manuelle
restic-Restore von der externen USB-Platte, siehe
capulus-core/2-betrieb-hardware/20010-nas-backup.md → Wiederherstellung
— das NAS selbst bleibt bewusst außerhalb von Ansible verwaltet, dieser
Pfad wird nicht automatisiert.


9. Troubleshooting

Symptom Hinweis
Pod CrashLoopBackOff nach Erstdeployment encryptedAdminToken ist noch REPLACE_ME_WITH_KUBESEAL_OUTPUT — Schritt 1.3 abschließen
vaultwarden-admin-Secret fehlt kubectl -n vaultwarden describe sealedsecret vaultwarden-admin — Ciphertext muss gegen den Public Key dieses Clusters erzeugt worden sein
Browser-Erweiterung/App kann sich nicht verbinden env.DOMAIN muss exakt zur benutzten Server-URL passen (Schema + Host), sonst schlägt der WebAuthn-Origin-Check fehl
Kein Live-Sync zwischen Geräten env.WEBSOCKET_ENABLED prüfen; Traefik/Cloudflare müssen Websocket-Upgrades durchreichen (Standard bei beiden, kein Extra-Konfig nötig)
/admin auf vault-tech.pke-lab.de liefert 403 Gewollt. Die Admin-Oberfläche nur über https://vault.tech.homeserver/admin aufrufen. Liefert auch der interne Host 403, kubectl -n vaultwarden get middleware,ingress prüfen
/admin ist über vault-tech.pke-lab.de trotzdem erreichbar (200) Die Middleware fehlt oder der Name in der Annotation des Ingress vaultwarden-admin stimmt nicht: Traefik verwirft dann den Router stillschweigend, und /admin fällt auf den offenen /-Router zurück. kubectl -n vaultwarden get middleware vaultwarden-admin-nur-intern
/admin liefert 404/Fehler trotz korrektem Token ADMIN_TOKEN env im Pod prüfen (kubectl -n vaultwarden exec deploy/vaultwarden -- env \| grep ADMIN_TOKEN) — muss aus dem Secret injiziert worden sein
Keine Einladungs-/Reset-Mail kommt an kubectl -n vaultwarden logs deploy/vaultwarden \| grep -i smtp prüfen — häufigste Ursache: falsche SMTP_SECURITY/SMTP_PORT-Kombination (Port 465 braucht force_tls, Port 587 braucht starttls) oder vaultwarden-smtp-Secret fehlt (siehe Abschnitt 4a)