From 270e1f4bdd9061f6432322da51fcccf56d1d4b87 Mon Sep 17 00:00:00 2001 From: Sankalp Thakur Date: Wed, 22 Jul 2026 19:19:52 +0530 Subject: [PATCH] Document SECURITY_TWO_FACTOR and related 2FA config settings Add configuration reference entries for two-factor authentication settings that were only covered in the installation guide. Link the new entries to a dedicated installation walkthrough anchor and reference only the PR in the changelog entry. Fixes #1760 Signed-off-by: Sankalp Thakur --- documentation/changelog.rst | 1 + documentation/configuration.rst | 57 +++++++++++++++++++++++++++++ documentation/host/installation.rst | 2 + 3 files changed, 60 insertions(+) diff --git a/documentation/changelog.rst b/documentation/changelog.rst index 95f8426263..3371e7516a 100644 --- a/documentation/changelog.rst +++ b/documentation/changelog.rst @@ -36,6 +36,7 @@ New features Infrastructure / Support ---------------------- +* Document ``SECURITY_TWO_FACTOR`` and related 2FA configuration settings [see `PR #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 `_] * Upgraded dependencies [see `PR #1485 `_, `PR #2215 `_ and `PR #2243 `_] * Prepare the ``device_scheduler`` to deal with commitments per device group [see `PR #1934 `_] diff --git a/documentation/configuration.rst b/documentation/configuration.rst index 603ef848af..4e59258d4f 100644 --- a/documentation/configuration.rst +++ b/documentation/configuration.rst @@ -521,6 +521,62 @@ 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 @@ -528,6 +584,7 @@ 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`` diff --git a/documentation/host/installation.rst b/documentation/host/installation.rst index e99ce2f07e..36073a8a8a 100644 --- a/documentation/host/installation.rst +++ b/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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^