SSD Nodes Learn Hosting plans →
Przewodniki Matt ConnorAutor: Matt Connor

Vaultwarden 2FA: logowanie dwuetapowe krok po kroku

Włącz drugi składnik logowania w Vaultwarden: e-mail, Duo, YubiKey OTP i klucz FIDO2. Konfiguracja SMTP, kod odzyskiwania i zabezpieczenie strony /admin.

Czym jest logowanie dwuetapowe w Vaultwarden

Logowanie dwuetapowe w Vaultwarden, czyli 2FA (uwierzytelnianie dwuskładnikowe), ustawia się w dwóch miejscach naraz. Użytkownik włącza wybraną metodę w sejfie webowym, a administrator serwera zapewnia konfigurację wymaganą przez tę metodę. Gdy pominiesz tę drugą część, część metod nie będzie dostępna, a Ty będziesz szukał błędu w przeglądarce zamiast w pliku docker-compose.yml.

Serwer udostępnia pięć metod: aplikację TOTP (jednorazowy kod oparty na czasie), kod wysyłany e-mailem, Duo, YubiKey OTP oraz klucze FIDO2 WebAuthn. TOTP działa od razu po instalacji. Kod e-mailem wymaga działającej poczty wychodzącej, i to jest miejsce, w którym zatrzymuje się większość osób hostujących samodzielnie. FIDO2 wymaga HTTPS i poprawnego DOMAIN, YubiKey OTP danych usługi walidacyjnej, a Duo można skonfigurować globalnie na serwerze albo osobno dla użytkownika.

Tekst powstał na wersji Vaultwarden 1.37.3, wydanej 13 września 2026. 5 października 2026 ukazała się wersja 1.37.4 z siedmioma poprawkami bezpieczeństwa, w tym jedną dotyczącą logowania dwuetapowego. 1 listopada 2026 wyszła wersja 1.37.5 z dwiema kolejnymi poprawkami bezpieczeństwa. Według jej release notes ta aktualizacja jest potrzebna, żeby sejf webowy w wersji 2026.7.1 lub nowszej mógł włączać i wyłączać metody logowania dwuetapowego, dlatego przykład poniżej używa już jej. Zanim skopiujesz zmienne do siebie, sprawdź numer własnej wersji na stronie /admin, w zakładce „Diagnostics”, w sekcji „Versions” (pole „Server Installed”), i przejrzyj release notes projektu, bo nazwy opcji bywają dodawane i usuwane między wydaniami.

Jednej rzeczy żadna z tych wersji nie robi: nie pozwala zalogować się samym passkey, bez hasła głównego. README projektu wymienia FIDO2 WebAuthn wyłącznie jako drugi składnik po haśle. Materiały o „Login with passkeys” opisują hostowaną usługę Bitwarden, a nie ten serwer. Jeśli planujesz wdrożenie dla zespołu, sprawdź ten punkt w release notes w dniu wdrożenia, a nie w cudzym artykule.

Najpierw kod odzyskiwania, potem drugi składnik

Przy własnym serwerze nie ma infolinii, która zresetuje konto. Jesteś użytkownikiem i pomocą techniczną w jednej osobie, więc kolejność musi być odwrotna niż w usłudze hostowanej: najpierw droga wyjścia, dopiero potem zamek.

Po włączeniu pierwszej metody wejdź w sejfie webowym w Ustawienia, dalej Bezpieczeństwo, dalej Logowanie dwuetapowe, i kliknij „View recovery code”. Ten kod wyłącza wszystkie metody 2FA na koncie, więc traktuj go jak drugie hasło główne. Zapisz go poza sejfem. Kod odzyskiwania trzymany w sejfie, do którego nie możesz się zalogować, nie jest kopią zapasową. Kartka schowana w domu w zupełności wystarczy. Od wersji 1.37.4, przy skonfigurowanej poczcie, serwer wysyła też e-mail po logowaniu kodem odzyskiwania, więc użycie kodu przez kogoś obcego nie przejdzie bez śladu.

Druga droga wyjścia jest po stronie serwera. Na liście użytkowników na stronie /admin, przy koncie z włączonym drugim składnikiem, pojawia się przycisk „Remove all 2FA”. To ratunek na sytuację, w której tracisz telefon i kod odzyskiwania naraz. To także powód, dla którego strona /admin wymaga mocniejszej ochrony niż konto zwykłego użytkownika: kto wejdzie na /admin, ten zdejmuje drugi składnik każdemu w instancji. Wracam do tego niżej.

SMTP, bez którego metoda e-mail nie zadziała

SMTP (simple mail transfer protocol) to protokół poczty wychodzącej. Vaultwarden nie ma własnego serwera pocztowego, ale obsługuje zarówno SMTP, jak i lokalne polecenie sendmail. Metoda „Email” jest domyślnie udostępniana przy włączonej obsłudze poczty i ustawionym SMTP_HOST albo USE_SENDMAIL=true; w obu przypadkach potrzebny jest też SMTP_FROM. Polecenie sendmail musi być dostępne w środowisku, w którym działa Vaultwarden.

services:
  vaultwarden:
    image: vaultwarden/server:1.37.5
    environment:
      DOMAIN: https://sejf.example.pl
      SIGNUPS_ALLOWED: "false"
      SMTP_HOST: smtp.example.pl
      SMTP_FROM: vaultwarden@example.pl
      SMTP_FROM_NAME: Vaultwarden
      SMTP_SECURITY: starttls
      SMTP_PORT: "587"
      SMTP_USERNAME: vaultwarden@example.pl
      SMTP_PASSWORD: tajne-haslo

Zmienna SMTP_SECURITY przyjmuje trzy wartości i każda ma swój domyślny port, który można zmienić przez SMTP_PORT. starttls to wartość domyślna z portem 587, czyli port submission, na którym połączenie zaczyna się jawnie i dopiero potem przechodzi na szyfrowane. force_tls to szyfrowanie od pierwszego pakietu, zwykle na porcie 465. off wyłącza szyfrowanie i domyślnie używa portu 25. Jeśli ustawisz force_tls i zostawisz port 587, wysyłka się nie uda: Vaultwarden od razu po połączeniu próbuje uzgodnić TLS (transport layer security), a serwer na porcie 587 oczekuje jawnej rozmowy SMTP. Biblioteka lettre, której używa Vaultwarden, przerywa połączenie, gdy uzgadnianie TLS się nie powiedzie, zanim wyśle jakiekolwiek dane logowania, więc błąd może pojawić się od razu. Nie zakładaj, że zobaczysz wyłącznie przekroczony limit czasu z SMTP_TIMEOUT.

Adres z SMTP_FROM musi być nadawcą, którego Twój dostawca poczty akceptuje dla podanego loginu. Większość dostawców odrzuca wiadomość, gdy adres nadawcy nie zgadza się z kontem, więc uwierzytelnienie przechodzi, a wysyłka i tak się nie udaje.

Sprawdzenie jest wbudowane. Na stronie /admin, w sekcji ustawień SMTP, jest pole „Enter test email” i przycisk „Send test email”. Wpisz swój adres i wyślij. Wiadomość powinna dojść w kilkanaście sekund. Gdy nie dochodzi, ustaw tymczasowo SMTP_DEBUG: "true", zrestartuj kontener i powtórz próbę: w logu pojawi się wtedy pełna rozmowa z serwerem poczty, razem z odpowiedzią, która kończy sprawę. Po skończonej diagnostyce wyłącz tę opcję, bo log robi się bardzo obszerny i może zawierać dane logowania do poczty.

Jedna pułapka kolejności. Ustawienia zapisane przez formularz na /admin trafiają do pliku data/config.json i mają pierwszeństwo przed zmiennymi środowiskowymi. Jeśli raz zapiszesz SMTP przez panel, a potem poprawisz hasło w docker-compose.yml, serwer dalej będzie używał starej wartości z config.json. Wybierz jedno miejsce konfiguracji i trzymaj się go.

Aplikacja TOTP i kod e-mailem: dwie metody bez sprzętu

TOTP to metoda domyślna i najmniej kłopotliwa. Użytkownik skanuje kod QR aplikacją w telefonie i przepisuje sześć cyfr. Po stronie serwera nie trzeba ustawiać niczego. Warunkiem poprawnego działania jest zgodny czas: TOTP liczy kody z zegara, więc serwer z zegarem rozjechanym o minutę zacznie odrzucać poprawne kody. Na VPS-ie pilnuje tego zwykle systemd-timesyncd albo chrony, i warto to sprawdzić przed włączeniem 2FA dla wszystkich.

Metoda e-mail wysyła jednorazowy kod na adres wybrany podczas jej włączania. Jej zachowanie regulują cztery zmienne: EMAIL_TOKEN_SIZE (domyślnie 6 cyfr), EMAIL_EXPIRATION_TIME (600 sekund), EMAIL_ATTEMPTS_LIMIT (3 próby) oraz EMAIL_2FA_AUTO_FALLBACK. Ostatnia z nich, ustawiona na true, automatycznie konfiguruje e-mail jako zapasową metodę 2FA, gdy jest potrzebna. Wydłużanie EMAIL_EXPIRATION_TIME kuszące bywa przy wolnej poczcie, ale każda dodatkowa minuta to dłuższe okno, w którym kod z przechwyconej skrzynki wciąż działa.

E-mail jako jedyny drugi składnik ma słabość, którą trzeba nazwać wprost: kto ma dostęp do skrzynki, ten ma drugi składnik. Jeśli skrzynka jest chroniona tym samym hasłem, co sejf, to nie dołożyłeś warstwy, tylko ją narysowałeś. Dla konta administratora wybierz klucz sprzętowy albo TOTP.

Klucz FIDO2 WebAuthn, czyli klucz sprzętowy

FIDO2 WebAuthn obsługuje fizyczne klucze USB lub NFC, w tym Nitrokey i SoloKey, a także uwierzytelniacze wbudowane w urządzenie, takie jak Windows Hello. Z punktu widzenia odporności na phishing jest najlepsza z całej piątki, bo klucz podpisuje wyłącznie dla domeny, dla której został zarejestrowany. Fałszywa strona podszywająca się pod Twój sejf nie dostanie poprawnego podpisu, nawet gdy użytkownik da się nabrać.

Po stronie serwera wymagane są HTTPS z ważnym certyfikatem oraz poprawnie ustawiona zmienna DOMAIN, z prefiksem https:// i z portem na końcu, gdy nie używasz 443. HTTPS skonfigurujesz w Vaultwardenie albo na reverse proxy.

DOMAIN=https://sejf.example.pl

Witryna musi być podawana po HTTPS z ważnym certyfikatem, bo przeglądarki udostępniają API WebAuthn tylko w bezpiecznym kontekście. Domena, protokół i port w pasku przeglądarki muszą odpowiadać konfiguracji DOMAIN. Nazwa domeny z DOMAIN staje się identyfikatorem, do którego klucz przywiązuje poświadczenie, więc późniejsza zmiana domeny sejfu wymaga ponownej rejestracji kluczy. Przenosisz instancję na nową domenę? Zaplanuj ponowną rejestrację kluczy, zanim wyłączysz starą, albo trzymaj kody odzyskiwania pod ręką.

Zarejestruj dwa klucze na konto: jeden noszony przy kluczach do domu, drugi zamknięty w szufladzie. Klucz sprzętowy można zgubić, a konto z jednym kluczem i bez kodu odzyskiwania wymaga wtedy interwencji administratora.

YubiKey OTP

YubiKey OTP to starszy mechanizm, w którym klucz po dotknięciu wpisuje długi ciąg znaków, a serwer weryfikuje go domyślnie w usłudze walidacyjnej YubiCloud. Jest to metoda inna niż FIDO2, mimo że urządzenie bywa to samo.

YUBICO_CLIENT_ID=11111
YUBICO_SECRET_KEY=AAAAAAAAAAAAAAAAAAAAAAAA

Para kluczy API pochodzi ze strony https://upgrade.yubico.com/getapikey/. Jeżeli Twój YubiKey został przeprogramowany i korzystasz z YubiCloud, musi być jeszcze zarejestrowany pod adresem https://upload.yubico.com/, inaczej walidacja zwróci błąd mimo poprawnej konfiguracji. Opcjonalna zmienna YUBICO_SERVER wskazuje własny serwer walidacyjny. Gdy jej nie podasz, używane są domyślne serwery YubiCloud.

Z tego wynika warunek, o którym łatwo zapomnieć: Twój VPS musi mieć łączność z wybranym serwerem walidacyjnym, a przy domyślnym YubiCloud wyjście na świat po HTTPS. Serwer odcięty regułą wychodzącą zapory od usługi walidacyjnej odrzuci poprawny YubiKey, bo nie ma jak zapytać o jego ważność. YubiCloud jest stroną trzecią przy konfiguracji domyślnej; własny serwer wskazany przez YUBICO_SERVER usuwa tę zależność, podczas gdy FIDO2 weryfikujesz całkowicie u siebie.

Duo

Duo to zewnętrzna usługa z powiadomieniem push na telefon, sensowna głównie tam, gdzie firma już jej używa. W panelu Duo tworzysz aplikację i przenosisz z niej trzy wartości.

DUO_IKEY=<Client ID>
DUO_SKEY=<Client Secret>
DUO_HOST=<API Hostname>

Vaultwarden korzysta z nowego okna logowania Duo. Zmienna DUO_USE_IFRAME, która we wcześniejszych wydaniach przywracała przestarzały tryb „Traditional Prompt” oparty na iframe, została usunięta w wersji 1.37.4 i jest ignorowana, nawet jeśli zostanie ustawiona. Jeśli masz ją w starej konfiguracji, po prostu ją skasuj. Uwierzytelnienie przez Duo wymaga łączności serwera z usługą zewnętrzną, więc jej awaria blokuje tę metodę; dostęp odzyskasz inną włączoną metodą albo kodem odzyskiwania.

Czy warto: za część tych metod w Bitwardenie się płaci

Dla osoby, która porównywała cenniki, obraz jest prosty. W hostowanym Bitwardenie TOTP, kod e-mailem i klucze sprzętowe FIDO2 WebAuthn są dostępne za darmo (konto darmowe może zarejestrować do 5 kluczy, konto Premium do 10). YubiKey OTP i Duo należą natomiast do planu Premium, który (stan na 3 listopada 2026) kosztuje 1,65 USD miesięcznie przy płatności rocznej, czyli 19,80 USD rocznie za użytkownika. Twój własny serwer daje wszystkie te metody bez osobnej opłaty, dla każdego konta w instancji.

Rachunek nie jest jednak zerowy, tylko przesunięty. Płacisz czasem: za SMTP, za aktualizacje obrazu, za kopie zapasowe i za bycie własną pomocą techniczną o drugiej w nocy. Jeśli ważysz te dwie strony, porównanie obu podejść rozwija zestawienie Vaultwardena z oficjalnym serwerem Bitwarden, a samą instalację od zera opisuje przewodnik po uruchomieniu menedżera haseł na własnym VPS-ie. Dla jednej osoby i dla rodziny rachunek zwykle wychodzi na korzyść własnego serwera. Dla firmy bez dyżuru administratora, zwykle nie.

Strona /admin to osobne drzwi, bez drugiego składnika

To najważniejszy fragment tego tekstu. Strona /admin nie korzysta z kont użytkowników i nie ma żadnego drugiego składnika. Chroni ją wyłącznie wartość ADMIN_TOKEN. Kto ją pozna, ten zobaczy listę kont, wyłączy 2FA każdemu i zmieni konfigurację serwera.

Dokumentacja projektu zaleca, żeby nie trzymać tam zwykłego hasła, tylko skrót w formacie PHC wygenerowany algorytmem Argon2id. Vaultwarden ma do tego wbudowane polecenie.

docker run --rm -it vaultwarden/server /vaultwarden hash

Polecenie zapyta o hasło i wypisze ciąg zaczynający się od $argon2id$v=19$m=65540,t=3,p=4$. Ten ciąg wstawiasz jako ADMIN_TOKEN, a przy logowaniu na /admin wpisujesz hasło, nie skrót.

Tu czeka pułapka, na której potyka się wiele osób. Znak $ ma znaczenie dla Docker Compose. W pliku .env wpisz skrót w apostrofach i nie zmieniaj niczego. W docker-compose.yml musisz podwoić każde wystąpienie $ na $$, inaczej Compose podstawi puste zmienne i token nie zadziała; pojawią się też ostrzeżenia interpolacji, na przykład WARNING: The argon2id variable is not set. Defaulting to a blank string.

ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$...'

Warto dołożyć trzy ograniczenia. ADMIN_RATELIMIT_SECONDS i ADMIN_RATELIMIT_MAX_BURST spowalniają zgadywanie tokenu, a ADMIN_SESSION_LIFETIME (domyślnie 20 minut) skraca czas życia zalogowanej sesji panelu. Zmienna DISABLE_ADMIN_TOKEN ustawiona na true otwiera panel każdemu, kto zna adres, więc ma sens wyłącznie wtedy, gdy przed Vaultwardenem stoi inny mechanizm uwierzytelnienia. Jeśli panel nie jest Ci potrzebny na co dzień, najlepszą ochroną jest jego brak: usuń ADMIN_TOKEN, nie ustawiaj DISABLE_ADMIN_TOKEN i upewnij się, że w data/config.json nie ma klucza admin_token. Alternatywnie zostaw panel wyłącznie w sieci prywatnej, na przykład wystawiając sejf przez tunel Cloudflare bez otwierania portów na VPS-ie i blokując tam ścieżkę /admin.

Ustawienia, które warto zmienić przy okazji

  • SIGNUPS_ALLOWED=false zamyka rejestrację, żeby ktoś obcy nie założył konta na Twoim serwerze. Nowych użytkowników dodajesz wtedy zaproszeniem.
  • DISABLE_2FA_REMEMBER=true wyłącza działanie opcji „zapamiętaj to urządzenie”, przez którą drugi składnik znika domyślnie na kolejne 30 dni; pole wyboru pozostaje widoczne, ale serwer je ignoruje. Od wersji 1.37.5 możesz zamiast tego skrócić ten okres zmienną TWO_FACTOR_REMEMBER_DAYS (od 1 do 90 dni).
  • INCOMPLETE_2FA_TIME_LIMIT=3 wysyła powiadomienie e-mail, gdy ktoś poda poprawne hasło główne, ale nie dokończy drugiego kroku. To najwcześniejszy sygnał, że Twoje hasło główne wyciekło. Ta opcja działa tylko przy skonfigurowanej poczcie wychodzącej przez SMTP albo sendmail, co jest kolejnym argumentem, żeby zająć się pocztą najpierw.
  • EMAIL_2FA_ENFORCE_ON_VERIFIED_INVITE=true automatycznie włącza e-mail jako drugi składnik przy rejestracji z potwierdzonym adresem e-mail, niezależnie od polityki organizacji.

Czego logowanie dwuetapowe nie chroni

Drugi składnik chroni logowanie, czyli moment, w którym ktoś rozmawia z Twoim serwerem. Nie chroni kopii katalogu data, którą ktoś wyniósł z serwera albo z Twojego backupu. Taka kopia nigdy nie przechodzi przez ekran logowania, więc żadna z pięciu metod jej nie dotyczy.

O bezpieczeństwie wyniesionej kopii decyduje co innego: siła hasła głównego i parametry funkcji KDF, z której wyprowadzany jest klucz szyfrujący sejf. Mechanizm szyfrowania po stronie klienta i to, co realnie widzi serwer, rozkłada na części analiza bezpieczeństwa samego Vaultwardena. Drugą połową tej samej rozmowy są kopie zapasowe, bo plik db.sqlite3 skopiowany w trakcie zapisu potrafi być nie do odtworzenia; poprawną procedurę opisuje instrukcja tworzenia i odtwarzania kopii zapasowej Vaultwardena. Włączone 2FA bez sprawdzonego odtworzenia backupu to dwa zamki w drzwiach postawionych na piasku.

Co najczęściej nie działa

Metoda „Email” nie pojawia się na liście. Sprawdź, czy obsługa poczty i e-mailowego 2FA jest włączona oraz czy skonfigurowano SMTP_HOST albo USE_SENDMAIL=true. Wyślij wiadomość testową z /admin, a przy SMTP sprawdź log kontenera przy włączonym SMTP_DEBUG.

Klucz FIDO2 nie chce się zarejestrować. Sejf jest otwarty po HTTP, certyfikat jest nieważny, albo adres w pasku przeglądarki różni się od wartości DOMAIN. Wystarczy www z jednej strony i brak www z drugiej.

Klucze przestały działać po przeprowadzce. Zmiana nazwy domeny w DOMAIN wymaga ponownej rejestracji poświadczeń WebAuthn. Zaloguj się kodem odzyskiwania i zarejestruj klucze ponownie.

Poprawne kody TOTP są odrzucane. Zegar serwera się rozjechał. Sprawdź synchronizację czasu na VPS-ie, zanim zaczniesz podejrzewać aplikację w telefonie.

Token panelu /admin nie działa mimo poprawnego hasła. Skrót Argon2 trafił do docker-compose.yml bez podwojenia znaków $.

Zmiana w docker-compose.yml nie przynosi skutku. Wartość została wcześniej zapisana przez panel i siedzi w data/config.json, który ma pierwszeństwo.

FAQ

Czy Vaultwarden pozwala zalogować się samym passkey, bez hasła głównego?

Nie w wersji 1.37.5 z 1 listopada 2026 ani we wcześniejszych 1.37.4 i 1.37.3. README projektu wymienia FIDO2 WebAuthn wyłącznie jako drugi składnik, używany po podaniu hasła głównego. Logowanie bez hasła, znane z hostowanego Bitwardena jako „Login with passkeys”, nie jest w tym serwerze funkcją dostępną. Przed wdrożeniem sprawdź release notes swojej wersji, bo to się może zmienić.

Włączyłem 2FA i zgubiłem telefon. Jak odzyskać dostęp do sejfu?

Użyj kodu odzyskiwania zapisanego przy włączaniu metody: wyłącza on wszystkie metody 2FA na koncie i wpuszcza Cię samym hasłem głównym. Jeżeli kodu nie masz, zaloguj się na stronę /admin i kliknij „Remove all 2FA” przy swoim koncie. Gdy nie masz ani kodu, ani tokenu do panelu, ale masz dostęp administracyjny do serwera, ustaw nowy ADMIN_TOKEN, uwzględniając pierwszeństwo data/config.json, odtwórz kontener i usuń 2FA przez panel.

Dlaczego metoda e-mail nie pojawia się wśród dostępnych opcji?

Vaultwarden udostępnia tę metodę domyślnie przy włączonej obsłudze poczty i skonfigurowanym SMTP_HOST albo USE_SENDMAIL=true. Przy SMTP ustaw SMTP_HOST, SMTP_FROM, SMTP_SECURITY i SMTP_PORT; przy sendmail ustaw USE_SENDMAIL=true oraz SMTP_FROM i zapewnij dostępność polecenia w środowisku serwera. Zrestartuj kontener, a potem wyślij wiadomość testową przyciskiem „Send test email” na stronie /admin. Udany test potwierdza wysyłkę, ale nie jest warunkiem wyświetlenia metody.

Czy strona /admin ma własne logowanie dwuetapowe?

Nie ma żadnego. Panel administracyjny chroni wyłącznie ADMIN_TOKEN, dlatego wpisz tam skrót Argon2id wygenerowany poleceniem docker run --rm -it vaultwarden/server /vaultwarden hash, a nie zwykłe hasło. Ogranicz też tempo prób zmiennymi ADMIN_RATELIMIT_SECONDS i ADMIN_RATELIMIT_MAX_BURST. Jeśli panel nie jest Ci potrzebny na co dzień, usuń ADMIN_TOKEN i klucz admin_token z data/config.json, nie ustawiaj DISABLE_ADMIN_TOKEN, a następnie odtwórz kontener, żeby wyłączyć tę stronę całkowicie.

Która metoda 2FA jest najlepsza dla konta administratora?

Klucz FIDO2 WebAuthn, bo jako jedyny wiąże podpis z domeną i przez to odrzuca stronę podszywającą się pod Twój sejf. Zarejestruj dwa klucze, jeden noszony i jeden zapasowy. Kod e-mailem zostaw jako metodę dla mniej wrażliwych kont: kto przejmie skrzynkę pocztową, ten przejmuje także ten drugi składnik.

Czy ten artykuł był przydatny?