启用或停用电子邮件枚举保护

本指南介绍了电子邮件枚举保护功能，并说明了如何启用和停用该功能。如果您是在 9 月 15 日当天或之后创建的项目， 2023 年，电子邮件枚举保护默认处于启用状态。

概览

电子邮件枚举是一种暴力破解攻击类型，恶意行为者通过将电子邮件地址传递给 API 并检查响应来尝试猜测或确认系统中的用户。

如果未启用电子邮件枚举保护，Identity Platform 会返回可用于电子邮件枚举攻击的信息：

  • 尝试使用不存在的电子邮件地址登录 数据。Identity Platform 返回 EMAIL_NOT_FOUND 错误。

  • 尝试使用系统中已存在的电子邮件地址注册。Identity Platform 返回 EMAIL_EXISTS 错误。

您可以使用 Identity Platform 的电子邮件枚举保护功能来保护 用户账号免受这些攻击

启用电子邮件枚举保护后，您的项目将具有以下行为：

  • fetchSignInForEmail API 将失败。在低于 SDK 22.3.0 版（Android 版）、10.18.0 版（iOS 版）和 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 Client SDK 方法与 EmailAuthCredential 搭配使用。请改用 REST API signUp，在 idToken 字段以及要关联的 email、password 字段中传递用户的 ID 令牌。

  • 移除电子邮件验证流程的错误响应，例如发起的那些 方法是调用 sendOobCode 请求类型为 VERIFY_AND_CHANGE_EMAIL 或 PASSWORD_RESET，以及调用 verifyBeforeUpdateEmail（适用于 Web 和 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 身份验证设置页面。

    转到 Firebase Authentication 设置

    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 身份验证设置页面。

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