Vaultwarden 1.37.4 雙因素驗證設定與解鎖

Vaultwarden 1.37.4 涵蓋的雙因素驗證功能

Vaultwarden 1.37.4 支援 5 種第二驗證因素：驗證器應用程式（TOTP，基於時間的一次性密碼）、電子郵件驗證碼、FIDO2 WebAuthn 安全金鑰、YubiKey OTP，以及 Duo。驗證器應用程式完全不需要伺服器設定。其他 4 種方式各自需要伺服器端的設定或服務：正常運作的郵件系統、正確的 DOMAIN over HTTPS、Yubico 憑證，或 Duo 憑證。

1.37.4 的設定沒有任何選項可強制所有使用者啟用第二驗證因素。強制要求來自組織的兩步驟登入政策，Bitwarden 的說明頁面稱為「Require two-step login」。此政策只適用於該組織的成員。啟用政策時，沒有第二驗證因素的成員也會立即被撤銷組織成員資格。

本指南假設 Vaultwarden 已透過 Docker Compose 執行，並位於具備有效憑證的反向代理後方。如果尚未完成，請先參閱在 VPS 上安裝 Vaultwarden，再返回本指南。以下所有設定都是環境變數。所有名稱與預設值均來自 1.37.4 的 .env.template 與原始碼。Vaultwarden wiki 並未依版本發布分頁，且只有 WebAuthn 與 YubiKey 的頁面，因此本指南以原始碼作為較可靠的參考。

變更前先固定版本

截至 28 October 2026，最新的標記版本是 1.37.4，於 5 October 2026 發布。其版本說明列出七項安全性公告，其中一項評為 High，並要求所有人儘快更新。請固定使用該標記，而不是 latest，確保此處描述的行為與實際執行內容一致。複製標記前，請先查看 releases page，確認是否有更新的版本。

services:
  vaultwarden:
    image: vaultwarden/server:1.37.4
    restart: unless-stopped
    env_file: vaultwarden.env
    volumes:
      - ./vw-data:/data
    # keep your existing ports, networks and proxy labels as they are

env_file 行會將 SMTP password 和 Duo client secret 等機密資訊排除在 compose file 之外。請在 docker-compose.yml 旁建立 vaultwarden.env，並限制其權限，因為其中會存放認證資訊：

touch vaultwarden.env
chmod 600 vaultwarden.env

如果現有設定位於 environment:，請改在該處加入新的變數。請選定一個位置，避免日後無法判斷應採用哪個值。

1.37.4 的七項升級說明中，有兩項涉及 two-factor authentication。Duo 的 DUO_USE_IFRAME 設定已移除；如果檔案中仍有該設定，請刪除。新增的電子郵件範本 email/recover_twofactor 用於 recovery-code 登入。請先備份 /data，操作方式請參閱 備份與還原 Vaultwarden，因為沒有備份的 rollback 只能靠猜測。

套用變更並確認容器已恢復運作

完成下方各節的每項變更後，執行以下命令。docker compose config 會輸出代入環境變數後的完整檔案，讓你在任何服務重新啟動前先發現拼字錯誤。up -d 會因環境變數已變更而重新建立容器。

docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail 50 vaultwarden

docker compose ps 應列出正在執行的 vaultwarden 服務。Vaultwarden 啟動時會檢查設定；某些不相容的 2FA 設定組合會使服務完全無法啟動。如果服務持續重新啟動，請先查看日誌。下方各節列出這些情況在 1.37.4 中顯示的錯誤文字。

驗證器應用程式（TOTP）：無須設定

TOTP 預設即可運作。每位使用者都能在 Web vault 中，使用 Aegis 或 2FAS 等驗證器應用程式掃描 QR code。

TOTP code 會根據共享 secret 與目前時間，以 30 秒為一個步進值計算。因此，伺服器時鐘很重要。Docker container 使用主機時鐘，請檢查主機：

timedatectl

正常的主機會顯示 System clock synchronized: yes。如果顯示 no，每個 code 都會依據錯誤的時間判定。

Vaultwarden 預設也接受前一個與下一個 30 秒步進值的 code，以吸收手機與伺服器之間的小幅時鐘差異。這項設定是 AUTHENTICATOR_DISABLE_TIME_DRIFT，預設值為 false。將其設為 true 後，前一個與下一個步進值的 code 都會失效。除非有明確原因，否則請保留預設值，因為手機若慢或快幾秒，便會在每個步進值的邊界導致驗證失敗。

Email 驗證碼需要可運作的 SMTP

完成郵件設定後，電子郵件雙步驟登入會自動啟用。在 1.37.4 的原始碼中，SMTP 啟用且設定了 SMTP_HOST 或 USE_SENDMAIL 時，電子郵件雙步驟登入就會啟用。範本指出，必須設定 SMTP_FROM，並設定上述兩者其中之一，才能啟用郵件服務。

SMTP_HOST=smtp.example.com
SMTP_FROM=vaultwarden@example.com
SMTP_FROM_NAME=Vaultwarden
SMTP_PORT=587
SMTP_SECURITY=starttls
SMTP_USERNAME=vaultwarden@example.com
SMTP_PASSWORD=your-smtp-password

預設的 SMTP_SECURITY 為 starttls，預設埠號為 587。force_tls 模式預設使用 465 埠。如果設定 SMTP_USERNAME，就必須同時設定 SMTP_PASSWORD。

1.37.4 的電子郵件驗證碼預設為 6 位數（EMAIL_TOKEN_SIZE），有效時間為 600 秒（EMAIL_EXPIRATION_TIME）。驗證失敗 3 次後，token 會重設，並需要重新寄送電子郵件（EMAIL_ATTEMPTS_LIMIT）。請維持 6 位數。範本指出，不論此設定值為何，client 都會假設驗證碼為 6 位數。

有兩個選用設定可將電子郵件驗證碼連結至註冊流程，兩者預設值都是 false。範本將 EMAIL_2FA_ENFORCE_ON_VERIFIED_INVITE 說明為「無論組織政策為何，註冊時都設定電子郵件 2FA」。它將 EMAIL_2FA_AUTO_FALLBACK 說明為「需要時，自動將電子郵件 2FA 設定為備援提供者」。兩者都依賴電子郵件 2FA；電子郵件 2FA 關閉時，1.37.4 會拒絕這些設定。

電子郵件是五種驗證因素中最弱的一種。寄送至信箱的驗證碼，其安全性僅與該信箱的密碼相當。請將它提供為備援方式，並引導使用者改用應用程式或安全金鑰。

FIDO2 WebAuthn 需要 HTTPS 與相符的 DOMAIN

安全金鑰會綁定網站的位址。FIDO2 WebAuthn 的 wiki 頁面指出，Vaultwarden 必須透過 HTTPS 提供服務，並使用有效憑證。頁面也指出，DOMAIN 必須設定為存取 Vaultwarden 時使用的相同位址，包括 https://；若連接埠不是 443，也必須包含連接埠。

DOMAIN=https://vw.example.com

範本另外提供兩種有效格式：包含連接埠的 https://vw.domain.tld:8443，以及包含路徑的 https://domain.tld/vw。範本也警告，DOMAIN 若與使用者開啟的位址不一致，受影響的不只是安全金鑰。附件下載與電子郵件中的連結也可能失效。

常見錯誤是使用第二個主機名稱。DOMAIN 指定為 https://vw.example.com，但有些人會開啟 https://vault.example.com，因為代理伺服器同時回應這兩個名稱。第二個名稱與 DOMAIN 不一致，因此安全金鑰無法在該位址運作。請選定一個名稱，將它設定在 DOMAIN，並在代理伺服器將另一個名稱重新導向。較完整的 HTTPS 與代理伺服器設定，請參閱 自架 Vaultwarden 的實際安全性。

YubiKey OTP 需要 Yubico API 憑證

YubiKey OTP 是一種模式。觸碰金鑰時，金鑰會輸入一組很長的一次性驗證碼。這與 FIDO2 分開，許多 YubiKey 兩者都支援。OTP 需要向 Yubico 取得 client ID 和 secret key：

YUBICO_CLIENT_ID=11111
YUBICO_SECRET_KEY=AAAAAAAAAAAAAAAAAAAAAAAA

這些是範本中的預留位置值，不是可運作的值。YUBICO_SERVER 是選用設定。若不設定，Vaultwarden 會使用預設的 YubiCloud 伺服器。兩個值都必須設定，或兩個都不設定。若只設定其中一個，且已啟用 Yubico 支援，1.37.4 會拒絕啟動，並顯示必須同時設定 YUBICO_CLIENT_ID 和 YUBICO_SECRET_KEY 才能支援 Yubikey OTP。

如果每位使用者都能註冊 FIDO2 金鑰，可能完全不需要 OTP。FIDO2 不需要第三方憑證，因此伺服器上可少保存一組 secret。

Duo 需要從 Duo 管理面板取得 3 個值

整個執行個體的 Duo（範本稱為「全域 Duo 支援」）需要這 3 個值。這些值來自您在 Duo 管理面板中建立的應用程式。相關步驟請依照 Duo 的官方文件操作。

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

啟用全域 Duo 支援後，如果 3 個值只設定其中一部分，設定驗證會因 All Duo options need to be set for global Duo support 而失敗。3 個值全部留白是有效設定；使用者之後可自行設定 Duo 憑證。請注意 1.37.4 升級說明：DUO_USE_IFRAME 已不存在，因此應予移除，不要從舊檔案沿用。

是否能強制所有 Vaultwarden 使用者啟用 2FA？

無法透過伺服器設定完成。1.37.4 的 config.rs 與 .env.template 都沒有要求使用第二因素的全域設定。最接近的選項是 EMAIL_2FA_ENFORCE_ON_VERIFIED_INVITE，但它只會設定電子郵件驗證碼。這是 1.37.4 的狀態，因此在假設後續版本仍然如此之前，請先查閱較新版本的發行說明。

以下兩項設定很容易被誤認為是強制執行。DISABLE_2FA_REMEMBER=true 會要求已設定第二因素的使用者在每次登入時使用該因素。「記住」核取方塊仍會顯示，但會被忽略。對尚未設定第二因素的使用者則沒有作用。SIGNUPS_ALLOWED 預設為 true；除非註冊期間自動設定電子郵件 2FA，否則新帳戶一開始不會設定第二因素。因此，開放註冊的公開執行個體仍會持續建立不受任何政策涵蓋的帳戶。

強制執行方式是組織的兩步驟登入政策。啟用後，該政策會套用至所屬組織的成員。未加入任何組織的個人帳戶永遠不會受到涵蓋。若要涵蓋所有使用者，每位使用者都必須是已啟用該政策之組織的成員。

啟用政策後，沒有 2FA 的成員會發生什麼事

這是最容易讓人意外的部分，因此請先閱讀，再儲存政策。在 1.37.4 中，將兩步驟登入政策儲存為啟用後，系統會立即執行強制套用。所有已確認、角色低於 Admin，且沒有第二因素的成員都會被撤銷存取權。依 Vaultwarden 的角色順序，這包括 Manager 和 User 角色。Owners 和 admins 不受檢查。若已設定電子郵件，每位被撤銷存取權的成員都會收到電子郵件。若強制套用發生錯誤，政策不會儲存。

Bitwarden 的文件也描述了相同的效果：非 owners 或 admins 的成員會被撤銷存取權、收到電子郵件，且必須符合政策要求後才能恢復存取。「已撤銷」是成員資格狀態。成員不會從組織中移除，但會失去存取組織項目的權限。

政策之後仍會持續強制套用。政策啟用期間，角色低於 Admin 且沒有第二因素的成員，無法被確認、恢復或變更成員資格，除非 EMAIL_2FA_AUTO_FALLBACK=true 成功為其已驗證的電子郵件地址啟用電子郵件 2FA。1.37.4 的錯誤遵循 Cannot <action> because 2FA is required (membership <id>) 的模式。若成員之後移除最後一個第二因素，系統會再次執行強制套用，並撤銷其存取權。

請依照以下順序部署：

1. 確認 owners 和 admins 都已設定第二因素，因為政策不會檢查這些角色。
2. 告知成員啟用日期，以及伺服器提供哪些因素。
3. 給成員時間完成註冊，再啟用政策。
4. 成員完成註冊後，恢復遭撤銷存取權的成員。對於仍沒有第二因素且角色低於 Admin 的成員，來源程式碼會阻止恢復，除非自動電子郵件備援成功啟用第二因素。

Recovery code：使用後的實際效果

每個啟用兩步驟登入的使用者都有一組 recovery code。Web vault 只有在使用者再次輸入 master password 後，才會顯示這組代碼。請告知使用者將代碼寫下或列印出來，並存放在 vault 外部。將 recovery code 存在它所解鎖的 vault 內沒有任何作用。

登入時使用這組代碼，不只是允許單次登入。在 1.37.4 中，系統會移除該使用者的所有第二因素驗證、清除每一個「記住此裝置」token、重新執行組織原則檢查、記錄事件，並清除已儲存的 recovery code。輸入代碼時不受空格與字母大小寫影響，因為系統會先移除空格並將字母轉為小寫，再進行比對。

這會帶來兩個結果。第一，使用者在完成復原後既沒有第二因素驗證，也沒有 recovery code，因此必須重新註冊，才能取得新的代碼。第二，如果使用者隸屬於已啟用該原則的組織，且權限低於 Admin，原則檢查會撤銷其存取權，直到使用者完成註冊並恢復存取權。

設定郵件後，1.37.4 也會寄信給使用者。範本的主旨為 Two-Step Login Recovered From <ip>，內文表示該帳戶已使用帳戶的 recovery code 停用兩步驟登入。收到這封郵件但未使用 recovery code 的使用者，應立即變更 master password。郵件寄送失敗時，系統只會記錄事件，登入仍會成功。

管理員如何移除遭鎖定使用者的 2FA

使用者遺失手機和復原碼後，管理員仍可協助其恢復存取權。1.37.4 版管理員頁面提供「移除所有 2FA」按鈕，但只有已啟用兩步驟登入的使用者才會顯示。此操作會刪除該使用者的所有第二因素、清除其記住裝置的 token、執行組織政策檢查，並清除復原碼。

管理員頁面需要 ADMIN_TOKEN，除非 DISABLE_ADMIN_TOKEN=true 略過其內建驗證。若兩者皆未設定，管理員面板會停用。範本建議使用 Argon2 PHC 字串，而不是純文字 token；Vaultwarden 安全指南說明如何保護該頁面。

按下按鈕前，請透過攻擊者無法控制的管道，確認對方確實是其聲稱的本人。僅因一封電子郵件就移除某人的第二因素，正是第二因素原本要阻止的攻擊。

按下按鈕後，會套用與復原碼相同的政策規則。若組織已啟用該政策，Manager 或 User 可能會立即遭撤銷存取權。請使用者立即註冊新的因素，然後恢復其成員資格。

管理員移除操作可修正遺失第二因素的問題，但不會讓其他人存取保管庫。若要讓受信任的人在緊急情況下存取某人的保管庫，這是另一項功能：Vaultwarden 緊急存取。

選用：在登入停在第二步時發出警示

INCOMPLETE_2FA_TIME_LIMIT 預設為 3 分鐘。若登入通過主密碼驗證，但未在這段時間內完成第二步，Vaultwarden 會寄送電子郵件給使用者。若使用者未嘗試登入，表示其他人已知道其主密碼。將其設為 0 即可停用此功能。INCOMPLETE_2FA_SCHEDULE 預設每分鐘執行一次檢查。這兩項功能都必須能正常寄送郵件才有作用。

為何變更 2FA 會導致無法登入，以及各原因

加入 YubiKey 或 Duo 後，容器不斷重新啟動。 必要群組中缺少一個值。執行 docker compose logs --tail 50 vaultwarden，並尋找上述提到的 Yubico 或 Duo 錯誤。docker compose config 會顯示實際傳入容器的值。

安全金鑰註冊在某個主機名稱失敗，但在另一個主機名稱正常。 DOMAIN 與瀏覽器中的位址不一致。修正主機名稱，或在代理層將第二個名稱重新導向至第一個名稱。

完全收不到電子郵件驗證碼。 郵件傳輸未正常運作。要求驗證碼後，立即檢查日誌中的 SMTP 錯誤。接著根據連接埠檢查 SMTP_SECURITY：使用 587 時檢查 starttls，使用 465 時檢查 force_tls。

所有 TOTP 驗證碼都遭拒絕。 主機時間不正確，或 AUTHENTICATOR_DISABLE_TIME_DRIFT=true 移除了容許誤差。timedatectl 可回答第一個問題。

成員突然失去共用項目的存取權。 雙步驟登入政策撤銷了其存取權，原因可能是啟用政策時，或成員移除最後一個第二因素時。成員註冊一個因素後，即可恢復其成員資格。

FAQ

我可以在 Vaultwarden 中強制所有使用者啟用雙因素驗證嗎？

在 1.37.4 中，無法透過伺服器設定做到。Vaultwarden 的設定沒有全域強制開關。強制執行是由組織的雙步驟登入政策負責，而且只適用於該組織的成員。此政策不會檢查擁有者和管理員，因此請確保他們手動完成註冊。

啟用雙步驟登入政策後，現有成員會發生什麼事？

在 Vaultwarden 1.37.4 中，儲存政策的當下，所有已確認、排名低於 Admin 且未設定第二因素的成員都會被撤銷存取權。如果已設定郵件功能，系統會寄送通知給他們。他們仍留在組織中，但無法存取其中的項目。完成第二因素註冊後，才能恢復其成員資格。

為什麼在我的 Vaultwarden 伺服器上註冊安全金鑰會失敗？

FIDO2 WebAuthn 需要使用具有效憑證的 HTTPS。DOMAIN 也必須與使用者開啟的完整位址完全相符，包括 https:// 以及任何不是 443 的連接埠。如果使用者透過第二個主機名稱存取 vault，安全金鑰會在該位址失敗。請使用單一主機名稱，並將其他主機名稱重新導向至該位址。

使用 Vaultwarden 復原碼時會發生什麼事？

系統會移除帳戶上的所有第二因素，並清除已記住的裝置。復原碼隨即失效，因此必須再次啟用雙步驟登入，才能取得新的復原碼。如果已設定郵件功能，1.37.4 會寄送通知給使用者。如果你屬於已啟用雙步驟登入政策的組織，且排名低於 Admin，則必須重新完成註冊，才能恢復存取權。

Vaultwarden 管理員可以重設使用者的 2FA 嗎？

可以。設定 ADMIN_TOKEN 後，1.37.4 的管理員頁面會為已啟用雙步驟登入的使用者顯示「移除所有 2FA」按鈕。此操作會刪除該使用者的所有第二因素和復原碼。請先確認使用者身分，並要求對方立即重新完成註冊，因為組織政策可能會隨即撤銷其存取權。