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

本指南介绍了电子邮件枚举保护功能，并说明了如何启用和停用此功能。如果您的项目是在 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 方法来更改用户的 电子邮件地址。

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

  • 您无法再使用 setAccountInfo REST API 将电子邮件地址/密码提供方与现有用户账号关联。您无法再在任何平台上将 linkWithCredential 客户端 SDK 方法与 EmailAuthCredential 搭配使用。 请改用 REST API signUp，并在 idToken 字段中传递用户的 ID 令牌，并在 email 和 password 字段中传递要关联的电子邮件地址和密码。

  • 移除电子邮件验证流程的错误响应，包括通过调用 sendOobCode REST API 并使用 VERIFY_AND_CHANGE_EMAIL 或 PASSWORD_RESET 请求类型发起的流程，以及通过调用适用于 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. 点击保存 。

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. 点击保存 。

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