feat(recoverable): Add support for username recovery via simple login flows

CHANGES.rst

@@ -9,6 +9,7 @@ Version 5.6.0
 Features & Improvements
 +++++++++++++++++++++++
 - (:issue:`1038`) Add support for 'secret_key' rotation
+- (:issue:`980`) Add support for username recovery in simple login flows
 
 Version 5.5.2
 -------------

docs/api.rst

@@ -231,6 +231,8 @@ Forms
 .. autoclass:: flask_security.ChangeEmailForm
 .. autoclass:: flask_security.ChangePasswordForm
 .. autoclass:: flask_security.ConfirmRegisterForm
+.. autoclass:: flask_security.Form
+.. autoclass:: flask_security.FormInfo
 .. autoclass:: flask_security.ForgotPasswordForm
 .. autoclass:: flask_security.LoginForm
 .. autoclass:: flask_security.MfRecoveryCodesForm
@@ -239,23 +241,22 @@ Forms
 .. autoclass:: flask_security.RegisterForm
 .. autoclass:: flask_security.ResetPasswordForm
 .. autoclass:: flask_security.SendConfirmationForm
-.. autoclass:: flask_security.TwoFactorVerifyCodeForm
-.. autoclass:: flask_security.TwoFactorSetupForm
-.. autoclass:: flask_security.TwoFactorSelectForm
 .. autoclass:: flask_security.TwoFactorRescueForm
+.. autoclass:: flask_security.TwoFactorSelectForm
+.. autoclass:: flask_security.TwoFactorSetupForm
+.. autoclass:: flask_security.TwoFactorVerifyCodeForm
 .. autoclass:: flask_security.UnifiedSigninForm
 .. autoclass:: flask_security.UnifiedSigninSetupForm
 .. autoclass:: flask_security.UnifiedSigninSetupValidateForm
 .. autoclass:: flask_security.UnifiedVerifyForm
+.. autoclass:: flask_security.UsernameRecoveryForm
 .. autoclass:: flask_security.VerifyForm
+.. autoclass:: flask_security.WebAuthnDeleteForm
 .. autoclass:: flask_security.WebAuthnRegisterForm
 .. autoclass:: flask_security.WebAuthnRegisterResponseForm
 .. autoclass:: flask_security.WebAuthnSigninForm
 .. autoclass:: flask_security.WebAuthnSigninResponseForm
-.. autoclass:: flask_security.WebAuthnDeleteForm
 .. autoclass:: flask_security.WebAuthnVerifyForm
-.. autoclass:: flask_security.Form
-.. autoclass:: flask_security.FormInfo
 
 .. _signals_topic:
 
@@ -385,6 +386,13 @@ sends the following signals.
 
     .. versionadded:: 3.3.0
 
+.. data:: username_recovery_email_sent
+
+    Sent when a username is successfully recovered and sent over email. In addition to the
+    app (which is the sender), it is passed the `user` argument.
+
+    .. versionadded:: 5.6.0
+
 .. data:: us_security_token_sent
 
     Sent when a unified sign in access code is sent. In addition to the app

docs/configuration.rst

@@ -1155,6 +1155,38 @@ Recoverable
 
     Default: ``_("Your password has been reset")``.
 
+.. py:data:: SECURITY_USERNAME_RECOVERY
+
+   Specifies whether username recovery is enabled.
+
+   Default: ``False``.
+
+   .. versionadded:: 5.6.0
+
+.. py:data:: SECURITY_USERNAME_RECOVERY_URL
+
+    Specifies the username recovery URL.
+
+    Default: ``"/recover-username"``.
+
+    .. versionadded:: 5.6.0
+
+.. py:data:: SECURITY_EMAIL_SUBJECT_USERNAME_RECOVERY
+
+   Sets subject for the username recovery email.
+
+   Default: ``_("Your requested username")``.
+
+   .. versionadded:: 5.6.0
+
+.. py:data:: SECURITY_USERNAME_RECOVERY_TEMPLATE
+
+   Specifies the path to the template for the username recovery page.
+
+   Default: ``"security/recover_username.html"``.
+
+   .. versionadded:: 5.6.0
+
 Change-Email
 ------------
 .. versionadded:: 5.5.0
@@ -1935,6 +1967,7 @@ A list of all templates:
 * :py:data:`SECURITY_TWO_FACTOR_VERIFY_CODE_TEMPLATE`
 * :py:data:`SECURITY_TWO_FACTOR_SELECT_TEMPLATE`
 * :py:data:`SECURITY_TWO_FACTOR_SETUP_TEMPLATE`
+* :py:data:`SECURITY_USERNAME_RECOVERY_TEMPLATE`
 * :py:data:`SECURITY_US_SIGNIN_TEMPLATE`
 * :py:data:`SECURITY_US_SETUP_TEMPLATE`
 * :py:data:`SECURITY_US_VERIFY_TEMPLATE`

docs/customizing.rst

@@ -18,6 +18,7 @@ following is a list of view templates:
 * `security/login_user.html`
 * `security/mf_recovery.html`
 * `security/mf_recovery_codes.html`
+* `security/recover_username.html`
 * `security/register_user.html`
 * `security/reset_password.html`
 * `security/change_password.html`
@@ -178,6 +179,7 @@ The following is a list of all the available form overrides:
 * ``us_setup_form``: Unified sign in setup form
 * ``us_setup_validate_form``: Unified sign in setup validation form
 * ``us_verify_form``: Unified sign in verify form
+* ``username_recovery_form``: Username recovery form
 * ``wan_delete_form``: WebAuthn delete a registered key form
 * ``wan_register_form``: WebAuthn initiate registration ceremony form
 * ``wan_register_response_form``: WebAuthn registration ceremony form
@@ -366,6 +368,8 @@ The following is a list of email templates:
 * `security/email/confirmation_instructions.txt`
 * `security/email/login_instructions.html`
 * `security/email/login_instructions.txt`
+* `security/email/username_recovery.html`
+* `security/email/username_recovery.txt`
 * `security/email/reset_instructions.html`
 * `security/email/reset_instructions.txt`
 * `security/email/reset_notice.html`
@@ -448,6 +452,7 @@ welcome_existing                SECURITY_SEND_REGISTER_EMAIL         SECURITY_EM
                                 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
+username_recovery               SECURITY_USERNAME_RECOVERY           SECURITY_EMAIL_SUBJECT_USERNAME_RECOVERY          - user                 username_recovery_email_sent
 =============================   ==================================   =============================================     ====================== ===============================
 
 When sending an email, Flask-Security goes through the following steps:

docs/openapi.yaml

@@ -646,6 +646,50 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/DefaultJsonErrorResponse"
+  /recover-username:
+    get:
+      summary: GET username recovery form
+      responses:
+        200:
+          description: Username recovery form
+          content:
+            text/html:
+              schema:
+                type: string
+                description: render_template(SECURITY_USERNAME_RECOVERY_TEMPLATE)
+                example: render_template(SECURITY_USERNAME_RECOVERY_TEMPLATE)
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DefaultJsonResponseNoUser"
+    post:
+      summary: Request username recovery
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RecoverUsername"
+          application/x-www-form-urlencoded:
+            schema:
+              $ref: "#/components/schemas/RecoverUsername"
+      responses:
+        200:
+          description: Send username recovery email
+          content:
+            text/html:
+              schema:
+                type: string
+                description: render_template(SECURITY_USERNAME_RECOVERY_TEMPLATE)
+                example: render_template(SECURITY_USERNAME_RECOVERY_TEMPLATE)
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DefaultJsonResponseNoUser"
+        400:
+          description: Error when trying to send recovery email (e.g. user doesn't exist)
+          content:
+            application/json:
+              schema:
+                $ref: "#components/schemas/DefaultJsonErrorResponse"
   /confirm:
     get:
       summary: GET send confirmation form
@@ -2231,6 +2275,14 @@ components:
           type: string
           description: >
             Email address to send link email to.
+    RecoverUsername:
+      type: object
+      required: [email]
+      properties:
+        email:
+          type: string
+          description: >
+            Email address associated with the account.
     UsSignin:
       type: object
       required: [identity, passcode]

flask_security/__init__.py

@@ -45,20 +45,21 @@
     unauth_csrf,
 )
 from .forms import (
-    Form,
     ChangePasswordForm,
+    ConfirmRegisterForm,
+    Form,
     ForgotPasswordForm,
     LoginForm,
+    PasswordlessLoginForm,
     RegisterForm,
     ResetPasswordForm,
-    PasswordlessLoginForm,
-    ConfirmRegisterForm,
     SendConfirmationForm,
     TwoFactorRescueForm,
     TwoFactorSetupForm,
     TwoFactorVerifyCodeForm,
-    VerifyForm,
     unique_identity_attribute,
+    UsernameRecoveryForm,
+    VerifyForm,
 )
 from .mail_util import MailUtil, EmailValidateException
 from .oauth_glue import OAuthGlue
@@ -87,6 +88,7 @@
     user_confirmed,
     user_registered,
     user_not_registered,
+    username_recovery_email_sent,
     us_security_token_sent,
     us_profile_changed,
     wan_deleted,

flask_security/core.py

@@ -51,6 +51,7 @@
     TwoFactorVerifyCodeForm,
     TwoFactorSetupForm,
     TwoFactorRescueForm,
+    UsernameRecoveryForm,
     VerifyForm,
     get_register_username_field,
     login_username_field,
@@ -289,6 +290,7 @@
     "EMAIL_SUBJECT_PASSWORD_NOTICE": _("Your password has been reset"),
     "EMAIL_SUBJECT_PASSWORD_CHANGE_NOTICE": _("Your password has been changed"),
     "EMAIL_SUBJECT_PASSWORD_RESET": _("Password reset instructions"),
+    "EMAIL_SUBJECT_USERNAME_RECOVERY": _("Your requested username"),
     "EMAIL_PLAINTEXT": True,
     "EMAIL_HTML": True,
     "EMAIL_SUBJECT_TWO_FACTOR": _("Two-factor Login"),
@@ -325,6 +327,9 @@
         "webauthn": "flask_security.webauthn.WebAuthnTfPlugin",
     },
     "UNIFIED_SIGNIN": False,
+    "USERNAME_RECOVERY": False,
+    "USERNAME_RECOVERY_TEMPLATE": "security/recover_username.html",
+    "USERNAME_RECOVERY_URL": "/recover-username",
     "US_SETUP_SALT": "us-setup-salt",
     "US_SIGNIN_URL": "/us-signin",
     "US_SIGNIN_SEND_CODE_URL": "/us-signin/send-code",
@@ -642,6 +647,10 @@
         ),
         "success",
     ),
+    "USERNAME_RECOVERY_REQUEST": (
+        _("If registered, your username will be sent to your email."),
+        "info",
+    ),
 }
 
 
@@ -1151,6 +1160,7 @@ class Security:
     :param two_factor_select_form: set form for selecting between active 2FA methods
     :param mf_recovery_codes_form: set form for retrieving and setting recovery codes
     :param mf_recovery_form: set form for multi factor recovery
+    :param username_recovery_form: set form for the username recovery view
     :param us_signin_form: set form for the unified sign in view
     :param us_setup_form: set form for the unified sign in setup view
     :param us_setup_validate_form: set form for the unified sign in setup validate view
@@ -1220,6 +1230,8 @@ class Security:
     .. versionadded:: 5.5.0
         ``change_email_form`` in support of the
          :ref:`Change-Email<configuration:change-email>` feature.
+    .. versionadded:: 5.6.0
+        ``username_recovery_form``
 
     .. deprecated:: 4.0.0
         ``send_mail`` and ``send_mail_task``. Replaced with ``mail_util_cls``.
@@ -1278,6 +1290,7 @@ def __init__(
         phone_util_cls: t.Type[PhoneUtil] = PhoneUtil,
         render_template: t.Callable[..., str] = default_render_template,
         totp_cls: t.Type[Totp] = Totp,
+        username_recovery_form: t.Type[UsernameRecoveryForm] = UsernameRecoveryForm,
         username_util_cls: t.Type[UsernameUtil] = UsernameUtil,
         webauthn_util_cls: t.Type[WebauthnUtil] = WebauthnUtil,
         mf_recovery_codes_util_cls: t.Type[MfRecoveryCodesUtil] = MfRecoveryCodesUtil,
@@ -1325,6 +1338,7 @@ def __init__(
             "two_factor_select_form": FormInfo(cls=two_factor_select_form),
             "mf_recovery_codes_form": FormInfo(cls=mf_recovery_codes_form),
             "mf_recovery_form": FormInfo(cls=mf_recovery_form),
+            "username_recovery_form": FormInfo(cls=username_recovery_form),
             "us_signin_form": FormInfo(cls=us_signin_form),
             "us_setup_form": FormInfo(cls=us_setup_form),
             "us_setup_validate_form": FormInfo(cls=us_setup_validate_form),
@@ -1466,6 +1480,7 @@ def init_app(
             "two_factor_select_form",
             "mf_recovery_form",
             "mf_recovery_codes_form",
+            "username_recovery_form",
             "us_signin_form",
             "us_setup_form",
             "us_setup_validate_form",

flask_security/forms.py

@@ -871,6 +871,12 @@ class TwoFactorRescueForm(Form):
     submit = SubmitField(get_form_field_label("submit"))
 
 
+class UsernameRecoveryForm(Form, UserEmailFormMixin):
+    """The username recovery form"""
+
+    submit = SubmitField(get_form_field_label("recover_username"))
+
+
 class DummyForm(Form):
     """A dummy form for json responses"""
 

flask_security/recoverable.py

@@ -11,7 +11,11 @@
 
 from flask import current_app
 from .proxies import _security, _datastore
-from .signals import password_reset, reset_password_instructions_sent
+from .signals import (
+    password_reset,
+    reset_password_instructions_sent,
+    username_recovery_email_sent,
+)
 from .utils import (
     config_value,
     get_token_status,
@@ -114,3 +118,22 @@ def update_password(user, password):
         _async_wrapper=current_app.ensure_sync,
         user=user,
     )
+
+
+def send_username_recovery_email(user):
+    """Sends the username recovery email for the specified user.
+    :param user: The user requesting username recovery
+    """
+    if config_value("USERNAME_RECOVERY"):
+        send_mail(
+            config_value("EMAIL_SUBJECT_USERNAME_RECOVERY"),
+            user.email,
+            "username_recovery",
+            user=user,
+            username=user.username,
+        )
+        username_recovery_email_sent.send(
+            current_app._get_current_object(),
+            _async_wrapper=current_app.ensure_sync,
+            user=user,
+        )

flask_security/signals.py

@@ -53,3 +53,5 @@
 change_email_instructions_sent = signals.signal("change-email-instructions-sent")
 
 change_email_confirmed = signals.signal("change-email")
+
+username_recovery_email_sent = signals.signal("username-recovery-email-sent")

flask_security/templates/security/email/username_recovery.html

@@ -0,0 +1,8 @@
+{# This template receives the following context:
+  user - the entire user model object
+#}
+
+<p>{{ _fsdomain("Hello,") }}</p>
+<p>{{ _fsdomain("You recently requested to recover your username.") }}</p>
+<p>{{ _fsdomain("Your username is: %(username)s", username=user.username) }}</p>
+<p>{{ _fsdomain("If you did not initiate this request, you can safely ignore this email.") }}</p>

flask_security/templates/security/email/username_recovery.txt

@@ -0,0 +1,8 @@
+{# This template receives the following context:
+  user - the entire user model object
+#}
+
+{{ _fsdomain("Hello,") }}
+{{ _fsdomain("You recently requested to recover your username.") }}
+{{ _fsdomain("Your username is: %(username)s", username=user.username) }}
+{{ _fsdomain("If you did not initiate this request, you can safely ignore this email.") }}