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

本指南說明電子郵件列舉防護功能，並介紹如何啟用及停用這項功能。如果您在 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 權杖，並傳遞 email 和 password 欄位來建立連結。

  • 移除電子郵件驗證流程的錯誤回應，包括透過下列方式啟動的流程：使用 VERIFY_AND_CHANGE_EMAIL 或 PASSWORD_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\"}]}}"
}