067-merchant-self-provisioning.rst (6284B)
1 DD 67: Merchant Self Provisioning 2 ################################# 3 4 :Design status: Accepted 5 :Implementation status: Implemented 6 :DD shepherd: TBD 7 :Historical contributors: Florian Dold, Sebastian, Christian Grothoff 8 :First published: 2025-07-31 9 :Last substantive change: 2025-08-03 10 :Implementation evidence: taler-typescript-core (2025-08-05), merchant (2025-08-06), sandcastle-ng (2025-10-30) 11 :Normative references: ``core/api-merchant.rst``, ``taler-merchant-manual.rst``, ``manpages/taler-merchant.conf.5.rst`` 12 13 .. note:: 14 15 Self-provisioning is implemented. The API, operator manual and 16 configuration man page are normative where they differ from this planning 17 document. 18 19 Summary 20 ======= 21 22 The self-provisioning feature allows merchants sign up for their own Taler 23 Merchant Backend instance. 24 25 Motivation 26 ========== 27 28 It's not feasible for non-technical merchants that want to use Taler to 29 set up their own server with a merchant backend instance running. 30 31 Requirements 32 ============ 33 34 * The self-provisioning should be completely automatic, 35 manual actions of the service provider must be kept at a minimum. 36 37 Timeline 38 ======== 39 40 The original target was September 1, 2025. The feature subsequently landed; 41 this date is retained as historical planning context. 42 43 Proposed Solution 44 ================= 45 46 Implementation tasks: 47 48 * Merchant backend 49 50 * A sysadmin tool to skip the requirement of 2fa channel for instances that are not self provisioned (like blog) 51 * New configuration option ``ENABLE_SELF_PROVISIONING`` in the 52 ``[MERCHANT]`` section, defaulting to ``NO`` 53 * New public endpoint for self-provisioned instance creation 54 * New (private) endpoints for 2FA channel confirmation 55 * New public endpoints for password reset 56 * Changed endpoint for instance details (must include email/phone) 57 * Database schema changes / migration 58 59 * Ideally with migration test 60 61 * Merchant SPA: 62 63 * onboarding page 64 * password reset flow 65 * new email/phone field in instance details 66 67 Documentation tasks: 68 69 * New options for self-provisioning documented in man page 70 * API changes documented in API docs 71 * Setup of 2FA providers (via helper scripts) documented in merchant operator manual 72 73 Deployment tasks: 74 75 * Integrated self-provisioning in sandcastle-ng 76 77 Testing tasks: 78 79 * taler-harness tests for self provisioning 80 * test steps added to docs.taler.net 81 * test steps run as part of final QC 82 83 Flows 84 ===== 85 86 Signup: 87 88 * User goes to the merchant SPA in their browser 89 * User selects sign-up option 90 * User enters details, incl. phone number and e-mail 91 * Backend sends 2FA confirmation codes to user 92 * User enters 2FA codes on website 93 94 * User can re-request 2FA codes after cooldown, limited attempts 95 96 * Once 2FA channels are confirmed by the backend, user has full 97 access to the merchant backend instance. 98 99 * While 2FA confirmation is pending, password login works, 100 but only limited actions (i.e.: only entering the confirmation code, requesting new codes) are available. 101 102 Password reset: 103 104 * User selects "Forgot Password" option on the login screen 105 * User enters their username 106 * Backend sends E-Mail and SMS verification codes to the user 107 * User enters 2FA codes on website 108 * On successful validation of 2FA codes, user can enter new password 109 110 * User can re-request 2FA codes after cooldown, limited attempts 111 112 * User can log in with their new password 113 114 UI Structure Mocks 115 ================== 116 117 New login page: 118 119 :: 120 121 Login required 122 123 Username: [ ... ] 124 Password: [ ... ] 125 126 [Confirm] 127 --- 128 [Sign up] [Forgot Password] 129 130 Signup page: 131 132 :: 133 134 Please enter your information to create a new merchant instance: 135 136 Username: [ ... ] 137 Password: [ ... ] 138 E-Mail*: [ ... ] 139 Phone number*: [ ... ] 140 141 * This information is used to restore access to your account 142 143 Definition of Done 144 ================== 145 146 * [ ] closure of every child of tracking bug https://bugs.taler.net/n/10224 verified 147 * [x] integration-test coverage added 148 149 Drawbacks and Alternatives 150 ========================== 151 152 * The name might be too technical. Maybe call it "self onboarding" or "self sign-up"? 153 * Merchants need to fully trust the provider. 154 * Multi-tenancy always has some negative security implementations 155 156 * Alternative: Deploy *separate* merchant backends per user instead of deploying an instance, in 157 order to avoid multi-tenancy drawbacks. 158 159 Scope 160 ===== 161 162 Explicitly out of scope *for now* are: 163 164 * Invitation links (i.e. closed self sign-ups) 165 * Manual approval of sign-ups. For now, sign-ups are automatically 166 approved/active. 167 * 2FA for login 168 * 2FA for particular operations (e.g. changing bank account) 169 170 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. 171 172 Integration Tests 173 ================= 174 175 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: 176 177 - 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. 178 - 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. 179 - An user that makes an amount of request above the threshold should get 429 for "sign up" or "forgot password" endpoints. 180 - 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. 181 182 183 Related Efforts 184 =============== 185 186 The corebank API also has 2FA. We should keep the API design as aligned as 187 possible. 188 189 Discussion / Q&A 190 ================ 191 192 * Can the merchant delete their own instance? Or is it some support request via e-mail? 193 * How does the instance user known the admin/support contact? Is there some page for that in the side-bar? 194 Or is this external to the feature? 195 * What happens while the 2FA channels aren't confirmed yet? What happens if ONE of the channels is not confirmed?