014-merchant-backoffice-ui.rst (4515B)
1 DD 14: Merchant backoffice UI 2 ############################# 3 4 :Design status: Accepted 5 :Implementation status: Implemented 6 :DD shepherd: TBD 7 :Historical contributors: Thien-Thi Nguyen, Christian Grothoff 8 :First published: 2021-01-30 9 :Last substantive change: 2024-02-08 10 :Implementation evidence: merchant (2021-08-05) 11 :Normative references: :doc:`../taler-merchant-manual`, :doc:`../core/api-merchant` 12 13 .. note:: 14 15 The user stories below record the original UI design. The current merchant 16 manual and API authentication specification are authoritative. 17 18 Motivation 19 ========== 20 21 The merchant should have a user-friendly way to manage the merchant backend. 22 The implemented single-page application uses the HTTP+JSON RESTful API 23 (:doc:`../core/api-merchant`). 24 25 26 Security Architecture 27 ===================== 28 29 Either (simple deployment): 30 31 Internal auth (via API key, user directly downloads SPA, asked to enter 32 API key). See: https://bugs.gnunet.org/view.php?id=6731 33 34 API token/key is persisted (by SPA) in local storage of browser until 35 you explicitly logout. 36 37 Or (large company with existing authentication infrastructure): 38 39 External auth: 40 41 1. Login flow via reverse proxy for authentication: 42 43 BROWSER -> AUTH-PROXY -> (likely) redirect to login server 44 45 2. AUTH-PROXY may redirect to login server, passes authentication token 46 via URL param when redirecting back to the AUTH-PROXY for the SPA 47 download 48 49 BROWSER -> AUTH-PROXY -> SPA (download HTML/JS from backend) 50 51 3. Running SPA: 52 53 SPA-in-BROWSER -> AUTH-PROXY -> BACKEND 54 55 https://backend/instance/foo/ 56 57 - Browser shows login dialog (401 Unauthorized, say). 58 59 - AUTH-PROXY is happy, allows download of HTML. 60 61 - All requests from SPA are then automatically auth'ed because the 62 browser KNOWS already how to bypass the auth-proxy (token 63 validation, etc). 64 65 66 User stories 67 ============ 68 69 Story #1: Login 70 --------------- 71 72 1. User loads SPA at say https://backend/instance/$FOO/ 73 74 2. SPA asks for authorization IF an API key is specified/required by the 75 merchant backend for the respective instance. 76 77 Note: we have several authorization methods: 78 79 - HTTP ``Authorization`` header with a bearer token 80 81 - (maybe?) username / password 82 83 - (maybe?) theoretically: TLS client certificates (maybe much later) 84 85 Additionally, the user may specify which instance to log into, as 86 different instances may use different credentials. So the SPA needs to 87 fetch the list of instances. 88 89 3. Special case: If there are no instances, the ``admin`` instance MUST 90 be used, and the login should immediately move on to the ``setup`` 91 (admin) instance dialog, forcing the user to setup the admin 92 instance upon first login. 93 94 4. After login, we (somehow) need to persist the login data in the SPA. 95 Local storage or just global variable in the JS? Local storage may be 96 better to survive page reload, right? 97 98 Q: How does the SPA know about the base URL? In the LibEuFin UI, it's 99 part of the login page. 100 101 A: Just use relative URLs to its own location? => Possible, but might 102 now always be the case 103 104 => Could use relative URL by default, maybe have a field to allow user to 105 override? => Makes sense. 106 107 5. LOGOUT button to reset state and go back to login page. 108 109 6. "Change instance" drop-down, to change instance without having to log 110 in again IF the credentials are the same? 111 112 113 Story #2: Manage instances 114 -------------------------- 115 116 This involves only the ``admin`` instance owner. 117 118 Management operations include: 119 120 - creating an instance (including in particular merchant bank accounts) 121 122 - deleting an instance (with extra confirmation) 123 124 - updating an instance (change in bank accounts) 125 126 Q: Do we have some separate "admin login" to manage instances? Who is 127 actually allowed to manage instances? LibEuFin has some permissions 128 system for this. 129 130 A: The admin instance owner can manage instances. Current authentication and 131 authorization, including scoped login tokens, is specified by the merchant 132 API. 133 134 135 Story #3: View orders and their status, grant refunds 136 ----------------------------------------------------- 137 138 - list all orders (by date, by payment status, etc.) 139 140 - for paid orders, view details (show contract, show already granted 141 refunds, trigger refund) 142 143 144 Story #4: Manage inventory 145 -------------------------- 146 147 - add product to inventory 148 149 - update stock (increase available stock) 150 151 - change product description / price / etc. 152 153 - delete products from inventory