Quelltext der Seite Vaultwarden: Zwei-Faktor-Anmeldung und SSO mit OpenID Connect

{{Steckbrief
| gilt_fuer   = Vaultwarden 1.37.x; Bitwarden-Clients ab 2026.x; Identitätsanbieter mit OpenID Connect (Microsoft Entra ID, Keycloak, Authentik, Zitadel u. a.)
| bereich     = IT-Security
| dauer       = 2FA je Benutzer ca. 5 Minuten; SSO-Anbindung ca. 1–2 Stunden
| rechte      = Benutzerkonto in Vaultwarden; für SSO zusätzlich Administrator des Identitätsanbieters und Zugriff auf die Vaultwarden-Konfiguration
| stand       = Oktober 2026
}}
'''Zwei-Faktor-Anmeldung in Vaultwarden''' schützt Tresore davor, dass ein erbeutetes Master-Passwort allein für die Anmeldung reicht. Vaultwarden unterstützt alle gängigen zweiten Faktoren der Bitwarden-Clients – von der Authenticator-App bis zum FIDO2-Sicherheitsschlüssel – und kann sie über eine Organisationsrichtlinie für alle Mitglieder verpflichtend machen. Seit Version 1.35.0 lässt sich außerdem '''Single Sign-On über OpenID Connect''' anbinden, sodass sich Mitarbeiter mit ihrem Firmenkonto, z. B. aus Microsoft Entra ID, anmelden. Diese Anleitung zeigt beides und erklärt die Besonderheiten.

[[Datei:Vaultwarden-2FA-SSO.png|thumb|center|750px|Zwei-Faktor-Anmeldung und SSO in Vaultwarden: Faktoren Authenticator-App (TOTP), FIDO2/WebAuthn-Sicherheitsschlüssel und Passkeys als zweiter Faktor, E-Mail-Code, YubiKey OTP und Duo; Wiederherstellungscode offline aufbewahren; Organisationsrichtlinie Zwei-Faktor-Anmeldung erforderlich; SSO mit OpenID Connect: Vaultwarden leitet zur Anmeldung an Entra ID, Keycloak oder Authentik weiter, Rücksprung an /identity/connect/oidc-signin; das Master-Passwort bleibt zum Entschlüsseln des Tresors nötig.]]

== Zwei-Faktor-Methoden in Vaultwarden ==
{| class="wikitable"
! Methode !! Schutz vor Phishing !! Voraussetzung in Vaultwarden
|-
| '''FIDO2/WebAuthn''' (Sicherheitsschlüssel wie YubiKey, Nitrokey; Passkeys als zweiter Faktor) || hoch – an die Domain gebunden || HTTPS mit gültigem Zertifikat, <code>DOMAIN</code> exakt wie im Browser
|-
| '''Authenticator-App''' (TOTP, z. B. Microsoft Authenticator, Aegis, 2FAS) || mittel – Code kann abgefangen werden || keine
|-
| '''YubiKey OTP''' || mittel || API-Schlüssel von Yubico: <code>YUBICO_CLIENT_ID</code>, <code>YUBICO_SECRET_KEY</code>
|-
| '''Duo''' (Universal Prompt) || je nach Duo-Methode || pro Benutzer oder global: <code>DUO_IKEY</code>, <code>DUO_SKEY</code>, <code>DUO_HOST</code>
|-
| '''E-Mail-Code''' || gering – hängt am Mailkonto || SMTP konfiguriert
|}
'''Empfehlung:''' zwei FIDO2-Schlüssel je Administrator (einer als Reserve), für alle übrigen Mitarbeiter FIDO2 oder eine Authenticator-App. E-Mail nur als Notlösung, vor allem wenn das Mailkonto mit einem Passwort aus demselben Tresor geschützt ist.

Hintergrund zu den Verfahren: [[Zwei-Faktor-Authentifizierung]].

== Schritt 1: Zwei-Faktor-Anmeldung als Benutzer einrichten ==
# Im Web-Tresor anmelden, ''Einstellungen › Sicherheit › Zweistufige Anmeldung'' öffnen.
# Zuerst den '''Wiederherstellungscode''' anzeigen und ausgedruckt oder in einem zweiten, unabhängigen Speicher ablegen. Er ist der einzige Weg zurück, wenn alle Faktoren verloren gehen.
# Einen Anbieter wählen, mit dem Master-Passwort bestätigen und der Anleitung folgen: QR-Code scannen bzw. Sicherheitsschlüssel antippen.
# Nach Möglichkeit einen zweiten Faktor als Ersatz hinterlegen.

* Meldet sich jemand mit Wiederherstellungscode an, entfernt Bitwarden alle Zwei-Faktor-Methoden des Kontos. Seit 1.37.4 schickt Vaultwarden danach eine eigene Benachrichtigung.
* Verliert ein Mitarbeiter Faktor und Wiederherstellungscode, kann ein Administrator die Zwei-Faktor-Anmeldung im '''Admin-Panel''' unter ''Users'' entfernen. Vorher die Identität sicher prüfen (persönlich oder Rückruf), sonst wird das zum Einfallstor.
* Der in Vaultwarden gespeicherte '''TOTP-Generator''' für Einträge im Tresor ist etwas anderes: Er erzeugt Codes für andere Dienste. Den zweiten Faktor für den Tresor selbst nie im selben Tresor speichern.

== Schritt 2: Zwei-Faktor-Anmeldung für alle verpflichtend machen ==
# Im Web-Tresor in die '''Organisation''' wechseln, ''Admin-Konsole › Richtlinien''.
# Richtlinie '''Zweistufige Anmeldung erforderlich''' aktivieren.
* Mitglieder ohne zweiten Faktor verlieren den Zugriff auf die Organisation, bis sie einen eingerichtet haben. Vorher ankündigen und eine Übergangsfrist einplanen.
* Mit <code>EMAIL_2FA_ENFORCE_ON_VERIFIED_INVITE=true</code> richtet Vaultwarden bei eingeladenen Benutzern mit bestätigter Adresse automatisch E-Mail als zweiten Faktor ein, damit sie die Richtlinie sofort erfüllen. Danach auf eine stärkere Methode wechseln lassen.
* Mit <code>DISABLE_2FA_REMEMBER=true</code> verlangt Vaultwarden den zweiten Faktor bei jeder Anmeldung, auch wenn ''Angemeldet bleiben'' gewählt wurde.

== Single Sign-On mit OpenID Connect ==
'''So funktioniert SSO bei Vaultwarden:'''
* Der Benutzer wählt in der App ''Single Sign-On verwenden'' und meldet sich beim Identitätsanbieter an – mit dessen Kennwort, MFA und Richtlinien für bedingten Zugriff.
* Danach fragt der Client trotzdem das '''Master-Passwort''' ab. Es bleibt nötig, um den Tresor zu entschlüsseln. SSO ersetzt nur die Anmeldung, nicht das Zero-Knowledge-Prinzip. Funktionen wie Key Connector oder vertrauenswürdige Geräte aus Bitwarden Enterprise gibt es in Vaultwarden nicht.
* Vorteil: Wer im Verzeichnis deaktiviert wird, kann sich nicht mehr neu anmelden. Bereits geöffnete und offline zwischengespeicherte Tresore bleiben aber lesbar, bis die Sitzung abläuft. Deshalb gehört das Sperren in Vaultwarden selbst zum Offboarding, siehe [[Vaultwarden: Organisationen, Sammlungen und Benutzerverwaltung]].

=== Schritt 3: App im Identitätsanbieter registrieren (Beispiel Entra ID) ===
# Im [[Entra ID|Microsoft Entra Admin Center]] unter ''App-Registrierungen'' eine neue Registrierung anlegen.
# Unter ''Authentifizierung'' als Umleitungs-URI vom Typ ''Web'' eintragen: <code>https://vault.firma.de/identity/connect/oidc-signin</code>
# Unter ''Zertifikate & Geheimnisse'' einen geheimen Clientschlüssel erstellen und den '''Wert''' notieren; Ablaufdatum im Kalender vermerken.
# Unter ''API-Berechtigungen'' sicherstellen, dass <code>openid</code>, <code>profile</code>, <code>email</code> und <code>offline_access</code> vorhanden sind. Ohne <code>offline_access</code> gibt es kein Refresh-Token und die Sitzung endet nach Ablauf des Zugriffstokens.
# Optional unter ''Unternehmensanwendungen › Eigenschaften'' ''Zuweisung erforderlich'' aktivieren und nur eine Gruppe zuweisen.

=== Schritt 4: Vaultwarden konfigurieren ===
<syntaxhighlight lang="yaml">
      SSO_ENABLED: "true"
      SSO_AUTHORITY: https://login.microsoftonline.com/<Verzeichnis-ID>/v2.0
      SSO_SCOPES: "openid profile offline_access User.Read"
      SSO_CLIENT_ID: <Anwendungs-ID>
      SSO_CLIENT_SECRET: ${VW_SSO_SECRET}
      SSO_SIGNUPS_MATCH_EMAIL: "true"
      SSO_ONLY: "false"
</syntaxhighlight>
{| class="wikitable"
! Einstellung !! Bedeutung !! Empfehlung
|-
| <code>SSO_AUTHORITY</code> || Basisadresse des Anbieters ohne <code>/.well-known/openid-configuration</code>; muss exakt dem Feld <code>issuer</code> entsprechen || Wert aus der Discovery-Antwort übernehmen
|-
| <code>SSO_ONLY</code> || verbietet die Anmeldung nur mit E-Mail und Master-Passwort || erst nach erfolgreicher Umstellung aller Benutzer
|-
| <code>SSO_SIGNUPS_ALLOWED</code> (ab 1.37.3) || SSO darf neue Konten anlegen || <code>false</code>, wenn nur eingeladene Benutzer Zugang erhalten sollen
|-
| <code>SSO_SIGNUPS_MATCH_EMAIL</code> || verknüpft beim ersten SSO-Login ein bestehendes Konto mit gleicher E-Mail || für die Umstellung bestehender Konten <code>true</code>
|-
| <code>SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION</code> || akzeptiert Anbieter ohne Angabe <code>email_verified</code> || <code>false</code> lassen; zusammen mit Match-E-Mail droht Kontoübernahme
|-
| <code>SSO_MASTER_PASSWORD_POLICY</code> || Master-Passwort-Regeln für SSO-Konten, z. B. <code>{"minLength":14,"minComplexity":3}</code> || setzen
|-
| <code>SSO_PKCE</code> || PKCE im Code-Flow || Standard <code>true</code> lassen
|}
* Die Rücksprungadresse bildet Vaultwarden selbst aus <code>DOMAIN</code>.
* Der Anzeigename kommt aus dem Claim <code>preferred_username</code>.
* Vaultwarden speichert die Zuordnung zum Anbieter (<code>iss</code>/<code>sub</code>) separat. Ändert sich später der Anbieter, muss diese Zuordnung zurückgesetzt werden.
* '''Keycloak''' und '''Authentik''': Das Zugriffstoken muss länger als 5 Minuten gelten (z. B. 10 Minuten), sonst kollidiert es mit der Ablaufprüfung der Clients; Scope <code>offline_access</code> ergänzen. Bei Authentik endet <code>SSO_AUTHORITY</code> mit einem Schrägstrich.

=== Schritt 5: Testen und umstellen ===
# Mit einem Testkonto im Web-Tresor ''Single Sign-On verwenden'' wählen.
# Im Log prüfen, ob die Anmeldung ohne Fehler durchläuft; bei Problemen vorübergehend <code>LOG_LEVEL=info,vaultwarden::sso=debug</code>.
# Browser-Erweiterung, Desktop-App und Smartphone testen. Die Desktop-App öffnet für SSO den Browser und erwartet den Rücksprung über das Protokoll <code>bitwarden://</code>; unter Linux mit Firefox braucht das zusätzliche Einstellungen.
# Benutzer informieren und erst danach gegebenenfalls <code>SSO_ONLY=true</code> setzen.

== Hinweise ==
* '''Zwei-Faktor und SSO kombinieren''': Bei SSO greift die MFA des Identitätsanbieters. Ob zusätzlich die Zwei-Faktor-Anmeldung von Vaultwarden verlangt wird, bewusst entscheiden und testen.
* '''Login mit Passkeys''' statt Master-Passwort unterstützt Vaultwarden noch nicht. Passkeys funktionieren aber als zweiter Faktor (FIDO2) und können im Tresor für andere Websites gespeichert werden.
* '''Notfallkonten''': Mindestens ein Administratorkonto behält Master-Passwort-Anmeldung mit FIDO2, damit ein Ausfall des Identitätsanbieters nicht alle aussperrt – mit <code>SSO_ONLY=true</code> ist das nicht möglich, dann ist der Rückweg das Umstellen der Konfiguration.
* Bei der Einführung von Mehr-Faktor-Authentifizierung und Single Sign-On unterstützt Sie das Team [https://www.max-it.de/it-services/cybersecurity/ Cybersecurity von m.a.x. it].

== Siehe auch ==
* [[Vaultwarden]] – Überblick und alle Artikel der Reihe
* [[OpenID Connect]]
* [[Single Sign-On]]
* [[Vaultwarden: Absichern und härten]]

== Links und Quellen ==
* [https://github.com/dani-garcia/vaultwarden/wiki/Enabling-SSO-support-using-OpenId-Connect Vaultwarden-Wiki: Enabling SSO support using OpenID Connect]
* [https://www.max-it.de/it-services/cybersecurity/ Cybersecurity von m.a.x. it]

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