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

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

概览

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

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

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

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

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

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

  • fetchSignInForEmail API 将失败。在 Android SDK 版本 22.3.0、iOS SDK 版本 10.18.0 和 Web SDK 版本 10.6.0 之前，将匿名身份验证用户与电子邮件地址相关联也无法正常运作。

  • 在所有平台上调用 createAuthUri REST API 或 fetchSignInMethodsForEmail 客户端 SDK 方法时，系统不再返回指定电子邮件地址的登录方法列表。

  • 用户必须先验证新电子邮件地址，然后才能更改电子邮件地址。例如，您无法再通过 update REST API、setAccountInfo REST API 或 updateEmail 客户端 SDK 方法在所有平台上更改用户的电子邮件地址。

    您可以改用 verifyBeforeUpdateEmail（适用于 Web 和 Android）或 sendEmailVerification(beforeUpdatingEmail:)（适用于 iOS）。

  • 您现在无法再使用 setAccountInfo REST API 将电子邮件/密码提供方与现有用户账号相关联。您现在无法在任何平台上使用带有 EmailAuthCredential 的 linkWithCredential 客户端 SDK 方法。请改用 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 控制台中，前往身份验证设置页面。

    前往“身份验证设置”

    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 控制台中，前往身份验证设置页面。

    前往“身份验证设置”

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