DD 67: Merchant Self Provisioning

11.67. DD 67: Merchant Self Provisioning#

Status: incomplete draft (2025-07-31)

11.67.1. Summary#

The self-provisioning feature allows merchants sign up for their own Taler Merchant Backend instance.

11.67.2. Motivation#

It’s not feasible for non-technical merchants that want to use Taler to set up their own server with a merchant backend instance running.

11.67.3. Requirements#

  • The self-provisioning should be completely automatic, manual actions of the the service provider must be kept at a minimum.

11.67.4. Timeline#

Ideally, available by Sept. 1st 2025.

11.67.5. Proposed Solution#

Implementation tasks:

  • Merchant backend

    • A sysadmin tool to skip the requirement of 2fa channel for instances that are not self provisioned (like blog)

    • New configuration option ALLOW_SIGNUP: boolean in [merchant] section with default to false

    • New public endpoint for self-provisioned instance creation

    • New (private) endpoints for 2FA channel confirmation

    • New public endpoints for password reset

    • Changed endpoint for instance details (must include email/phone)

    • Database schema changes / migration

      • Ideally with migration test

  • Merchant SPA:

    • onboarding page

    • password reset flow

    • new email/phone field in instance details

Documentation tasks:

  • New options for self-provisioning documented in man page

  • API changes documented in API docs

  • Setup of 2FA providers (via helper scripts) documented in merchant operator manual

Deployment tasks:

  • Integrated self-provisioning in sandcastle-ng

Testing tasks:

  • taler-harness tests for self provisioning

  • test steps added to docs.taler.net

  • test steps run as part of final QC

11.67.6. Flows#

Signup:

  • User goes to the merchant SPA in their browser

  • User selects sign-up option

  • User enters details, incl. phone number and e-mail

  • Backend sends 2FA confirmation codes to user

  • User enters 2FA codes on website

    • User can re-request 2FA codes after cooldown, limited attempts

  • Once 2FA channels are confirmed by the backend, user has full access to the merchant backend instance.

    • While 2FA confirmation is pending, password login works, but only limited actions (i.e.: only entering the confirmation code, requesting new codes) are available.

Password reset:

  • User selects “Forgot Password” option on the login screen

  • User enters their username

  • Backend sends E-Mail and SMS verification codes to the user

  • User enters 2FA codes on website

  • On successful validation of 2FA codes, user can enter new password

    • User can re-request 2FA codes after cooldown, limited attempts

  • User can log in with their new password

11.67.7. UI Structure Mocks#

New login page:

Login required

Username: [ ... ]
Password: [ ... ]

[Confirm]
---
[Sign up] [Forgot Password]

Signup page:

Please enter your information to create a new merchant instance:

Username: [ ... ]
Password: [ ... ]
E-Mail*: [ ... ]
Phone number*: [ ... ]

* This information is used to restore access to your account

11.67.8. Definition of Done#

11.67.9. Drawbacks and Alternatives#

  • The name might be too technical. Maybe call it “self onboarding” or “self sign-up”?

  • Merchants need to fully trust the provider.

  • Multi-tenancy always has some negative security implementations

    • Alternative: Deploy separate merchant backends per user instead of deploying an instance, in order to avoid multi-tenancy drawbacks.

11.67.10. Scope#

Explicitly out of scope for now are:

  • Invitation links (i.e. closed self sign-ups)

  • Manual approval of sign-ups. For now, sign-ups are automatically approved/active.

  • 2FA for login

  • 2FA for particular operations (e.g. changing bank account)

But we may want to restrict the phone number area code so we should handle the case that some particular phone can’t be use for signup.

11.67.11. Integration Tests#

These are scenarios that we consider basic and we should have an integration test for every one of them to know that the spec is implemented properly:

  • A merchant doing an account’s registration should get an email/phone notification with the comfirmation code. The merchant account should be in created state and only after using the confirmation code the account can be activated.

  • A merchant with an activated account can call “forgot password”. Merchant should get a notification with the confirmation code that can be used to call the endpoint to change the password. A new login the with new password needs to be tested.

  • An user that makes an amount of request above the threshold should get 429 for “sign up” or “forgot password” endpoints.

  • A merchant that doesn’t have an activated account may be able to set and change all the configuration. But backend won’t take any action with it (for example, it won’t check KYC status). It may be also possible to delete the instance.

11.67.13. Discussion / Q&A#

  • Can the merchant delete their own instance? Or is it some support request via e-mail?

  • How does the instance user known the admin/support contact? Is there some page for that in the side-bar? Or is this external to the feature?

  • What happens while the 2FA channels aren’t confirmed yet? What happens if ONE of the channels is not confirmed?