Add support for generic response messages. (pallets-eco#632)

The new SECURITY_RETURN_GENERIC_RESPONSES flag, if set to True will make Flask-Security consistent with the OWASP Authentication errors cheat-sheet recommendations.

This affects the /register, /login, /forgot, /confirm, /us-signin, /verify endpoints.

This adds new signal (user_not_registered), new email templates (welcome_existing, welcome_existing_username) to improve UX in the case of someone trying to register an already registered email/username.

close pallets-eco#585

Author: jwag956

.pre-commit-config.yaml

@@ -14,12 +14,12 @@ repos:
     -   id: check-merge-conflict
     -   id: fix-byte-order-marker
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v2.34.0
+    rev: v2.37.1
     hooks:
     -   id: pyupgrade
         args: [--py37-plus]
 -   repo: https://github.com/psf/black
-    rev: 22.3.0
+    rev: 22.6.0
     hooks:
     -   id: black
 -   repo: https://gitlab.com/pycqa/flake8

CHANGES.rst

@@ -24,6 +24,7 @@ Features
 Fixes
 +++++
 - (:pr:`591`) Make the required zxcvbn complexity score configurable (mephi42)
+- (:issue:`585`) Provide option to prevent user enumeration.
 - (:issue:`531`) Get rid of Flask-Mail. Flask-Mailman is now the default preferred email package.
   Flask-Mail is still supported so there should be no backwards compatability issues.
 - (:issue:`597`) A delete option has been added to us-setup (form and view).
@@ -60,6 +61,8 @@ For unified signin:
 - ``SECURITY_US_VERIFY_SEND_CODE_URL`` and ``SECURITY_US_SIGNIN_SEND_CODE_URL`` endpoints are now POST only.
 - Empty passwords were always permitted when ``SECURITY_UNIFIED_SIGNIN`` was enabled - now an additional configuration
   variable ``SECURITY_PASSWORD_REQUIRED`` must be set to False.
+- ``SECURITY_US_VERIFY_SEND_CODE_URL`` and ``SECURITY_US_SIGNIN_SEND_CODE_URL`` used to send ``code_sent`` to the template.
+  Now they flash the ``SECURITY_MSG_CODE_HAS_BEEN_SENT`` message.
 
 Login:
 

docs/api.rst

@@ -268,6 +268,19 @@ sends the following signals.
    `form_data` is a dictionary representation of registration form's content
    received with the registration request.
 
+.. data:: user_not_registered
+
+    Sent when a user attempts to register, but is already registered. This is ONLY sent
+    when :py:data:`SECURITY_RETURN_GENERIC_RESPONSES` is enabled. It is passed the
+    following arguments:
+
+        * `user` - The existing user model
+        * `existing_email` - True if attempting to register an existing email
+        * `existing_username`- True if attempting to register an existing username
+        * `form_data` - the entire contents of the posted request form
+
+    .. versionadded:: 5.0.0
+
 .. data:: user_confirmed
 
    Sent when a user is confirmed. In addition to the app (which is the

docs/configuration.rst

@@ -435,6 +435,13 @@ These configuration keys are used globally across all features.
 
     Default: ``False``.
 
+.. py:data:: SECURITY_RETURN_GENERIC_RESPONSES
+
+    If set to ``True`` Flask-Security will return generic responses to endpoints
+    that could be used to enumerate users. Please see :ref:`generic_responses`.
+
+    .. versionadded:: 5.0.0
+
 .. py:data:: SECURITY_BACKWARDS_COMPAT_UNAUTHN
 
     If set to ``True`` then the default behavior for authentication
@@ -1515,7 +1522,7 @@ Recovery Codes
     To enable this feature - set this to ``True``. Please see :ref:`models_topic` for
     required additions to your database models. This enables a user to generate and
     use a recovery code for two-factor authentication. This works for all two-factor
-    mechanisms - including webauthn. Note that these code are single use and
+    mechanisms - including WebAuthn. Note that these code are single use and
     the user should be advised to write them down and store in a safe place.
 
 .. py:data:: SECURITY_MULTI_FACTOR_RECOVERY_CODES_N
@@ -1642,6 +1649,7 @@ The default messages and error levels can be found in ``core.py``.
 * ``SECURITY_MSG_ALREADY_CONFIRMED``
 * ``SECURITY_MSG_API_ERROR``
 * ``SECURITY_MSG_ANONYMOUS_USER_REQUIRED``
+* ``SECURITY_MSG_CODE_HAS_BEEN_SENT``
 * ``SECURITY_MSG_CONFIRMATION_EXPIRED``
 * ``SECURITY_MSG_CONFIRMATION_REQUEST``
 * ``SECURITY_MSG_CONFIRMATION_REQUIRED``
@@ -1652,6 +1660,9 @@ The default messages and error levels can be found in ``core.py``.
 * ``SECURITY_MSG_EMAIL_NOT_PROVIDED``
 * ``SECURITY_MSG_FAILED_TO_SEND_CODE``
 * ``SECURITY_MSG_FORGOT_PASSWORD``
+* ``SECURITY_MSG_GENERIC_AUTHN_FAILED``
+* ``SECURITY_MSG_GENERIC_RECOVERY``
+* ``SECURITY_MSG_GENERIC_US_SIGNIN``
 * ``SECURITY_MSG_IDENTITY_ALREADY_ASSOCIATED``
 * ``SECURITY_MSG_INVALID_CODE``
 * ``SECURITY_MSG_INVALID_CONFIRMATION_TOKEN``

docs/customizing.rst

@@ -303,6 +303,10 @@ The following is a list of email templates:
 * `security/email/change_notice.html`
 * `security/email/welcome.html`
 * `security/email/welcome.txt`
+* `security/email/welcome_existing.html`
+* `security/email/welcome_existing.txt`
+* `security/email/welcome_existing_username.html`
+* `security/email/welcome_existing_username.txt`
 * `security/email/two_factor_instructions.html`
 * `security/email/two_factor_instructions.txt`
 * `security/email/two_factor_rescue.html`
@@ -338,33 +342,37 @@ to ``False`` will bypass sending of the email (they all default to ``True``).
 In most cases, in addition to an email being sent, a :ref:`Signal <signals_topic>` is sent.
 The table below summarizes all this:
 
-=============================   ================================   =============================================     ====================== ===============================
-**Template Name**               **Gate Config**                    **Subject Config**                                **Context Vars**       **Signal Sent**
------------------------------   --------------------------------   ---------------------------------------------     ---------------------- -------------------------------
-welcome                         SECURITY_SEND_REGISTER_EMAIL       SECURITY_EMAIL_SUBJECT_REGISTER                   - user                 user_registered
-                                                                                                                     - confirmation_link
-                                                                                                                     - confirmation_token
-confirmation_instructions       N/A                                SECURITY_EMAIL_SUBJECT_CONFIRM                    - user                 confirm_instructions_sent
-                                                                                                                     - confirmation_link
-                                                                                                                     - confirmation_token
-login_instructions              N/A                                SECURITY_EMAIL_SUBJECT_PASSWORDLESS               - user                 login_instructions_sent
-                                                                                                                     - login_link
-                                                                                                                     - login_token
-reset_instructions              SEND_PASSWORD_RESET_EMAIL          SECURITY_EMAIL_SUBJECT_PASSWORD_RESET             - user                 reset_password_instructions_sent
-                                                                                                                     - reset_link
-                                                                                                                     - reset_token
-reset_notice                    SEND_PASSWORD_RESET_NOTICE_EMAIL   SECURITY_EMAIL_SUBJECT_PASSWORD_NOTICE            - user                 password_reset
-
-change_notice                   SEND_PASSWORD_CHANGE_EMAIL         SECURITY_EMAIL_SUBJECT_PASSWORD_CHANGE_NOTICE     - user                 password_changed
-two_factor_instructions         N/A                                SECURITY_EMAIL_SUBJECT_TWO_FACTOR                 - user                 tf_security_token_sent
-                                                                                                                     - token
-                                                                                                                     - username
-two_factor_rescue               N/A                                SECURITY_EMAIL_SUBJECT_TWO_FACTOR_RESCUE          - user                 N/A
-us_instructions                 N/A                                SECURITY_US_EMAIL_SUBJECT                         - user                 us_security_token_sent
-                                                                                                                     - login_token
-                                                                                                                     - login_link
-                                                                                                                     - username
-=============================   ================================   =============================================     ====================== ===============================
+=============================   ==================================   =============================================     ====================== ===============================
+**Template Name**               **Gate Config**                      **Subject Config**                                **Context Vars**       **Signal Sent**
+-----------------------------   ----------------------------------   ---------------------------------------------     ---------------------- -------------------------------
+welcome                         SECURITY_SEND_REGISTER_EMAIL         SECURITY_EMAIL_SUBJECT_REGISTER                   - user                 user_registered
+                                                                                                                       - confirmation_link
+                                                                                                                       - confirmation_token
+confirmation_instructions       N/A                                  SECURITY_EMAIL_SUBJECT_CONFIRM                    - user                 confirm_instructions_sent
+                                                                                                                       - confirmation_link
+                                                                                                                       - confirmation_token
+login_instructions              N/A                                  SECURITY_EMAIL_SUBJECT_PASSWORDLESS               - user                 login_instructions_sent
+                                                                                                                       - login_link
+                                                                                                                       - login_token
+reset_instructions              SEND_PASSWORD_RESET_EMAIL            SECURITY_EMAIL_SUBJECT_PASSWORD_RESET             - user                 reset_password_instructions_sent
+                                                                                                                       - reset_link
+                                                                                                                       - reset_token
+reset_notice                    SEND_PASSWORD_RESET_NOTICE_EMAIL     SECURITY_EMAIL_SUBJECT_PASSWORD_NOTICE            - user                 password_reset
+
+change_notice                   SEND_PASSWORD_CHANGE_EMAIL           SECURITY_EMAIL_SUBJECT_PASSWORD_CHANGE_NOTICE     - user                 password_changed
+two_factor_instructions         N/A                                  SECURITY_EMAIL_SUBJECT_TWO_FACTOR                 - user                 tf_security_token_sent
+                                                                                                                       - token
+                                                                                                                       - username
+two_factor_rescue               N/A                                  SECURITY_EMAIL_SUBJECT_TWO_FACTOR_RESCUE          - user                 N/A
+us_instructions                 N/A                                  SECURITY_US_EMAIL_SUBJECT                         - user                 us_security_token_sent
+                                                                                                                       - login_token
+                                                                                                                       - login_link
+                                                                                                                       - username
+welcome_existing                SECURITY_SEND_REGISTER_EMAIL         SECURITY_EMAIL_SUBJECT_REGISTER                   - user                 user_not_registered
+                                SECURITY_RETURN_GENERIC_RESPONSES                                                      - recovery_link
+welcome_existing_username       SECURITY_SEND_REGISTER_EMAIL         SECURITY_EMAIL_SUBJECT_REGISTER                   - email                user_not_registered
+                                SECURITY_RETURN_GENERIC_RESPONSES                                                      - username
+=============================   ==================================   =============================================     ====================== ===============================
 
 When sending an email, Flask-Security goes through the following steps:
 
@@ -375,7 +383,7 @@ When sending an email, Flask-Security goes through the following steps:
 
   #. Calls :meth:`.MailUtil.send_mail` with all the required parameters.
 
-The default implementation of ``MailUtil.send_mail`` uses Flask-Mail to create and send the message.
+The default implementation of ``MailUtil.send_mail`` uses flask-mailman to create and send the message.
 By providing your own implementation, you can use any available python email handling package.
 
 Email subjects are by default localized - see above section on Localization to learn how

docs/patterns.rst

@@ -115,6 +115,47 @@ and :func:`flask_security.password_breached_validator`.
 
 .. _5.1.1.2 Memorized Secret Verifiers: https://pages.nist.gov/800-63-3/sp800-63b.html#sec5
 
+
+.. _generic_responses:
+
+Generic Responses - Avoiding User Enumeration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+How an application responds to API requests that contain identity or authentication information
+can give would-be attackers insight into active users on the system. OWASP has a great `cheat-sheet`_ describing
+this and useful ways to avoid it. Flask-Security supports this by setting the
+:py:data:`SECURITY_RETURN_GENERIC_RESPONSES` configuration to ``True``. As documented in the cheat-sheet - this does
+come with some usability concerns. The following endpoints are affected:
+
+    * :py:data:`SECURITY_REGISTER_URL` - The same response will be returned whether the email (or username) is already in the
+      system or not. JSON requests will ALWAYS return 200. If :py:data:`SECURITY_CONFIRMABLE` is set (it should be!), the
+      `SECURITY_MSG_CONFIRM_REGISTRATION` message will be flashed for both new and existing email addresses. Detailed errors will still
+      be returned for things like insufficient password complexity, etc.. In the case of trying to register an existing email, an email will be sent to that email address
+      explaining that they are already registered and displaying the associated username (if any) and provide a hint on how to reset their
+      password if they forgot it. In the case of a new email but an already registered username, an email will be sent saying that the
+      user must try registering again with a different username.
+    * :py:data:`SECURITY_LOGIN_URL` - For any errors (unknown username, inactive account, bad password) the `SECURITY_MSG_GENERIC_AUTHN_FAILED`
+      message will be returned.
+    * :py:data:`SECURITY_RESET_URL` - In all cases the `SECURITY_MSG_PASSWORD_RESET_REQUEST` message will be flashed. For JSON
+      a 200 will always be returned (whether an email was sent or not).
+    * :py:data:`SECURITY_CONFIRM_URL` - In all cases the `SECURITY_MSG_CONFIRMATION_REQUEST` message will be flashed. For JSON
+      a 200 will always be returned (whether an email was sent or not).
+    * :py:data:`SECURITY_US_SIGNIN_SEND_CODE_URL` - The `SECURITY_MSG_GENERIC_US_SIGNIN` message will be flashed in all cases -
+      whether a selected method is setup for the user or not.
+    * :py:data:`SECURITY_US_SIGNIN_URL` - For any errors (unknown username, inactive account, bad passcode) the `SECURITY_MSG_GENERIC_AUTHN_FAILED`
+      message will be returned.
+    * :py:data:`SECURITY_US_VERIFY_LINK_URL` - For any errors (unknown username, inactive account, bad passcode) the `SECURITY_MSG_GENERIC_AUTHN_FAILED`
+      message will be returned.
+
+
+In the case of an application using a ``username`` as an identity it should be noted that it is possible for a bad-actor to enumerate usernames, albeit slowly,
+by parsing emails.
+
+Note also that :py:data:`SECURITY_REQUIRES_CONFIRMATION_ERROR_VIEW` is ignored in these cases. If your application is using WebAuthn, be sure
+to set :py:data:`SECURITY_WAN_ALLOW_USER_HINTS` to ``False``.
+
+
+.. _cheat-sheet: https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html#authentication-and-error-messages
+
 .. _csrftopic:
 
 CSRF

flask_security/core.py

@@ -119,6 +119,7 @@
     "URL_PREFIX": None,
     "SUBDOMAIN": None,
     "FLASH_MESSAGES": True,
+    "RETURN_GENERIC_RESPONSES": False,
     "I18N_DOMAIN": "flask_security",
     "I18N_DIRNAME": pkg_resources.resource_filename("flask_security", "translations"),
     "EMAIL_VALIDATOR_ARGS": None,
@@ -350,6 +351,21 @@
 #: Default Flask-Security messages
 _default_messages = {
     "API_ERROR": (_("Input not appropriate for requested API"), "error"),
+    "GENERIC_AUTHN_FAILED": (
+        _("Authentication failed - identity or password/passcode invalid"),
+        "error",
+    ),
+    "GENERIC_RECOVERY": (
+        _(
+            "If that email address is in our system, "
+            "you will receive an email describing how to reset your password."
+        ),
+        "info",
+    ),
+    "GENERIC_US_SIGNIN": (
+        _("If that identity is in our system, you were sent a code."),
+        "info",
+    ),
     "UNAUTHORIZED": (_("You do not have permission to view this resource."), "error"),
     "UNAUTHENTICATED": (
         _("You are not authenticated. Please supply the correct credentials."),
@@ -458,6 +474,7 @@
         _("You can only access this endpoint when not logged in."),
         "error",
     ),
+    "CODE_HAS_BEEN_SENT": (_("Code has been sent."), "info"),
     "FAILED_TO_SEND_CODE": (_("Failed to send code. Please try again later"), "error"),
     "TWO_FACTOR_INVALID_TOKEN": (_("Invalid code"), "error"),
     "TWO_FACTOR_LOGIN_SUCCESSFUL": (_("Your code has been confirmed"), "success"),