Podłącz aplikacje Bitwarden do własnego Vaultwarden

Co ustawiasz, żeby aplikacje Bitwarden zobaczyły Vaultwarden

Oficjalne aplikacje Bitwarden łączą się z Vaultwarden po wpisaniu adresu Twojego serwera w pole Server URL na ekranie logowania. Podajesz go przed e-mailem i hasłem, a nie po zalogowaniu. Po stronie serwera muszą być spełnione dwa warunki: publicznie zaufany certyfikat TLS (transport layer security) dostępny po HTTPS oraz ustawienie DOMAIN równe dokładnie temu adresowi, z którego korzystają klienci.

Trzecia rzecz zaskakuje najczęściej. Konto z bitwarden.com nie jest tym samym kontem co konto na Twoim serwerze. Nie ma logowania krzyżowego między chmurą a Vaultwarden, więc przeniesienie danych to eksport i import, a nie zalogowanie się w nowym miejscu.

Ten poradnik zakłada, że serwer już działa. Jeśli jeszcze nie, wróć do instalacji Vaultwarden na VPS w kontenerze Dockera i dopiero potem konfiguruj klienty.

Dlaczego adres serwera podajesz przed logowaniem

Aplikacja musi wiedzieć, gdzie wysłać żądanie logowania, zanim je wyśle. Domyślnie wysyła je do chmury Bitwardena, czyli do regionu US albo EU. Twojego e-maila i hasła głównego w tej bazie nie ma, więc logowanie zostaje odrzucone, chociaż dane są poprawne dla Twojego serwera. Objaw wygląda jak zły login, a przyczyną jest zły adres serwera. Po zalogowaniu pola adresu już nie zobaczysz, bo każde konto w aplikacji jest przypisane do serwera, na którym zostało dodane.

Dla Vaultwarden wypełniasz tylko pole bazowego adresu. Klienty Bitwardena pozwalają dodatkowo podać osobne adresy dla API, identity, web vault, ikon, powiadomień i zdarzeń. Vaultwarden obsługuje wszystkie te ścieżki pod jednym adresem, więc te pola zostaw puste. Wypełnione po części są częstą przyczyną sytuacji, w której logowanie działa, a synchronizacja lub ikony nie.

Android i iOS: pole Server URL na ekranie logowania

Zainstaluj aplikację Bitwarden ze sklepu Google Play albo App Store, uruchom ją i nie loguj się od razu.

1. Na ekranie logowania rozwiń listę opisaną jako Logging in on.
2. Wybierz opcję Self-hosted.
3. W polu Server URL wpisz pełny adres z przedrostkiem https://, na przykład https://vault.example.com.
4. Zapisz ustawienie przyciskiem Save.
5. Dopiero teraz podaj e-mail i hasło główne konta z Twojego serwera.

Adres wpisz dokładnie tak, jak działa w przeglądarce, razem z podkatalogiem, jeśli trzymasz Vaultwarden pod ścieżką. Bez https:// aplikacja nie ma jak zbudować poprawnego żądania. Ekran konfiguracji ma też pole na certyfikat klienta. Służy ono do uwierzytelniania urządzenia przed serwerem i nie sprawia, że telefon zaufa Twojemu własnemu certyfikatowi serwera.

Rozszerzenie do przeglądarki

Rozszerzenie ma ten sam mechanizm. Otwórz je, na ekranie logowania rozwiń listę Logging in on, wybierz Self-hosted, wpisz adres z https:// i zapisz. Ustawienie zapisuje się w tej konkretnej instalacji rozszerzenia, więc drugi profil przeglądarki i drugi komputer konfigurujesz osobno.

Sam web vault konfiguruje się sam. Vaultwarden podaje własną kopię interfejsu webowego pod tym samym adresem, więc wystarczy otworzyć https://vault.example.com i zalogować się tam. Jeżeli interfejs webowy działa, a rozszerzenie nie, to prawie zawsze znaczy, że rozszerzenie nadal celuje w chmurę.

Aplikacja desktopowa i klient CLI

W aplikacji na Windows, macOS i Linuxa lista na ekranie logowania nazywa się Accessing. Wybierz Self-hosted, wpisz adres, zapisz, potem zaloguj się. Każde konto dodane w aplikacji może wskazywać inny serwer, więc konto firmowe w chmurze i konto prywatne na Twoim VPS mogą stać obok siebie.

Klient wiersza poleceń ustawia się jedną komendą przed pierwszym logowaniem:

bw config server https://vault.example.com
bw login
bw sync

bw config server zapisuje adres w lokalnej konfiguracji klienta. Jeśli pomylisz kolejność i najpierw wywołasz bw login, klient spróbuje uwierzytelnić się w chmurze. Wyloguj się wtedy przez bw logout, ustaw adres i zaloguj ponownie.

Konto z bitwarden.com to inne konto niż konto na Twoim serwerze

Konto żyje w bazie danych tego serwera, na którym je założono. Klucz szyfrujący sejf powstaje z hasła głównego i adresu e-mail, a jego zaszyfrowana kopia leży w tej samej bazie. Twój Vaultwarden nie ma dostępu do bazy Bitwardena, więc nie może sprawdzić Twojego hasła z chmury ani odszyfrować tamtego sejfu. Dlatego przenosisz dane, a nie konto.

Kolejność jest taka. W chmurowym web vault wejdź w Tools i wyeksportuj sejf do pliku .json. Wybierz eksport zwykły albo chroniony hasłem. Eksport szyfrowany kluczem konta odczyta tylko to samo konto, więc do przenosin się nie nadaje. Następnie założ konto na swoim serwerze, zaloguj się w jego web vault, wejdź w Tools oraz Import data, jako format wskaż eksport Bitwardena i wczytaj plik. Przy pliku chronionym hasłem klient poprosi o to hasło w okienku potwierdzenia importu.

Dwie rzeczy do zapamiętania. Eksport sejfu nie zawiera załączników ani wysłanych elementów Send, więc pliki dopięte do wpisów pobierz i dodaj ręcznie. Plik eksportu to Twoje hasła w postaci czytelnej lub łatwej do odszyfrowania, więc usuń go z dysku zaraz po zakończeniu importu. Jeżeli ważysz jeszcze, czy zostać przy chmurze, porównanie Vaultwarden z oficjalnym serwerem Bitwarden rozkłada różnice w funkcjach i obowiązkach.

Certyfikat TLS: dlaczego certyfikat własny nie przejdzie na telefonie

Klienty Bitwardena wymagają połączenia po HTTPS z certyfikatem, któremu urządzenie ufa domyślnie. Wiki Vaultwarden mówi o tym wprost i zaleca Let's Encrypt, bo część platform certyfikatów podpisanych samodzielnie nie dopuszcza. Na telefonie to widać najszybciej: przeglądarka na laptopie pozwoli Ci kliknąć ostrzeżenie i wejść dalej, a aplikacja mobilna po prostu nie połączy się i nie da Ci żadnego wyjątku do zaakceptowania.

Najprostsza droga to nazwa domenowa wskazująca na VPS i certyfikat z Let's Encrypt, czyli certbot razem z nginx na Ubuntu 24.04. Jeśli nie chcesz otwierać portów na świat, tunel Cloudflare bez otwartych portów też daje publicznie zaufany certyfikat na krawędzi. Własne CA (certificate authority) ma sens w sieci, którą kontrolujesz w całości, i możesz dodać własne CA do magazynu zaufania Ubuntu, ale telefony ze sklepowymi aplikacjami zostaną z tym problemem, więc dla klientów mobilnych to droga w ślepą uliczkę.

Sprawdź z zewnątrz, czy serwer podaje cały łańcuch certyfikatów, a nie tylko swój certyfikat:

echo | openssl s_client -connect vault.example.com:443 -servername vault.example.com -showcerts 2>/dev/null | grep -E "subject=|issuer="

Powinieneś zobaczyć swój certyfikat oraz certyfikat pośredni wystawcy. Brak pośredniego to klasyczna sytuacja, w której przeglądarka na komputerze radzi sobie sama, bo ma ten certyfikat w pamięci, a telefon odrzuca połączenie.

DOMAIN musi być dokładnie tym adresem, z którego korzystają klienty

DOMAIN to bazowy adres Twojej instancji. Dokumentacja Vaultwarden ostrzega, że przy złym ustawieniu część funkcji przestaje działać w sposób trudny do powiązania z przyczyną. Vaultwarden używa tej wartości do rejestracji drugiego składnika WebAuthn i kluczy passkey, do kanału powiadomień oraz do linków w wiadomościach e-mail. Klucz bezpieczeństwa zarejestrowany dla jednego pochodzenia nie zadziała dla innego, więc gdy DOMAIN mówi https://vault.example.com, a użytkownicy wchodzą przez https://bitwarden.example.com, rejestracja klucza się nie uda, chociaż logowanie hasłem działa.

Wartości poprawne to na przykład https://vault.example.com, https://vault.example.com:8443 przy niestandardowym porcie oraz https://example.com/vaultwarden/ przy hostowaniu pod ścieżką. Fragment pliku compose dla istniejącej instalacji wygląda tak:

services:
  vaultwarden:
    image: vaultwarden/server:latest
    environment:
      DOMAIN: "https://vault.example.com"
      SIGNUPS_ALLOWED: "false"
      PUSH_ENABLED: "true"
      PUSH_INSTALLATION_ID: "twoje-id"
      PUSH_INSTALLATION_KEY: "twoj-klucz"

Po zmianie zmiennych kontener trzeba odtworzyć, bo środowisko ustawia się przy starcie. W produkcji przypnij konkretną wersję obrazu zamiast latest, żeby aktualizacja odbywała się wtedy, kiedy Ty ją uruchamiasz.

Reverse proxy: WebSocket i rozmiar załącznika

Synchronizacja na żywo w przeglądarce i w aplikacji desktopowej jedzie po WebSocket pod ścieżką /notifications/hub. Od wersji 1.29.0 WebSocket jest włączony domyślnie, stare WEBSOCKET_ENABLED i WEBSOCKET_PORT są ignorowane, a wersja 1.31.0 usunęła osobny port 3012 i przeniosła ten ruch na główny port HTTP. Wyłącza się to przez ENABLE_WEBSOCKET=false, czego zwykle nie chcesz.

Twoje zadanie po stronie proxy to przepuścić nagłówki podniesienia połączenia i podnieść limit rozmiaru żądania dla załączników:

map $http_upgrade $connection_upgrade {
  default upgrade;
  ""      close;
}

server {
  listen 443 ssl;
  server_name vault.example.com;
  client_max_body_size 525M;

  location / {
    proxy_pass http://127.0.0.1:8080;
    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;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
  }
}

Linie z certyfikatem pominąłem, bo zwykle wstawia je certbot. Bez pary nagłówków Upgrade i Connection logowanie i ręczna synchronizacja działają normalnie, a zmiany po prostu nie pojawiają się same w drugiej przeglądarce. Jeśli ta konfiguracja jest dla Ciebie nowa, wyjaśnienie konfiguracji reverse proxy w nginx tłumaczy, co robi każda z tych dyrektyw.

Powiadomienia push na własnym serwerze

Telefon nie trzyma otwartego WebSocketa, bo system usypia aplikacje w tle. Android korzysta z FCM, iOS z APNs, a do obu prowadzi droga przez infrastrukturę Bitwardena. Dlatego Vaultwarden wymaga rejestracji instalacji: podajesz swój e-mail na stronie https://bitwarden.com/host/ i dostajesz identyfikator oraz klucz instalacji.

PUSH_ENABLED=true
PUSH_INSTALLATION_ID=twoje-id
PUSH_INSTALLATION_KEY=twoj-klucz

Jeśli Twoje konto instalacji jest w regionie europejskim, dodaj jeszcze dwie zmienne, bo domyślnie Vaultwarden mówi do bramki amerykańskiej:

PUSH_RELAY_URI=https://api.bitwarden.eu
PUSH_IDENTITY_URI=https://identity.bitwarden.eu

Cztery warunki, o których mówi wiki. Push wymaga Vaultwarden w wersji 1.30.2 lub nowszej. Działa tylko z aplikacjami ze sklepów, czyli Google Play, App Store i zgodnych z nimi (Aurora Store); wersje z F-Droid czy Neo Store nie mają obsługi Firebase Messaging, więc żadne powiadomienie do nich nie dotrze. Telefon musi mieć dostęp do firebaseinstallations.googleapis.com, co bywa zablokowane przez filtry DNS. Po włączeniu push na serwerze każdy użytkownik musi się wylogować i zalogować ponownie, żeby aplikacja zarejestrowała token, a przy uporczywym braku powiadomień pomaga czyszczenie danych aplikacji albo jej ponowna instalacja.

Włączenie push oznacza, że powiadomienie o zmianie wychodzi z Twojego serwera przez bramkę Bitwardena do Google albo Apple. Sam sejf nadal pobiera się z Twojego VPS po TLS, ale ten dodatkowy kanał to świadomy wybór, a nie detal. Jeśli chcesz go rozważyć na spokojnie, analiza bezpieczeństwa Vaultwarden i jego modelu zagrożeń omawia, co wychodzi poza Twój serwer i dlaczego.

Co robi natychmiastowa synchronizacja bez push, a czego nie robi

Bez push nic nie ginie, tylko przychodzi później. Przeglądarka, rozszerzenie i aplikacja desktopowa i tak dostają zmiany na żywo, bo używają WebSocketa na głównym porcie. Telefon bez push synchronizuje się przy otwarciu aplikacji oraz na żądanie, przez opcję synchronizacji w ustawieniach sejfu. Wpis dodany na laptopie pojawi się więc na telefonie po jego uruchomieniu, a nie w tej samej sekundzie.

Co to znaczy w praktyce. Jeśli zmieniasz hasło na komputerze i od razu chcesz je wkleić na telefonie, wymuś synchronizację, zanim uznasz, że Vaultwarden zgubił zmianę. Jeśli odbierasz komuś dostęp do organizacji, pamiętaj, że urządzenie z sejfem w pamięci lokalnej dowie się o tym przy następnej synchronizacji.

Jak zaprosić kogoś, gdy rejestracja jest wyłączona

Publiczny serwer trzymaj z SIGNUPS_ALLOWED=false, bo inaczej konto założy każdy, kto zna adres. To ustawienie nie blokuje zapraszania. Administrator lub właściciel organizacji może zaprosić użytkownika, a zaproszony adres e-mail może się zarejestrować, mimo że rejestracja jest wyłączona. INVITATIONS_ALLOWED=false wyłącza tę drogę całkowicie.

Zaproszenie idzie e-mailem, więc wymaga skonfigurowanego SMTP. Link z zaproszenia jest ważny pięć dni, po czym trzeba wysłać nowe. Bez SMTP żadna wiadomość z serwera nie wyjdzie, więc masz dwie sensowne opcje: skonfigurować SMTP, albo na czas rejestracji ustawić SIGNUPS_ALLOWED=true razem z SIGNUPS_DOMAINS_WHITELIST ograniczonym do Twojej domeny i wyłączyć to zaraz po założeniu konta. Stan użytkowników sprawdzisz na stronie /admin, chronionej przez ADMIN_TOKEN.

Objaw i co sprawdzić

• Logowanie działa w przeglądarce, a na telefonie nie: sprawdź, jaki adres ma aplikacja, bo prawdopodobnie stoi na Self-hosted z literówką albo wróciła do regionu chmury.
• Aplikacja przyjmuje adres, ale hasło jest odrzucane: sprawdź, czy to konto faktycznie istnieje na Twoim serwerze, a nie tylko w chmurze.
• Telefon nie łączy się, laptop tak: sprawdź łańcuch certyfikatów komendą openssl s_client z zewnątrz sieci domowej.
• Rejestracja klucza passkey lub WebAuthn się nie kończy: porównaj DOMAIN z adresem w pasku przeglądarki, znak po znaku, razem ze schematem i portem.
• Zmiany nie pojawiają się same w rozszerzeniu: sprawdź w proxy nagłówki Upgrade i Connection dla ruchu na /notifications/hub.
• Telefon nie dostaje powiadomień: sprawdź zmienne PUSH_*, wersję Vaultwarden i to, czy aplikacja pochodzi ze sklepu.
• Załącznik nie chce się wgrać: sprawdź client_max_body_size w nginx, bo domyślny limit jest o rzędy wielkości mniejszy.

Zanim uznasz, że działa

Zaloguj się na telefonie przez dane komórkowe, z wyłączonym Wi-Fi. To jedyny test, który potwierdza publiczny DNS i zaufany certyfikat naraz, bo w sieci domowej możesz trafiać na serwer inną drogą. Potem dodaj wpis na telefonie, zsynchronizuj sejf na komputerze i sprawdź, że wpis jest. Włącz drugi składnik uwierzytelnienia i zaloguj się od nowa w innej przeglądarce, żeby sprawdzić, że DOMAIN jest ustawiony poprawnie.

Na końcu zadbaj o kopię. Sejf, który masz w czterech aplikacjach, nadal istnieje w jednym miejscu, czyli w bazie na Twoim VPS, a kopia zapasowa i odtworzenie Vaultwarden zajmuje mniej czasu niż konfiguracja klientów, którą właśnie skończyłeś.

FAQ

Czy mogę zalogować się do Vaultwarden kontem z bitwarden.com?

Nie. Konto istnieje tylko w bazie tego serwera, na którym je założono, a klucz szyfrujący sejf powstaje z hasła głównego i adresu e-mail. Twój Vaultwarden nie ma dostępu do bazy chmury, więc nie sprawdzi tamtego hasła. Wyeksportuj sejf z chmury do pliku .json, założ konto na swoim serwerze i wczytaj plik przez Tools oraz Import data w interfejsie webowym. Załączników eksport nie zawiera, więc pliki dopięte do wpisów przenieś ręcznie.

Dlaczego aplikacja na telefonie nie łączy się z serwerem, a komputer łączy się bez problemu?

Najczęściej z powodu certyfikatu. Przeglądarka na komputerze pozwala zaakceptować ostrzeżenie i zapamiętuje brakujące certyfikaty pośrednie, a aplikacja mobilna nie daje żadnego wyjątku i po prostu przerywa połączenie. Użyj certyfikatu od publicznie zaufanego wystawcy, na przykład Let's Encrypt, i sprawdź pełny łańcuch przez echo | openssl s_client -connect vault.example.com:443 -servername vault.example.com -showcerts. Druga częsta przyczyna to adres w polu Server URL bez przedrostka https:// albo wskazujący na adres widoczny tylko w sieci lokalnej.

Czy powiadomienia push są konieczne, żeby synchronizacja działała?

Nie. Bez push sejf nadal synchronizuje się w całości, tylko nie natychmiast: aplikacja mobilna pobiera zmiany przy otwarciu i na żądanie z ustawień. Przeglądarka i aplikacja desktopowa dostają zmiany na żywo przez WebSocket na głównym porcie serwera, o ile reverse proxy przepuszcza nagłówki Upgrade i Connection. Push dokładasz wtedy, gdy chcesz, żeby telefon reagował od razu, a wymaga to identyfikatora i klucza instalacji ze strony https://bitwarden.com/host/ oraz aplikacji ze oficjalnego sklepu.

Jak dodać drugą osobę, gdy rejestracja na serwerze jest wyłączona?

Przy SIGNUPS_ALLOWED=false administrator lub właściciel organizacji nadal może zaprosić użytkownika, a zaproszony adres e-mail zarejestruje się pomimo wyłączonej rejestracji. Zaproszenie wychodzi e-mailem i jego link jest ważny pięć dni, więc potrzebujesz skonfigurowanego SMTP. Jeśli SMTP nie masz, włącz rejestrację na chwilę razem z SIGNUPS_DOMAINS_WHITELIST ograniczonym do Twojej domeny, a po założeniu konta wyłącz ją ponownie.