commit e0092fd72a50a357b9a4af7906e975877f72db0b
parent ecd18a4d29c325ac43e4f849a3235df4bdbb1b25
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 9 Sep 2025 13:35:02 +0200
document MFA and self-provisioning (fixes #10379)
Diffstat:
1 file changed, 61 insertions(+), 0 deletions(-)
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
@@ -746,6 +746,67 @@ Production systems should additionally be configured to bind to a UNIX domain so
and use TLS for improved network privacy, see :ref:`Secure setup <Secure-setup>`.
+Multi-factor authentication
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The merchant backend supports multi-factor authentication for critical
+endpoints, including issuing access token, changing login credentials,
+modifying the bank account and deleting the instance. To use
+multi-factor authentication, the merchant backend must be configured
+with helper programs that can be used to send e-mails or SMS messages.
+
+
+.. code-block:: ini
+
+ [MERCHANT]
+ HELPER_SMS = sms_helper.sh
+ HELPER_EMAIL = email_helper.sh
+
+These scripts will be called by the merchant backend with the
+first argument being the phone number or the e-mail address, and
+with the message with the TAN code to send to the user on standard
+input. The shell scripts must exit with a status code of 0 on
+success. A trivial e-mail helper would look like this:
+
+.. code-block:: sh
+
+ #!/bin/sh
+ exec mail --subject="TAN code for the Taler merchant backend" "$1"
+
+Here, ``mail`` refers to the classic UNIX mail command.
+Example scripts can also be found in the `GNU Anastasis Git
+<https://git.taler.net/anastasis.git/tree/src/authorization>`_.
+
+
+Self-provisioning
+^^^^^^^^^^^^^^^^^
+
+Self-provisioning allows anyone to create a merchant instance. This
+is useful if a merchant backend is offered as a public service. In this
+case, you should set:
+
+.. code-block:: ini
+
+ [MERCHANT]
+ ENABLE_SELF_PROVISIONING = YES
+
+
+To enable self-provisioned users to reset their passwords if they
+forgot them, the merchant backend requires two other authentication
+methods to be available and validated when the instance is
+self-provisioned. This can be enabled using:
+
+.. code-block:: ini
+
+ [MERCHANT]
+ MANDATORY_TAN_CHANNELS = sms email
+
+With this setting, users that self-provision an instance must first
+demonstrate control over the e-mail address and phone number provided,
+and can thus later reset their password without needing support from
+the administrator.
+
+
.. index:: instance
.. _Instance-setup:
