如何為應用程式加入雙重驗證

要為應用程式加入雙重驗證（2FA），請讓使用者掃描 QR 碼以連結驗證器應用程式，並在輸入密碼後要求他們輸入該應用程式顯示的六位數代碼；只有代碼正確，伺服器才建立完整的工作階段。使用者啟用 2FA 時，請給他們一次性備用代碼，限制某人能猜測代碼的次數，並要求同時輸入密碼與目前的代碼，才能關閉 2FA。如果你使用代管的身分驗證服務，請直接開啟它內建的多因素驗證，而不要自行建置。

本指南會說明各種選擇、確切的流程、可交給 AI 建置工具的提示詞，以及那些會讓 2FA 看似存在、實際上卻沒有作用的錯誤。如果這個概念對你來說還很陌生，請先閱讀什麼是雙重驗證。

開始之前：你需要一個可以運作的登入功能

2FA 是建立在既有登入之上的。你需要以下其中一種：

• 你自己的登入功能，使用者與經過雜湊的密碼儲存在你應用程式的資料庫中。
• 代管的身分驗證服務，由它替你管理使用者。

如果你還沒有任何一種，請從如何為應用程式加入登入功能開始。本指南的其餘內容假設密碼步驟已經可以運作。

挑選第二因素

TOTP 代表基於時間的一次性密碼，是驗證器應用程式所使用的標準（RFC 6238）。你的伺服器與使用者的手機共享一個密鑰；兩者都會根據該密鑰與目前的時間產生相同的短代碼，通常每 30 秒變更一次。不需要網路連線，也不需要簡訊服務商。

通行密鑰則是以存放在使用者裝置上的加密金鑰來取代或補充密碼。它們更強，但自行建置的工作量也更大，因此許多應用程式會先使用 TOTP，之後再加入通行密鑰，或直接從身分驗證服務取得。

自行建置，還是直接開啟？

請查閱你的服務商目前的文件，了解它支援哪些因素，以及在哪些方案上可用。無論哪種方式，都絕不要自己撰寫代碼產生的數學運算；請使用廣泛採用的函式庫。

先決定政策

在下提示詞之前，先回答以下問題，因為它們會改變設計：

1. **誰必須使用？**對所有人都是選用、對管理員與員工必須使用，還是對所有人都必須使用？對擁有管理權限的人要求使用很常見。請參閱角色型存取控制。
2. **使用者多久需要重新輸入代碼？**每次登入，還是每個裝置 30 天內只需一次（「記住此裝置」）？
3. **哪些動作需要重新確認？**變更電子郵件、付款資訊或關閉 2FA 都是很好的候選。這稱為提升驗證（step-up authentication）。
4. **遺失手機時的流程是什麼？**備用代碼，加上你願意執行的人工備援流程。

逐步執行：在你自己的登入上使用 TOTP 2FA

1. 儲存正確的欄位

每位使用者需要：是否已啟用 2FA、TOTP 密鑰（靜態加密，而不是純文字）、啟用的時間，以及一份經過雜湊的備用代碼清單，就像密碼一樣。另外還需要一個地方來記錄失敗的嘗試次數。

2. 註冊

1. 使用者開啟設定，並點擊開啟雙重驗證。
2. 伺服器產生新的密鑰，並以 QR 碼回傳，同時提供給無法掃描的人使用的文字版本。
3. 使用者在驗證器應用程式中掃描，並輸入目前的代碼。
4. 伺服器檢查代碼。只有正確時，才會儲存密鑰並將 2FA 標記為已啟用。
5. 應用程式只顯示一次 8 到 10 組備用代碼，並要求使用者妥善保存。

第 4 步很重要：如果在確認代碼之前就開啟 2FA，掃描失敗的人在下次登入時就會被鎖在外面。

3. 登入時加入第二步驟

1. 使用者提交電子郵件與密碼，伺服器檢查它們。
2. 如果已啟用 2FA，伺服器不會建立完整的工作階段，而是建立一個短期的「等待第二因素」狀態。
3. 應用程式顯示代碼輸入畫面。伺服器檢查代碼，並允許少量的時鐘偏差。
4. 只有到這一步，伺服器才會發出真正的工作階段。

每一個受保護的路由和 API 端點都必須拒絕「等待第二因素」狀態。如果 2FA 畫面只是在瀏覽器中隱藏頁面，那麼直接呼叫 API 就能繞過它。

4. 次數限制與警示

六位數代碼有一百萬種組合，如果沒有限制，很容易被猜中。請限制嘗試次數，在連續失敗後將第二步驟鎖定一段時間，並在發生時寄信通知使用者。請參閱速率限制與從應用程式寄送電子郵件。

5. 復原與關閉

• 每組備用代碼只能使用一次，使用後即刪除。
• 關閉 2FA 需要密碼以及目前的代碼或備用代碼。
• 重新產生備用代碼會使舊的那一組失效。
• 每當 2FA 被開啟或關閉時，都要寄信通知使用者。

交給 AI 建置工具的提示詞

先從核心流程開始：

為我們現有的電子郵件與密碼登入加入選用的雙重驗證，使用驗證器應用程式（TOTP）。使用知名的 TOTP 函式庫，不要自己撰寫演算法。在設定中顯示 QR 碼與文字密鑰，並且只有在使用者輸入正確代碼後才啟用 2FA。密鑰需加密儲存，設定完成後不再顯示。顯示 10 組一次性備用代碼，且只顯示一次，並以雜湊方式儲存。

接著是強制執行，這是 AI 產生的程式碼最常出錯的地方：

在伺服器上強制執行 2FA。密碼正確之後，已啟用 2FA 的使用者會取得一個短期的「等待」狀態，而不是完整的工作階段。每個受保護的頁面和 API 路由都必須拒絕「等待」狀態。代碼嘗試次數限制為 5 次，之後將第二步驟鎖定 15 分鐘，並寄信通知使用者。

然後是政策：

管理員帳號必須啟用 2FA：沒有啟用 2FA 的管理員會被導向設定，在完成之前無法進入儀表板。關閉 2FA 或變更帳號電子郵件時，需要輸入密碼與目前的代碼。每當 2FA 被開啟或關閉時，寄信通知使用者。

最後，請代理人說明它建置了什麼：

列出每一個會檢查第二因素是否已完成的路由，說明 TOTP 密鑰與備用代碼儲存在哪裡，以及它們如何受到保護。

常見錯誤

• **在密碼步驟之後就發出完整工作階段。**這是最嚴重的錯誤。如果在檢查代碼之前，完整的工作階段就已經存在，2FA 就只是裝飾。測試方式是：只在密碼步驟之後，直接呼叫受保護的 API。
• **沒有嘗試次數限制。**無限制的猜測會讓代碼可以被暴力破解。
• **密鑰或備用代碼以純文字儲存。**資料庫外洩時，每個人的第二因素就全都洩露了。
• **在驗證之前就啟用。**掃描錯誤的使用者會在下次登入時被鎖在外面。
• **沒有復原途徑。**每一支遺失的手機都會變成一張客服單，或一位流失的客戶。
• **關閉太容易。**如果被盜用的工作階段可以在不需要代碼的情況下關閉 2FA，保護就形同虛設。
• **代碼出現在日誌中。**請確保代碼與密鑰絕不會出現在伺服器日誌或錯誤訊息中。
• **只在登入頁面上檢查。**密碼重設、「魔術連結」登入，以及任何社群登入，也都必須遵守 2FA，否則它們會成為繞過的途徑。

測試檢查清單

• 只有在輸入有效代碼後，註冊才會完成
• 輸入正確密碼但沒有代碼時，無法存取任何受保護的頁面或 API
• 錯誤的代碼會被拒絕；連續錯誤會觸發鎖定與寄信
• 幾分鐘前的代碼會被拒絕
• 每組備用代碼只能使用一次
• 關閉 2FA 需要密碼與目前的代碼
• 密碼重設不會繞過 2FA
• 沒有啟用 2FA 的管理員無法進入管理頁面（若有此要求）
• 密鑰與備用代碼在資料庫中已加密或雜湊
• 日誌中沒有任何代碼或密鑰

上線前也請完整執行AI 建置應用程式的安全檢查清單。

在 Mythex 加入 2FA

Mythex 不為你應用程式的終端使用者提供內建的登入系統，因此 2FA 是你所選擇的任何身分驗證方式的一部分：可以是使用專案資料庫的自有電子郵件與密碼登入，也可以是支援多因素驗證的代管服務商。你可以在對話中使用類似上面的提示詞來描述需求，而任何服務商金鑰都應放在專案 secrets 中（透過 /secrets、專案設定，或代理人顯示的 secrets 卡片），而不是放在訊息框裡。文件中的為應用程式加入登入功能食譜提供了起始提示詞，而為你建置的應用程式設定安全性則說明了關於金鑰與權限的習慣。代理人完成後，請在發布前於預覽中逐一測試檢查清單上的每一項。

常見問題