Document SECURITY_TWO_FACTOR and related 2FA config settings

documentation/changelog.rst

@@ -36,6 +36,7 @@ New features
 
 Infrastructure / Support
 ----------------------
+* Document ``SECURITY_TWO_FACTOR`` and related 2FA configuration settings [see `PR #2340 <https://www.github.com/FlexMeasures/flexmeasures/pull/2340>`_]
 * ``flexmeasures db upgrade`` now runs ``VACUUM ANALYZE`` after upgrading by default, so Postgres has fresh planner statistics right after a migration; opt out with ``--no-vacuum`` [see `PR #2333 <https://www.github.com/FlexMeasures/flexmeasures/pull/2333>`_]
 * Upgraded dependencies [see `PR #1485 <https://www.github.com/FlexMeasures/flexmeasures/pull/1485>`_, `PR #2215 <https://www.github.com/FlexMeasures/flexmeasures/pull/2215>`_ and `PR #2243 <https://www.github.com/FlexMeasures/flexmeasures/pull/2243>`_]
 * Prepare the ``device_scheduler`` to deal with commitments per device group [see `PR #1934 <https://www.github.com/FlexMeasures/flexmeasures/pull/1934>`_]

documentation/configuration.rst

@@ -521,13 +521,70 @@ You can also set this in a file (which some Flask tutorials advise).
 Default: ``None``
 
 
+.. _security_two_factor:
+
+SECURITY_TWO_FACTOR
+^^^^^^^^^^^^^^^^^^^
+
+Whether to require :abbr:`2FA (two-factor authentication)` when users log in to the UI.
+When enabled, FlexMeasures uses :abbr:`TOTP (time-based one-time password)` codes (currently via email).
+
+Strongly recommended for production. FlexMeasures logs a warning on startup if this is left ``False`` in a production environment.
+See :ref:`installation_two_factor` for a short setup walkthrough, and set ``SECURITY_TOTP_SECRETS`` when enabling 2FA.
+
+This setting is also recognized as an environment variable.
+
+Default: ``False``
+
+SECURITY_TWO_FACTOR_ENABLED_METHODS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Which 2FA methods are enabled. FlexMeasures currently supports ``email``; authenticator-app support may be added later.
+
+Default: ``["email"]``
+
+SECURITY_TWO_FACTOR_ALWAYS_VALIDATE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When ``True``, users must complete 2FA on every login.
+Set to ``False`` (together with ``SECURITY_TWO_FACTOR_LOGIN_VALIDITY``) if you want to skip re-validation for a limited time after a successful 2FA check (useful for testing or lower-friction deployments).
+
+Default: ``True``
+
+SECURITY_TWO_FACTOR_LOGIN_VALIDITY
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+How long a successful 2FA validation remains valid when ``SECURITY_TWO_FACTOR_ALWAYS_VALIDATE`` is ``False``.
+Uses a human-readable duration string (as understood by Flask-Security).
+
+Default: ``"1 week"``
+
+SECURITY_TWO_FACTOR_RESCUE_MAIL
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Email address users can contact when they cannot complete the second authentication step
+(for example, if they lost access to their email inbox used for TOTP codes).
+
+By default this falls back to the address part of ``MAIL_DEFAULT_SENDER``, which is often a no-reply address — set an address where hosts can actually help users.
+
+Default: address from ``MAIL_DEFAULT_SENDER`` (if configured as a ``(name, email)`` tuple), otherwise ``None``
+
+SECURITY_TOTP_ISSUER
+^^^^^^^^^^^^^^^^^^^^
+
+Issuer label shown in authenticator apps and related TOTP metadata.
+
+Default: ``"FlexMeasures"``
+
+
 .. _security_totp_secrets:
 
 SECURITY_TOTP_SECRETS
 ^^^^^^^^^^^^^^^^^^^^^
 
 A dictionary with secrets used to sign :abbr:`TOTP (time-based one-time password)` tokens.
 For example, ``{"1": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}``.
+Required when ``SECURITY_TWO_FACTOR`` is enabled.
 
 Default: ``None``
 

documentation/host/installation.rst

@@ -392,6 +392,8 @@ You can go to `http://localhost:5000/tasks/` and see the state of job queues and
 You need to set ``FLEXMEASURES_REDIS_PASSWORD="fm-redis-pass"`` in your `~/.flexmeasures.cfg` config file for this to work. 
 
 
+.. _installation_two_factor:
+
 Two-factor authentication
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^