啟用或停用電子郵件列舉保護功能

本指南說明電子郵件列舉防護功能,並介紹如何啟用及停用這項功能。如果您在 2023 年 9 月 15 日當天或之後建立專案,系統預設會啟用電子郵件列舉防護功能。

總覽

電子郵件列舉是一種暴力攻擊,惡意行為人會將電子郵件地址傳遞至 API 並檢查回應,藉此猜測或確認系統中的使用者。

如果沒有電子郵件列舉防護機制,Identity Platform 會傳回可供電子郵件列舉攻擊利用的資訊:

  • 嘗試登入的電子郵件地址不存在於系統中。Identity Platform 傳回 EMAIL_NOT_FOUND 錯誤。

  • 嘗試使用系統中已有的電子郵件地址註冊。Identity Platform 傳回 EMAIL_EXISTS 錯誤。

您可以運用 Identity Platform 的電子郵件列舉防護功能,保護應用程式中的使用者帳戶免於這類攻擊。

啟用電子郵件列舉防護後,專案會出現下列行為:

  • fetchSignInForEmail API 會失敗。如果 SDK 版本低於 Android 22.3.0、iOS 10.18.0 和網頁 10.6.0,也無法將匿名驗證使用者與電子郵件地址建立連結。

  • 在所有平台上呼叫 createAuthUri REST API 或 fetchSignInMethodsForEmail 用戶端 SDK 方法時,系統不會再傳回指定電子郵件地址的登入方法清單。

  • 使用者必須先驗證新電子郵件地址,才能變更地址。舉例來說,您無法再透過 update REST API、setAccountInfo REST API 或所有平台上的 updateEmail 用戶端 SDK 方法變更使用者電子郵件地址。

    您可以改用 verifyBeforeUpdateEmail (適用於網頁和 Android) 或 sendEmailVerification(beforeUpdatingEmail:) (適用於 iOS)。

  • 您無法再使用 setAccountInfo REST API,將電子郵件/密碼供應商連結至現有使用者帳戶。您無法再於任何平台使用 linkWithCredential 用戶端 SDK 方法搭配 EmailAuthCredential。請改用 REST API signUp,在 idToken 欄位中傳遞使用者的 ID 權杖,並傳遞 emailpassword 欄位來建立連結。

  • 移除電子郵件驗證流程的錯誤回應,包括透過下列方式啟動的流程:使用 VERIFY_AND_CHANGE_EMAILPASSWORD_RESET 要求類型呼叫 sendOobCode REST API;呼叫 Web 和 Android 的 verifyBeforeUpdateEmail、iOS 的 sendEmailVerification(beforeUpdatingEmail:),或所有平台的 sendPasswordResetEmail

    當您要求重設密碼時,系統只會在電子郵件地址存在的情況下傳送驗證電子郵件;當您要求變更電子郵件地址時,系統只會在電子郵件地址不存在的情況下傳送驗證電子郵件。在這兩種情況下,系統都不會顯示電子郵件未傳送的具體錯誤訊息。

    建議您不要允許使用者在沒有電子郵件驗證流程的情況下註冊。

  • 如果登入無效,系統會傳回 INVALID_LOGIN_CREDENTIALS 錯誤回應。無效的註冊案例仍會傳回 EMAIL_EXISTS 錯誤,請參閱下一節的建議。

如果應用程式依賴電子郵件列舉保護機制變更的任何行為,可以停用這項機制。不過,從長遠來看,我們不建議這麼做,詳情請參閱下一節。

安全性建議

執行帳戶盜用攻擊最常見的方法之一,是使用外洩或容易猜到的憑證,執行憑證填充攻擊。電子郵件列舉也可能用於取得使用者的私密資訊,或對使用者發動網路釣魚攻擊。基於上述原因,Google 建議使用電子郵件列舉防護功能,保護應用程式免於這類攻擊。

  • 如果您是在 2023 年 9 月 15 日當天或之後建立專案,系統預設會啟用電子郵件列舉防護功能。建議您啟用電子郵件列舉保護機制,並避免依賴本指南稍早列出的任何行為。

  • 如果您在 2023 年 9 月 15 日前建立專案,系統不會自動啟用電子郵件列舉保護機制。

    如果您的應用程式不依賴本指南稍早所述的任何行為,建議您立即啟用電子郵件列舉保護機制。

    如果您的應用程式依賴上述任何行為,建議您開始遷移,並盡快啟用電子郵件列舉保護措施。

除了使用電子郵件列舉防護功能,如果專案的註冊端點持續傳回 EMAIL_EXISTS 錯誤,請考慮採取措施防止濫用。以下提供幾種做法:

  • 啟用 App Check
  • reCAPTCHA 整合至註冊流程。
  • 禁止使用電子郵件地址和密碼或電子郵件連結登入,改用 Google 登入等替代方法。

啟用電子郵件列舉防護

如要啟用電子郵件列舉保護機制,請按照下列步驟操作:

Firebase 控制台

  1. 前往 Firebase 控制台的「Authentication Settings」(驗證設定) 頁面。

    前往「驗證設定」

    1. 在「使用者帳戶管理」窗格中,選取「使用者動作」

    2. 選取「電子郵件列舉防護 (建議)」

  2. 按一下 [儲存]

Node.js

  1. 安裝 Admin SDK

  2. 如要啟用電子郵件列舉保護機制,請使用下列其中一種做法:

    • 如要在專案層級提供保護措施,請按照下列步驟操作:

      import { getAuth } from 'firebase-admin/auth';
      
      getAuth().projectConfigManager().updateProjectConfig(
        {
          emailPrivacyConfig: {
            enableImprovedEmailPrivacy: true,
          },
        }
      );
      
    • 如要在租戶層級提供保護措施:

      import { getAuth } from 'firebase-admin/auth';
      
      getAuth().tenantConfigManager().updateTenant(TENANT_ID,
        {
          emailPrivacyConfig: {
            enableImprovedEmailPrivacy: true,
          },
        }
      );
      

      TENANT_ID 替換為要啟用電子郵件列舉保護機制的租戶 ID。

REST

  1. 在 Google Cloud 控制台中,使用 gcloud auth print-access-token 指令列印專案 ID 的存取權杖:

    gcloud auth print-access-token --project=PROJECT_ID
    
  2. 使用 Identity Toolkit API 為專案 ID 啟用電子郵件列舉防護功能:

    curl -X PATCH -d "{'emailPrivacyConfig':{'enableImprovedEmailPrivacy':true}}" \
        -H 'Authorization: Bearer ACCESS_TOKEN' \
        -H 'Content-Type: application/json' -H 'X-Goog-User-Project: PROJECT_ID' \
        "https://identitytoolkit.googleapis.com/admin/v2/projects/PROJECT_ID/config?updateMask=emailPrivacyConfig"
    

更改下列內容:

  • ACCESS_TOKEN:您先前產生的存取權杖
  • PROJECT_ID:您的專案 ID

停用電子郵件列舉防護

如要停用電子郵件列舉保護措施,請按照下列步驟操作:

Firebase 控制台

  1. 前往 Firebase 控制台的「Authentication Settings」(驗證設定) 頁面。

    前往「驗證設定」

    1. 在「使用者帳戶管理」窗格中,選取「使用者動作」

    2. 清除「電子郵件列舉防護 (建議)」

  2. 按一下 [儲存]

Node.js

  1. 安裝 Admin SDK

  2. 如要停用電子郵件列舉保護功能,請使用下列其中一種方法:

    • 如要在專案層級提供保護措施,請按照下列步驟操作:

      import { getAuth } from 'firebase-admin/auth';
      
      getAuth().projectConfigManager().updateProjectConfig(
        {
          emailPrivacyConfig: {
            enableImprovedEmailPrivacy: false,
          },
        }
      );
      
    • 如要在租戶層級提供保護措施:

      import { getAuth } from 'firebase-admin/auth';
      
      getAuth().tenantConfigManager().updateTenant(TENANT_ID,
        {
          emailPrivacyConfig: {
            enableImprovedEmailPrivacy: false,
          },
        }
      );
      

      TENANT_ID 替換為要停用電子郵件列舉保護機制的租戶 ID。

REST

  1. 在 Google Cloud 控制台中,使用 gcloud auth print-access-token 指令列印專案 ID 的存取權杖:

    gcloud auth print-access-token --project=PROJECT_ID
    
  2. 使用 Identity Toolkit API 停用電子郵件列舉保護機制:

    curl -X PATCH -d "{'emailPrivacyConfig':{'enableImprovedEmailPrivacy':false}}" \
        -H 'Authorization: Bearer ACCESS_TOKEN' \
        -H 'Content-Type: application/json' -H 'X-Goog-User-Project: PROJECT_ID' \
        "https://identitytoolkit.googleapis.com/admin/v2/projects/PROJECT_ID/config?updateMask=emailPrivacyConfig"
    

更改下列內容:

  • ACCESS_TOKEN:您先前產生的存取權杖
  • PROJECT_ID:您的專案 ID

錯誤回應範例

如果使用者嘗試以錯誤的電子郵件地址或密碼登入,或是嘗試使用系統中已有的電子郵件地址註冊,Identity Platform 會傳回類似下列的錯誤:

{
"code": "auth/internal-error",
"message": "{\"error\":{\"code\":400,\"message\":\"INVALID_LOGIN_CREDENTIALS\",\"errors\":[{\"message\":\"INVALID_LOGIN_CREDENTIALS\",\"domain\":\"global\",\"reason\":\"invalid\"}]}}"
}