Enable email enumeration protection

This guide shows you how to enable email enumeration protection.

Overview

Email enumeration is a type of brute-force attack in which a malicious actor attempts to guess or confirm users in a system by passing an email address to the API and checking the response.

In the examples that follow, email enumeration protection is disabled. Identity Platform returns information that can be used in an email enumeration attack:

  • An attempt is made to sign in with an email address that doesn't exist in the system. Identity Platform returns an EMAIL_NOT_FOUND error.

  • An attempt is made to sign up with an email address that already exists in the system. Identity Platform returns an EMAIL_EXISTS error.

You can use Identity Platform's email enumeration protection feature to protect user accounts in your app from these attacks. Email enumeration protection offers the following features:

  • Invalid sign-in cases return an INVALID_LOGIN_CREDENTIALS error response. Invalid sign-up cases return EMAIL_EXISTS.
  • Removes error responses for email verification flows. If the email address exists, a verification email is sent. If it does not exist, a verification email is not sent. We recommend that you do not allow users to sign up without an email verification flow.
  • Disables the ability for users to change their email address without first verifying the new address.
  • Disables listing of sign-in methods for a specified email address when calling createAuthUri.

Enable email enumeration protection

To enable email enumeration protection, follow these steps:

  1. In the Google Cloud console, print an access token for your project ID using the gcloud auth print-access-token command:

    gcloud auth print-access-token --project=PROJECT_ID
    
  2. Enable email enumeration protection for your project ID using the Identity Toolkit API:

    curl -X PATCH -d "{'email_privacy_config':{'enable_improved_email_privacy':"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=email_privacy_config"
    

Replace the following:

  • ACCESS_TOKEN: the access token you generated earlier
  • PROJECT_ID: your project ID

Disable email enumeration protection

To disable email enumeration protection, follow these steps:

  1. In the Google Cloud console, print an access token for your project ID using gcloud auth print-access-token command:

    gcloud auth print-access-token --project=PROJECT_ID
    
  2. Disable email enumeration protection using the Identity Toolkit API:

    curl -X PATCH -d "{'email_privacy_config':{'enable_improved_email_privacy':"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=email_privacy_config"
    

Replace the following:

  • ACCESS_TOKEN: the access token you generated earlier
  • PROJECT_ID: your project ID

Example of an error response

If a user attempts to sign in with an incorrect email address or password, or attempts to sign up with an email address that already exists in the system, Identity Platform returns an error similar to the following:

{
  "code": "auth/internal-error",
  "message": "{\"error\":{\"code\":400,\"message\":\"INVALID_LOGIN_CREDENTIALS\",\"errors\":[{\"message\":\"INVALID_LOGIN_CREDENTIALS\",\"domain\":\"global\",\"reason\":\"invalid\"}]}}"
}