089-merchant-2fa.rst (2927B)
1 DD 89: Merchant 2FA UX 2 ###################### 3 4 :Design status: Accepted 5 :Implementation status: Prototype 6 :DD shepherd: TBD 7 :Historical contributors: Florian Dold 8 :First published: 2026-03-03 9 :Last substantive change: 2026-03-03 10 :Implementation evidence: ``taler-typescript-core`` (2026-08-05, not merged into the reviewed HEAD) 11 12 Summary 13 ======= 14 15 This design document describes the user experience for two factor 16 authentication in the merchant portal. 17 18 Motivation 19 ========== 20 21 Users have been confused by the design currently implemented. The 2FA is an 22 important flow and as such should be well designed and documented. 23 24 Requirements 25 ============ 26 27 * At every step of the process, 28 it should be clear to the user what they need to do next. 29 30 Proposed Solution 31 ================= 32 33 We differentiate between two cases: 34 35 * 2FA steps where **all** possible channels have to be validated. This is 36 typically the case for sign-up and password reset. Here, we guide 37 the user one by one. The user can't choose the order. 38 * 2FA steps where **some** channels have to be validated. 39 This is typically the case for log-in and protected 40 operations such as modifying bank account information. 41 Here the user can select which channel to use. 42 43 Common considerations: 44 45 * The cancel button always cancels the whole operation. 46 * Once the backend supports it, 2FA codes should have a dash 47 after every group of 4 digits and start with a common 48 prefix (``TM-`` for the Taler merchant) that is already displayed 49 in the UI. Since we don't know the length of the 2FA code, we can't 50 display boxes directly, but the text field should automatically fill 51 in dashes. 52 53 54 Sign-up 55 ~~~~~~~ 56 57 * These wireframes apply to 2FA where *all* channels need to be validated. The 58 sign-up is taken as an example. 59 * For a sign-up, the UI should display the full phone number / e-mail address. 60 For other operations such as password reset, ``S1.2a/b`` should show 61 the redacted addresses. 62 * In the usual flow, the user sees ``S1.1``, ``S1.2a`` and finally ``S1.1b``. 63 64 65 .. image:: images/089/signup.excalidraw.svg 66 67 68 Authentication 69 ~~~~~~~~~~~~~~ 70 71 * These wireframes apply to 2FA where *some* channels (usually one) need to be 72 validated. Adding a bank account is taken as an example. 73 * We explicitly use a check-box instead of a button, since: 74 75 1. We can pre-select the 2FA option that we consider preferable (cost) 76 2. Instead of having many buttons, there's only one primary action 77 78 * For resending / expired auth codes, see ``S1.2b-e*`` 79 80 .. image:: images/089/auth.excalidraw.svg 81 82 Test Plan 83 ========= 84 85 * Non-trivial UI elements should be tested on mobile (such as the 2FA code entry input 86 element with dashes). 87 88 Discussion / Q&A 89 ================ 90 91 * Do we know beforehand from the API which 2FA channels are required? 92 * When signing up, what if the user mistyped their phone number? 93 Do we offer some affordance to go back and edit that information?