commit 078601848f8b06cf283180f6481a9090a99d0850
parent 1c467da677e2a79492a792aaff4770d560de99ca
Author: Christian Grothoff <christian@grothoff.org>
Date: Sat, 10 Oct 2026 21:37:52 +0200
transition to more strict v19 enforcement
Diffstat:
3 files changed, 21 insertions(+), 2 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -227,6 +227,8 @@ Currently, the ``/private/auth/`` API supports two main authentication methods i
``$TOKEN`` is an authentication token retrieved from the ``/private/token`` endpoint using basic authorization.
The respective username is the instance ``$ID``, and the password the instance password (``$INSTANCE_PASSWORD``).
A login token is commonly only valid for a limited period of time and scoped to specific permissions.
+ A login token that is unknown or has expired is rejected with a ``401 Unauthorized``
+ and ``TALER_EC_GENERIC_TOKEN_UNKNOWN`` or ``TALER_EC_GENERIC_TOKEN_EXPIRED`` respectively.
If the ``$INSTANCE_PASSWORD`` is lost, the administrator can set a password
using the ``taler-merchant-passwd`` command-line tool.
* ``token`` (@deprecated since **v19**): With this method, the client must provide an authentication token in
@@ -234,8 +236,16 @@ Currently, the ``/private/auth/`` API supports two main authentication methods i
The behaviour is then equivalent to the ``token`` method above.
Any API may be accessed using the bearer authentication ``secret-token: $INSTANCE_PASSWORD``.
Notice that this behaviour is deprecated and will be phased out in favor of login tokens.
-
-For testing, the service may be started with the configuration option ``DISABLED_AUTHENTICATION = YES``
+ The bearer token is only interpreted as the instance password if it is not a well-formed login token.
+ The backend refuses the instance password as a bearer token if the instance has a usable MFA channel
+ (a validated e-mail address with ``HELPER_EMAIL`` configured, or a validated phone number
+ with ``HELPER_SMS`` configured), as it would bypass the MFA required by ``/private/token``,
+ and always if the backend runs with ``STRICT_PROTOCOL_V19 = YES``.
+ Such requests fail with a ``401 Unauthorized`` and ``TALER_EC_MERCHANT_GENERIC_UNAUTHORIZED``.
+ Clients must then obtain a login token from ``/private/token`` using basic authorization;
+ for instances with MFA, that request requires solving MFA challenges.
+
+For testing, the service may be started with the configuration option ``DISABLE_AUTHENTICATION = YES``
in section ``[merchant]`` (@since **v20**).
.. _merchant-api-scopes:
diff --git a/core/merchant/post-instances-INSTANCE-forgot-password.rst b/core/merchant/post-instances-INSTANCE-forgot-password.rst
@@ -39,6 +39,12 @@
The uploaded body is to long, it exceeds the size limit.
Returned with an error code of
``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
+ :http:statuscode:`429 Too many requests`:
+ The request would have to start new MFA challenges, but a previous
+ password reset of this instance was started less than 15 minutes ago
+ and has not been completed. Any successful change of the instance
+ password lifts this limit immediately.
+ Returned with ``TALER_EC_MERCHANT_TAN_TOO_EARLY``.
:http:statuscode:`500 Internal Server Error`:
The server experienced an internal failure.
Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
diff --git a/manpages/taler-merchant.conf.5.rst b/manpages/taler-merchant.conf.5.rst
@@ -198,6 +198,9 @@ HELPER_EMAIL
STRICT_PROTOCOL_V19
Set to YES to strictly enforce protocol version 19 or later. Transient option for development.
+ Then the "external" authentication method is rejected when creating an instance or
+ changing its authentication, and the instance password is no longer accepted as a
+ bearer token (clients must use login tokens).
PAYMENT_TARGET_TYPES
Space-separated list of allowed payment target types (like bitcoin, iban or x-taler-bank).
