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

    • 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)

11.67.12. 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?