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