commit 80399cdaf0b98d9b6b16cab5eaf0b48e9e540c42
parent f77cc1a260a6715e204bf121498347d599b1abbc
Author: Florian Dold <dold@taler.net>
Date: Fri, 4 Sep 2026 21:36:34 +0200
merchant docs: document password-change MFA option
Issue: https://bugs.taler.net/n/11771
Diffstat:
4 files changed, 30 insertions(+), 3 deletions(-)
diff --git a/core/merchant/post-management-instances-INSTANCE-auth.rst b/core/merchant/post-management-instances-INSTANCE-auth.rst
@@ -13,7 +13,11 @@
`InstanceAuthConfigurationMessage`. Requests to the instance's own
``/private/auth`` endpoint use an `InstanceAuthChangeRequest` and must
reauthenticate with the current password whenever the existing
- authentication method is ``token``.
+ authentication method is ``token``. If ``PASSWORD_CHANGE_MFA`` is enabled,
+ the merchant must additionally solve one usable challenge from the channels
+ listed in ``MANDATORY_TAN_CHANNELS``. When several channels are available,
+ they are returned with ``combi_and`` set to false so the merchant may choose
+ any one of them.
**Response:**
@@ -26,7 +30,8 @@
the ``/private`` path is returned with
``TALER_EC_MERCHANT_PRIVATE_POST_INSTANCE_AUTH_BAD_OLD_PASSWORD``.
:http:statuscode:`403 Forbidden`:
- MFA channels are not available for this instance.
+ ``PASSWORD_CHANGE_MFA`` is enabled, but no configured MFA channel is
+ available for this instance.
Returned with ``TALER_EC_MERCHANT_GENERIC_MFA_MISSING``.
:http:statuscode:`404 Not found`:
This instance is unknown and thus cannot be reconfigured.
diff --git a/design-documents/049-auth.rst b/design-documents/049-auth.rst
@@ -224,7 +224,10 @@ itself to replace password authentication. A merchant changing its own
password must reauthenticate with the current password, which the backend
checks against its stored password hash. An administrator resetting another
instance's authentication is exempt because the administrative credential is
-the authority for that operation.
+the authority for that operation. Deployments may additionally set
+``PASSWORD_CHANGE_MFA`` to require one usable channel from
+``MANDATORY_TAN_CHANNELS`` as a second factor. If multiple channels are
+available, successfully solving any one of them is sufficient.
Forgotten-password recovery cannot provide the current password. The public
merchant recovery endpoint therefore requires all channels configured in
diff --git a/manpages/taler-merchant.conf.5.rst b/manpages/taler-merchant.conf.5.rst
@@ -171,6 +171,14 @@ MANDATORY_TAN_CHANNELS
mandatory: listing both requires both challenges, while listing only one
requires only that challenge.
+PASSWORD_CHANGE_MFA
+ Set to ``YES`` to require a merchant changing its own password to solve one
+ additional challenge using a channel from ``MANDATORY_TAN_CHANNELS``. If
+ multiple usable channels are configured, the merchant may choose any one of
+ them. The current password remains required. Enabling this option without
+ configuring at least one mandatory TAN channel is invalid. Defaults to
+ ``NO``.
+
PHONE_REGEX
Posix regular expression specifying which phone numbers are acceptable for
the instances. Useful to restrict phone numbers to those that work
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
@@ -850,6 +850,17 @@ demonstrate control over the e-mail address and phone number provided,
and can thus later reset their password without needing support from
the administrator.
+To also require one of these channels as a second factor when a merchant
+changes its password, set:
+
+.. code-block:: ini
+
+ [MERCHANT]
+ PASSWORD_CHANGE_MFA = YES
+
+The current password is still required. When both SMS and e-mail are usable,
+the merchant may complete either challenge.
+
.. index:: instance
.. _Instance-setup:
