如何為你的 App 加入雙重認證

要為你嘅 App 加入雙重認證（2FA），讓用戶透過掃描 QR code 連結驗證器應用程式，然後輸入密碼之後，由該應用程式顯示嘅六位數字代碼，只有當代碼驗證成功後，伺服器先會建立完整嘅 session。用戶開啟 2FA 時，應該給佢哋單次使用嘅備用碼，限制任何人可以猜測代碼嘅次數，並要求用戶輸入密碼同目前有效嘅代碼，先可以關閉 2FA。如果你使用託管嘅驗證供應商，就開啟佢內置嘅多重認證選項，而唔好自行開發。

本指南會逐步講解各種選擇、具體流程、可以俾 AI 生成工具使用嘅提示詞，以及一些會令 2FA 看似存在、實際上卻冇作用嘅常見錯誤。如果你對呢個概念仍然陌生，可以先閱讀什麼是雙重認證。

開始之前：你需要一個可運作嘅登入系統

2FA 建基於現有嘅登入之上。你需要先具備以下其中一項：

• 你自己嘅登入系統，用戶同經過雜湊處理嘅密碼儲存於你 App 嘅資料庫。
• 託管嘅驗證供應商，由佢代你管理用戶。

如果兩樣你都仲未有，可以先由如何為你的 App 加入登入開始。本指南其餘部分假設密碼步驟已經可以正常運作。

揀選第二重驗證方式

TOTP 代表 time-based one-time password（基於時間嘅一次性密碼），即驗證器應用程式使用嘅標準（RFC 6238）。你嘅伺服器同用戶嘅手機共用一個金鑰；雙方各自根據該金鑰同目前時間，生成相同嘅短代碼，通常每 30 秒更換一次。它不需要網絡連線，亦不需要 SMS 服務供應商。

通行密鑰以儲存於用戶裝置上嘅密碼學金鑰取代或補充密碼。它更加安全，但你自行建立時工作量較多，所以好多 App 會先用 TOTP，之後再加入通行密鑰，或者從驗證供應商取得。

自行建立，定係開啟現成功能？

請查閱你供應商目前嘅文件，了解佢支援邊啲驗證方式，以及各個方式適用於邊個計劃。無論點樣揀，都唔好自行編寫生成代碼嘅數學運算；請使用廣泛採用嘅函式庫。

先決定政策

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

1. **邊啲人必須使用？**對所有人自願使用、要求管理員同職員使用，定係要求所有人使用。要求具管理權限嘅人使用好常見。參閱角色式存取控制。
2. **用戶幾耐需要重新輸入代碼？**每次登入，定係每部裝置每 30 日一次（「記住此裝置」）。
3. **邊啲操作需要重新驗證？**更改電郵、付款資料或者關閉 2FA，都是很好嘅例子。呢個稱為步驟提升驗證（step-up authentication）。
4. **遺失手機時嘅程序係咩？**備用碼，加上你願意執行嘅人手後備程序。

逐步做法：自行登入系統嘅 TOTP 2FA

1. 儲存正確嘅欄位

每位用戶需要：2FA 是否已啟用、TOTP 金鑰（需要加密儲存，唔可以用明文）、啟用嘅時間，以及一個經過雜湊處理嘅備用碼清單（同密碼一樣處理）。另外要加入一個地方計算失敗嘗試次數。

2. 登記

1. 用戶打開設定，撳開啟雙重認證。
2. 伺服器生成一個新金鑰，並以 QR code 形式回傳，另外提供文字版本，俾無法掃描嘅人使用。
3. 用戶用驗證器應用程式掃描，然後輸入目前顯示嘅代碼。
4. 伺服器驗證代碼。只有代碼正確，才會儲存金鑰並將 2FA 標示為已啟用。
5. App 只顯示一次 8 至 10 個備用碼，並要求用戶將其儲存。

第 4 步好關鍵：如果喺確認代碼之前就開啟 2FA，掃描失敗嘅人下次登入時就會被鎖在門外。

3. 登入時加入第二步

1. 用戶提交電郵同密碼，伺服器驗證佢哋。
2. 如果已啟用 2FA，伺服器唔會建立完整 session，而係建立一個短暫有效嘅「等待第二重驗證」狀態。
3. App 顯示代碼輸入畫面。伺服器驗證代碼，並容許少量時間偏差。
4. 直到呢一刻，伺服器先會發出真正嘅 session。

每個受保護嘅路由同 API 端點都必須拒絕「等待第二重驗證」狀態。如果 2FA 畫面只係喺瀏覽器中隱藏頁面，人哋可以直接呼叫 API 繞過。

4. 限制次數同發出提示

六位數字代碼有一百萬種組合，如果冇限制，就可以被猜到。應該限制嘗試次數，連續失敗後暫時鎖定第二步驗證，並在發生時向用戶發出電郵。參閱速率限制同從你嘅 App 發送電郵。

5. 復原同關閉

• 每個備用碼只可以使用一次，用完即刪除。
• 關閉 2FA 需要密碼同目前有效嘅代碼，或者備用碼。
• 重新生成備用碼會令舊有一組失效。
• 每當 2FA 被開啟或關閉時，都要電郵通知用戶。

俾 AI 生成工具嘅提示詞

先加入核心流程：

為我哋現有嘅電郵同密碼登入加入可選嘅雙重認證，使用驗證器應用程式（TOTP）。使用廣泛採用嘅 TOTP 函式庫，唔好自己編寫演算法。喺設定頁面顯示 QR code 同文字金鑰，並只有當用戶輸入正確代碼後，才啟用 2FA。金鑰需要加密儲存，設定完成後不再顯示。顯示 10 個單次使用嘅備用碼，只顯示一次，並以雜湊形式儲存。

然後是強制執行，呢度係 AI 生成程式碼最常出錯嘅地方：

喺伺服器上強制執行 2FA。密碼正確之後，已啟用 2FA 嘅用戶會進入一個短暫有效嘅等待狀態，而唔係完整 session。每個受保護嘅頁面同 API 路由都必須拒絕等待狀態。代碼嘗試次數限制為 5 次，之後將第二步驗證鎖定 15 分鐘，並電郵通知用戶。

然後是政策：

要求管理員帳戶使用 2FA：未啟用 2FA 嘅管理員會被引導去設定，完成之前無法進入儀表板。關閉 2FA 或更改帳戶電郵時，需要同時輸入密碼同目前有效嘅代碼。每當 2FA 被啟用或停用時，都要電郵通知用戶。

最後，要求 Agent 解釋它建立咗乜嘢：

列出每一個會檢查第二重驗證是否已完成嘅路由，說明 TOTP 金鑰同備用碼儲存喺邊度，以及如何保護佢哋。

常見錯誤

• **密碼之後就發出完整 session。**呢個係最嚴重嘅錯誤。如果代碼未經檢查，完整 session 已經存在，2FA 就只係裝飾。測試方法係：只完成密碼步驟後，直接呼叫一個受保護嘅 API。
• **冇限制嘗試次數。**冇限制嘅猜測，令代碼可以被暴力破解。
• **金鑰或備用碼以明文儲存。**資料庫一旦外洩，所有人嘅第二重驗證資料都會被取得。
• **未驗證就先啟用。**掃描錯誤嘅用戶，下次登入時會被鎖在門外。
• **冇復原途徑。**每次遺失手機都變成一張支援單，或者失去一位客戶。
• **容易關閉。**如果被盜取嘅 session 可以唔使代碼就關閉 2FA，保護就失效了。
• **代碼出現喺日誌中。**確保代碼同金鑰永遠唔會出現喺伺服器日誌或錯誤訊息中。
• **只喺登入頁面檢查。**密碼重設、「魔術連結」登入同任何社交登入，都必須尊重 2FA；否則就會變成繞過它嘅途徑。

測試清單

• 只有驗證成功代碼之後，登記才會完成
• 密碼正確但冇輸入代碼，無法存取任何受保護嘅頁面或 API
• 錯誤代碼會被拒絕；連續輸入錯誤代碼會觸發鎖定同電郵
• 幾分鐘前嘅代碼會被拒絕
• 每個備用碼只可以使用一次
• 關閉 2FA 需要密碼同目前有效嘅代碼
• 密碼重設唔可以繞過 2FA
• 未啟用 2FA 嘅管理員無法進入管理頁面（如果有此要求）
• 金鑰同備用碼喺資料庫中已加密或雜湊處理
• 日誌中冇任何代碼或金鑰

上線之前，亦要完成AI 建立 App 嘅安全檢查清單。

喺 Mythex 加入 2FA

Mythex 唔包括為你 App 嘅最終用戶而設嘅內置登入系統，所以 2FA 會成為你所選登入方式嘅一部分：可以係你自己用專案資料庫建立嘅電郵加密碼登入，或者係支援多重認證嘅託管供應商。你可以喺對話中用類似上面嘅提示詞描述需求，而任何供應商金鑰都應該放入專案機密（透過 /secrets、專案設定，或者 Agent 顯示嘅機密卡片），而唔係放入訊息框。文件中嘅為你的 App 加入登入食譜提供咗起步提示詞，而為你建立嘅 App 做安全設定則涵蓋金鑰同權限方面嘅日常習慣。Agent 完成工作之後，喺 Preview 中逐項測試檢查清單，然後才發布。

常見問題