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

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

總覽

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

如果未啟用電子郵件列舉防護功能，Identity Platform 會傳回可供電子郵件列舉攻擊利用的資訊：

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

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

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

啟用電子郵件列舉防護功能後，專案會顯示以下行為：

  • fetchSignInForEmail API 會失敗。在 Android 10.18.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 欄位和 email、password 欄位中傳遞使用者的 ID 權杖。

  • 移除電子郵件驗證流程的錯誤回應，例如透過呼叫 sendOobCode REST API 以 VERIFY_AND_CHANGE_EMAIL 或 PASSWORD_RESET 要求類型啟動的流程，以及在呼叫 verifyBeforeUpdateEmail (適用於網頁版和 Android)、sendEmailVerification(beforeUpdatingEmail:) (適用於 iOS) 或 sendPasswordResetEmail 用戶端 SDK 方法 (適用於所有平台) 時。

    當您提出重設密碼要求時，只有在電子郵件地址已存在的情況下，系統才會傳送驗證電子郵件；當您提出變更電子郵件地址要求時，只有在電子郵件地址不存在的情況下，系統才會傳送驗證電子郵件。在上述兩種情況下，系統都不會顯示特定錯誤訊息，指出電子郵件未送達。

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

  • 無效的登入情況會傳回 INVALID_LOGIN_CREDENTIALS 錯誤回應。無效的註冊案例會繼續傳回 EMAIL_EXISTS 錯誤，請參閱下一節的建議。

如果您的應用程式依賴電子郵件列舉保護機制所變更的任何行為，目前可以停用這項機制。不過，我們不建議長期使用這種做法，請參閱下一個章節。

安全性建議

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

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

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

    如果您的應用程式不依賴本指南前述的任何行為，建議您立即啟用電子郵件列舉保護功能。

    如果您的應用程式會依賴上述任何行為，建議您開始改用其他方法，並盡快啟用電子郵件列舉保護功能。

除了使用電子郵件列舉保護功能之外，建議您採取措施，防止濫用專案的註冊端點，導致持續傳回 EMAIL_EXISTS 錯誤。以下提供幾種方法：

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

啟用電子郵件列舉防護

如要啟用電子郵件列舉保護功能，請按照下列步驟操作：

Firebase 控制台

  1. 前往 Firebase 控制台的「Firebase Auth Settings」頁面。

    前往 Firebase Auth 設定

    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 控制台的「Firebase Auth Settings」頁面。

    前往 Firebase Auth 設定

    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\"}]}}"
}