Konta administratorów Proxmox VE z kluczami YubiKey (WebAuthn) i root@pam jako konto awaryjne

Model kont administratorów Proxmox VE: grupa proxmox-admins i root@pam jako konto awaryjne

Proxmox VE rozróżnia konta po realmie, czyli źródle kont. W oknie logowania widać dwa domyślne realmy. Proxmox VE authentication server obsługuje konta @pve, których hasła przechowuje klaster. Linux PAM standard authentication obsługuje konta @pam, czyli konta Linuksa na węźle, sprawdzane przez PAM (ang. Pluggable Authentication Modules). root@pam to linuksowy root węzła: tego konta nie da się usunąć, a w Proxmoxie ma wszystkie uprawnienia.

Administratorzy pracują na osobnych kontach @pve. W logu zadań każda operacja ma wtedy nazwę konta, które ją wykonało, na przykład UPID:pve-lab-01:...:vncshell::ab@pve:, a nie wspólne root@pam. root@pam zostaje kontem awaryjnym: służy do kilku operacji zastrzeżonych dla roota i do wejścia do panelu, gdy konta osobiste nie działają.

Uprawnienia nadajemy grupie, nie kontom: jeden wpis ACL (ang. Access Control List) ze ścieżką /, rolą Administrator i włączoną propagacją. Tak zaleca dokumentacja Proxmox VE w sekcji o grupach: „Groups are the preferred way to organize access permissions”. Dokumentacja online w dniu pisania odpowiada pakietowi pve-docs 9.2.13, tej samej wersji co w labie. W teście każde z trzech kont miało dzięki temu wpisowi wszystkie 47 uprawnień roli Administrator na / i na każdej ścieżce niżej, także na maszynie, której jeszcze nie było.

Jak działa logowanie kluczem YubiKey w Proxmox VE: WebAuthn od hasła do biletu

YubiKey obsługuje WebAuthn przez FIDO2 (ang. Fast IDentity Online), zestaw standardów FIDO Alliance. Stronę przeglądarki opisuje specyfikacja Web Authentication organizacji W3C (ang. World Wide Web Consortium). W WebAuthn serwer nie zna żadnego sekretu klucza. Przy rejestracji YubiKey tworzy nową parę kluczy dla tego serwisu i tego konta, a serwer zapisuje tylko klucz publiczny. Przy logowaniu klucz podpisuje losowe wyzwanie serwera, a serwer sprawdza podpis. Ten przebieg prześledziliśmy w labie dla konta ab@pve i panelu otwartego pod adresem https://pve-lab-01.pve.lab:8006.

Rejestracja klucza: co zapisuje serwer, a co YubiKey

1. Panel wysyła POST /api2/json/access/tfa/ab@pve z typem webauthn, opisem i hasłem konta. Bez hasła serwer odpowiada błędem password is required to modify user.
2. Serwer zwraca wyzwanie rejestracji z polami: identyfikator serwisu rp.id = pve-lab-01.pve.lab, konto ab@pve, algorytmy podpisu ES256 (krzywa eliptyczna P-256) i RS256 (RSA), attestation: none, userVerification: discouraged, residentKey: discouraged i 5 minut na odpowiedź.
3. Przeglądarka przekazuje wyzwanie do klucza. Po dotknięciu YubiKey tworzy nową parę kluczy związaną z pve-lab-01.pve.lab i odsyła klucz publiczny oraz identyfikator poświadczenia (ang. credential).
4. Panel odsyła odpowiedź drugim POST na ten sam adres, a serwer zapisuje klucz publiczny i identyfikator w /etc/pve/priv/tfa.cfg.

userVerification: discouraged oznacza, że wystarczy dotknięcie klucza; PIN FIDO2 nie jest potrzebny. residentKey: discouraged oznacza klucz nierezydentny, więc rejestracja nie zajmuje miejsca na passkeys w pamięci YubiKey. Ten sam fizyczny YubiKey zarejestrowany na ab@pve i na root@pam ma dwa niezależne poświadczenia. Poświadczenie z konta ab@pve nie loguje na root@pam; w teście serwer odpowiedział 401.

Logowanie: półbilet, wyzwanie i podpis klucza

1. Przeglądarka wysyła login i hasło (POST /api2/json/access/ticket). Proxmox sprawdza hasło w realmie pve. Ponieważ konto ma wpis WebAuthn, zamiast pełnego biletu wydaje półbilet zaczynający się od PVE:!tfa!. W półbilecie jest wyzwanie: losowy challenge, rpId = pve-lab-01.pve.lab i lista allowCredentials z identyfikatorami kluczy zarejestrowanych na tym koncie. Zapytanie API z półbiletem kończy się odpowiedzią 401.
2. Panel otwiera okno „Second login factor required” i wywołuje WebAuthn w przeglądarce. Przeglądarka sprawdza, czy rpId pasuje do adresu strony i czy certyfikat jest poprawny.
3. Po dotknięciu YubiKey podpisuje kluczem prywatnym poświadczenia skrót rpId, flagi, licznik użyć i skrót danych klienta z wyzwaniem i adresem strony. Klucz prywatny nie opuszcza YubiKey.
4. Panel wysyła podpis razem z półbiletem. Serwer sprawdza podpis kluczem publicznym z rejestracji, wyzwanie, adres strony i identyfikator serwisu, a po sukcesie wydaje pełny bilet.

W tym przebiegu są trzy miejsca awarii. Klucz innej osoby nie ma żadnego identyfikatora z allowCredentials, więc przeglądarka nie dostanie podpisu; wymuszony obcy podpis serwer odrzucił w teście kodem 401. Inny adres panelu niż zapisany identyfikator serwisu blokuje WebAuthn jeszcze przed oknem klucza; pokazujemy to w następnym rozdziale. Utrata wszystkich zarejestrowanych kluczy blokuje konto, jeśli nie ma ono zapasowego składnika.

Nazwa panelu i zaufany certyfikat: warunek działania WebAuthn w Proxmox VE

Jedna nazwa panelu dla wszystkich administratorów

Identyfikator serwisu w WebAuthn to nazwa domenowa. Proxmox zapisuje ją w polu ID ustawień WebAuthn, a adres strony (ang. origin) bierze z adresu, pod którym otwarto panel. W labie z ID = pve-lab-01.pve.lab serwer proponował klucz wyłącznie pod nazwą pve-lab-01.pve.lab, niezależnie od portu. Pod https://localhost:8006 (tunel SSH), pod adresem IP węzła i pod krótką nazwą pve-lab-01 serwer w ogóle nie dodał WebAuthn do wyzwania. Panel pokazał wtedy „No second factor left! Please contact an administrator!”, a w dzienniku węzła pojawiły się wpisy rp_id is not an effective_domain of rp_origin i webauthn error: failed to begin webauthn context instantiation.

Dlatego przed rejestracją pierwszego klucza ustalamy jedną pełną nazwę panelu, np. pve1.example.pl, i wszyscy administratorzy otwierają panel tylko pod nią. Pola ID nie zmieniamy później: panel ostrzega przy edycji, że „Changing the ID breaks existing WebAuthn TFA entries”. Klastra nie testowaliśmy. Ustawienia WebAuthn mają opcję allow-subdomains, domyślnie włączoną („Whether to allow the origin to be a subdomain, rather than the exact URL”).

Zaufany certyfikat dla panelu: Let's Encrypt albo własny urząd certyfikacji

Chrome 155 pozwala użyć prawdziwego klucza w WebAuthn tylko na stronie z poprawnym certyfikatem. Regułę widać w funkcji IsSecurityLevelAcceptableForWebAuthn w pliku chrome_content_browser_client.cc (tag 155.0.8059.84, commit 5869fe3135, 14 października 2026). Wyjątki to localhost, flaga --ignore-certificate-errors i polityka firmowa AllowWebAuthnWithBrokenTlsCerts. Panel Proxmoxa przypomina o tym przy ustawieniach WebAuthn: „WebAuthn requires using a trusted certificate”. Domyślny certyfikat węzła wystawia urząd certyfikacji klastra, któremu przeglądarki nie ufają.

Certyfikat dla nazwy panelu ustawiamy w panelu na jeden z dwóch sposobów. Pierwszy to Let's Encrypt przez ACME (ang. Automatic Certificate Management Environment), protokół automatycznego wydawania certyfikatów opisany w RFC 8555:

1. Datacenter → ACME → Accounts → Add. W oknie Register Account podajemy Account Name, E-Mail i ACME Directory (Let's Encrypt), akceptujemy Terms of Services i zatwierdzamy.
2. <węzeł> → System → Certificates → w części ACME: Add, Challenge Type i Domain z nazwą panelu.
3. W Using Account wybieramy konto z kroku 1 i klikamy Order Certificates Now.

Tej drogi nie testowaliśmy, bo lab nie ma publicznej nazwy. Wymagania wyzwania HTTP i wtyczek DNS opisuje rozdział Certificate Management w dokumentacji Proxmox VE. Drugi sposób to własny certyfikat, na przykład z wewnętrznego urzędu certyfikacji, któremu ufają komputery administratorów: <węzeł> → System → Certificates → Upload Custom Certificate.

Konfiguracja WebAuthn, grupy proxmox-admins i kont @pve w panelu Proxmox VE

Logujemy się jako root (Realm: Linux PAM standard authentication) pod docelową nazwą panelu. Kolejność ma znaczenie: ustawienia WebAuthn muszą istnieć, zanim ktokolwiek zarejestruje klucz.

1. Ustawienia WebAuthn. Datacenter → Options → zaznaczamy WebAuthn Settings → Edit → Auto-fill → OK. Auto-fill wpisuje do pól Name i ID nazwę z paska adresu, więc przed kliknięciem sprawdzamy, czy pasek pokazuje docelową nazwę. Origin zostawiamy puste: Proxmox weźmie wtedy adres strony z zapytania. Po zapisaniu wiersz WebAuthn Settings pokazuje wartości rp i id z nazwą panelu, a w /etc/pve/datacenter.cfg pojawia się linia zaczynająca się od webauthn:.
2. Grupa. Datacenter → Permissions → Groups → Create → Name: proxmox-admins → Create.
3. Uprawnienie dla grupy. Datacenter → Permissions → Add → Group Permission: Path /, Group proxmox-admins, Role Administrator, zaznaczone Propagate → Add. Lista Permissions pokazuje potem wpis z Path /, grupą @proxmox-admins w kolumnie User/Group/API Token i rolą Administrator.
4. Konta. Datacenter → Permissions → Users → Add: User name ab, Realm Proxmox VE authentication server, Group proxmox-admins → Add. To samo dla cd i ef. Pola hasła zostawiamy puste: panel na to pozwala (dla realmu pve wymaga tylko minimum 8 znaków, jeśli hasło jest podane), a każdy ustawi swoje hasło sam.

Zmiany cofamy w tych samych miejscach: konto, grupę i wpis uprawnień usuwa przycisk Remove na liście. Usunięcie grupy kasuje też jej wpisy ACL. Ustawień WebAuthn nie usuwa się z panelu; robi to polecenie pvesh set /cluster/options --delete webauthn uruchomione na węźle jako root.

Hasło i rejestracja klucza YubiKey na koncie administratora Proxmox VE

Hasło konta @pve ustawiane przez samego właściciela

Konto @pve bez hasła nie zaloguje się wcale. Hasło najprościej ustawić przy wspólnym spotkaniu, razem z rejestracją kluczy na root@pam. W sesji roota otwieramy Datacenter → Permissions → Users, zaznaczamy konto i klikamy Password. Właściciel konta sam wpisuje hasło w pola New Password i Confirm New Password i zatwierdza, więc nikt inny go nie poznaje. Gdy hasło zmienia administrator inny niż root, okno pyta też o Your Current Password, czyli hasło osoby zalogowanej.

Rejestracja YubiKey w Two Factor: Add, WebAuthn, Register Webauthn Device

Każdy administrator robi to na swoim komputerze, z własnym kluczem w porcie USB.

1. Otwieramy https://pve1.example.pl:8006, czyli pełną nazwę z rozdziału o nazwie panelu, i logujemy się: User name ab, Realm Proxmox VE authentication server.
2. Jeśli hasło wpisywał ktoś inny, zmieniamy je: menu konta w prawym górnym rogu → Password.
3. Menu konta → TFA. Panel otwiera Datacenter → Permissions → Two Factor. Klikamy Add → WebAuthn i wypełniamy Description (właściciel i numer seryjny klucza, np. YubiKey ab, nr 12345678) oraz Verify Password (hasło konta). Klikamy Register Webauthn Device i dotykamy klucza.
4. Na liście Two Factor pojawia się wpis typu WebAuthn z naszym opisem i zaznaczonym Enabled.

Zapasowy drugi składnik: drugi YubiKey albo kody odzyskiwania

Konto z jednym kluczem traci drugi składnik razem z kluczem. Zapas dodajemy od razu. Pierwsza możliwość to drugi YubiKey: powtarzamy rejestrację z innym opisem. Druga to kody odzyskiwania: Add → Recovery Keys → Verify Password, a po wygenerowaniu Copy Recovery Keys albo Print Recovery Keys i przechowanie kodów w menedżerze haseł lub w sejfie. Bez zapasu zgubiony klucz usuwa root, a do rejestracji nowego klucza konto działa na samym haśle.

Test logowania: Logout i ponowne logowanie. Po haśle panel otwiera okno „Second login factor required”; dotykamy klucza i wchodzimy do panelu. Klucz innej osoby nie zaloguje na to konto.

Klucze wszystkich administratorów na root@pam: rejestracja w jednej sesji roota

Klucz do root@pam może dodać tylko sesja zalogowana jako root@pam. Administrator z rolą Administrator dostał w teście odmowę (403) przy dodawaniu, wyłączaniu i usuwaniu kluczy roota oraz przy zmianie jego hasła. Wynika to z kodu funkcji reauth_user_for_user_modification w RPCEnvironment.pm (libpve-access-control 9.1.2, commit dff26b4586, 17 września 2026). Po dodaniu pierwszego klucza root wymaga już klucza przy logowaniu, dlatego wszystkie klucze rejestrujemy w jednej sesji: trzy osoby przy jednym komputerze, każda ze swoim kluczem.

1. Logujemy się jako root, Realm Linux PAM standard authentication.
2. Datacenter → Permissions → Two Factor → Add → WebAuthn: User root@pam, Description YubiKey ab, nr 12345678 → Register Webauthn Device. Klucza dotyka właściciel, ab. Pola hasła dla root@pam nie ma, bo panel je ukrywa.
3. Powtarzamy krok 2 dla kluczy cd i ef w tej samej sesji. Serwer wysyła do przeglądarki listę już zarejestrowanych kluczy, więc ten sam YubiKey nie zostanie zapisany dwa razy.
4. Logout i test: każda z trzech osób loguje się jako root swoim kluczem. W teście wyzwanie roota miało trzy pozycje w allowCredentials i każdy z trzech kluczy otwierał sesję.

Kody odzyskiwania root@pam w sejfie

W tej samej sesji: Add → Recovery Keys → User root@pam, a po wygenerowaniu Print Recovery Keys. Wydruk trafia do koperty w sejfie razem z hasłem roota. Proxmox generuje 10 kodów i każdy działa raz: w teście drugie użycie tego samego kodu skończyło się odpowiedzią 401. Drugiego zestawu nie da się dodać, dopóki istnieje pierwszy („user already has recovery keys”). Kody nie zależą od nazwy panelu: zalogowały roota także pod adresem IP, pod którym WebAuthn nie działa.

Hasło roota, konsola węzła i SSH poza TFA Proxmoxa

Hasło root@pam to hasło Linuksa na węźle, sprawdzane przez PAM. Wynika z tego, że w klastrze każdy węzeł ma własne hasło roota; klastra nie testowaliśmy. TFA Proxmoxa działa przy logowaniu do panelu i API, nie przy konsoli węzła ani SSH. Na pve-lab-01 polecenie sshd -T pokazuje permitrootlogin without-password, więc przez SSH root loguje się wyłącznie kluczem SSH, a hasło roota działa w panelu i na konsoli. Konsola węzła jest też ostatnią drogą ratunku, gdy przepadną wszystkie klucze i kody roota.

Kontrola kont, kluczy i tokenów API w panelu Proxmox VE

Proxmox nie wymusza WebAuthn. Wymuszenie TFA w ustawieniach realmu obsługuje tylko TOTP (ang. Time-based One-Time Password) i Yubico OTP, jak opisuje sekcja Two-Factor Authentication. W teście przy wymuszonym TOTP logowanie kluczem WebAuthn zostało odrzucone z komunikatem realm requires totp authentication. Administrator może też usunąć TFA innemu administratorowi, a wtedy to konto loguje się samym hasłem. Zgodność sprawdzamy więc w panelu co jakiś czas i po każdej zmianie osób:

Zgubiony YubiKey, odejście administratora i blokada TFA: procedury w panelu

Zmiana hasła roota z panelu zmienia hasło Linuksa na tym węźle, przez który otwarto panel: PAM.pm wykonuje usermod lokalnie. Tej ścieżki nie testowaliśmy. W klastrze hasło roota zmieniamy więc w panelu każdego węzła.

Granice modelu: tokeny API, operacje tylko dla root@pam i powłoka węzła

root@pam nie chroni przed przejętym kontem administratora. W teście konto ab@pve z rolą Administrator wygenerowało token API dla root@pam bez Privilege Separation: token miał 47 uprawnień i działał bez hasła i bez TFA. Pozwala na to sprawdzenie uprawnień w User.pm (funkcja generate_token nie ma wyjątku dla roota). To samo konto wyłączyło root@pam, po czym logowanie roota do panelu kończyło się odpowiedzią 401. Klucze chronią przed kradzieżą hasła, nie przed nieuczciwym administratorem.

Tokeny API omijają TFA. Token z Privilege Separation wyłączonym ma pełne uprawnienia konta i nie przechodzi przez drugi składnik. Tokenem nie da się za to zmieniać TFA: serwer odpowiada „not available with API token, need proper ticket”. Tworząc token (Datacenter → Permissions → API Tokens → Add), sprawdzamy, czy Privilege Separation jest zaznaczone, ustawiamy Expire (puste pole oznacza never) i nadajemy tokenowi tylko potrzebne uprawnienia przez Permissions → Add → API Token Permission. Szczegóły opisuje sekcja API Tokens dokumentacji.

Niektóre operacje wymagają root@pam mimo roli Administrator. W teście ustawienie args w konfiguracji maszyny wirtualnej zwróciło only root can set 'args' config zarówno administratorowi, jak i tokenowi root@pam; zadziałało dopiero z sesji root@pam zalogowanej kluczem. Z kodu Qemu.pm (qemu-server 9.2.11) i LXC.pm (pve-container 6.1.14) wynika, że to samo dotyczy niemapowanych urządzeń PCI (ang. Peripheral Component Interconnect) i USB, portów szeregowych na prawdziwe urządzenia, a w kontenerach punktów montowania spoza magazynów (bind mount), hookscriptu i flag innych niż nesting.

Powłoka węzła z panelu wygląda inaczej dla kont @pve. Przycisk Shell i przycisk Upgrade uruchamiają dla nich /bin/login, czyli monit logowania kontem Linuksa. root@pam dostaje od razu powłokę roota (/bin/login -f root). Komentarz w Nodes.pm (pve-manager 9.2.21) mówi wprost: „non-root must always login for now, we do not have a superuser role!”. Do powłoki i aktualizacji systemu administratorzy potrzebują więc osobnej drogi, na przykład SSH z kluczami.

Wyniki testu na Proxmox VE 9.2 w labie

Wszystkie przypadki sprawdziliśmy 20 października 2026 r. na pve-lab-01, a potem przywróciliśmy stan sprzed testu.

Źródła: dokumentacja Proxmox VE 9.2, kod źródłowy i Chromium 155

• Proxmox VE: User Management (pve-docs 9.2.13): sekcje Groups, Two-Factor Authentication, Limits and Lockout of Two-Factor Authentication, Server Side Webauthn Configuration i API Tokens.
• Proxmox VE: Certificate Management.
• pve-access-control 9.1.2: commit dff26b4586 z 17 września 2026 r.
• pve-manager 9.2.21: commit 4f6e0ac86f z 24 września 2026 r.
• proxmox-widget-toolkit 5.2.10: commit 5faa913848 z 18 września 2026 r.
• qemu-server 9.2.11: commit c5399752ae z 9 października 2026 r.
• pve-container 6.1.14: commit 1c0488315a z 27 sierpnia 2026 r.
• Chromium 155.0.8059.84 (commit 5869fe3135, 14 października 2026): chrome_content_browser_client.cc i authenticator_common_impl.cc. Wirtualny klucz w narzędziach deweloperskich Chrome pomija kontrolę certyfikatu (IsVirtualEnvironmentEnabled), więc zachowanie przy niezaufanym certyfikacie trzeba sprawdzać prawdziwym YubiKey.
• RFC 8555: Automatic Certificate Management Environment (ACME).