New user onboarding flow

[dennisreimann]

For the new user onboarding flow we assume there is an instance to connect to already.

User Types

There are at least three roles/use cases for the flow of onboarding/initial login:

1. Admin
   • Their account got created when setting up the instance.
   • They could either set up merchant accounts (and stores) in advance or simply offer a registration.
   • Related: #5548
2. Merchant
   • Their account might have been created by the admin or they get to the instance for registering.
   • Manage the store and access roles for their employees.
   • They provide employee accounts by setting them up in advance or let their employees register.
3. Employee
   • Roles like cashier, with limited store access.

Onboarding Approaches

1. Open Instance
   • Users register themselves via shared register link
   • Admin can require email confirmation and approval
2. Invitation based
   • Admin or store owner creates basic user account with email address
   • User gets an email with invite link request to setup the account (confirm email, set password)
     • "You have been invited to INSTANCE/STORE, setup your account here: LINK/QRCODE"

In both scenarios the admin has the option to deactivate user later on.

Invite links

Store Owners and Employees can be provided with a link/qrcode, which is basically an encoded version of ...

• The instance URL to connect to
• An access token we can use on the instance to initially identify them and their setup state, which can either be:
  • Pre-setup by the supervisor role (Admin -> Merchant, Merchant -> Employee)
  • Registration and assignment to the defined role for new users, no prior setup

This is very similar to the flow of connecting a LNDhub-compatible wallet: A custom link scheme which can be handled by our app plus the connection details. Something like this, which can be shared as a link or QR code:

https://SERVER_URL/invite/USER_ID/TOKEN

The app can then transfer this into an API call to https://SERVER_URL/api/app//USER_ID/TOKEN, which handles the setup and responds with the account details for the app.

TODO

• #5714
  • [x] Separate self-registration and invite cases
  • [x] Add invitation email for users created by the admin (right now there is no email when an account is setup with a password)
  • [x] Add handler action for invite links
• #5719
  • [x] Add user creation/invite on the store level (right now one can only add existing users to stores)
  • [x] Improve default role structure

Optional and related

• #5718 — can be incorporated if/when merged.

  • [x] Make instance name configurable to allow for better branding
  • [x] Add contact email address for instance (see #4806)

• [ ] Integrate everything

• [ ] Wording adjustments, e.g. in emails

[pavlenex]

Trying to structure this a bit better:

• Create new custom roles
  • Merchant role = guest role right now?
  • Employee = access to POS?
  • Admin = this role exists already
• Allow admin to invite accounts with pre-assigned roles
  • Currently we can't invite users that are not added, we throw an error
• Generate proper invite link with all custom settings
• Add ability to invite via QR
• #5548

I would assume this issue is only about Creating new custom roles or does it touch more?

[pavlenex]

For the specific roles, perhaps merchant is actually store owner and employee is just guest or is there anything else?

[TChukwuleta]

Hey @pavlenex

I have a question on this:

"Currently we can't invite users that are not added, we throw an error"

Is there a reason to this. If the user doesn't exist, an email invite can be sent to the user. Also, in that case it might also be nice to see a status flag based on if the invite is pending, accepted and registered on the store, etc.

[dennisreimann]

Right now we have those two roles on the server-level:

1. Owner (default)
   • btcpay.store.canmodifystoresettings
   • btcpay.store.cantradecustodianaccount
   • btcpay.store.canwithdrawfromcustodianaccount
   • btcpay.store.candeposittocustodianaccount
2. Guest
   • btcpay.store.canviewstoresettings
   • btcpay.store.canmodifyinvoices
   • btcpay.store.canviewcustodianaccounts
   • btcpay.store.candeposittocustodianaccount

To not interrupt anyone's setup, I'd simply rename "Owner" to "Store Owner" (making it more precise) and add:

3. Employee
   • btcpay.store.canmodifyinvoices
   • btcpay.store.canmodifypaymentrequests
   • btcpay.store.cancreatenonapprovedpullpayments
   • btcpay.store.canviewpayouts
   • btcpay.store.canviewpullpayments
4. Store Manager (optional, mentioning it because we dicussed it some times already):
   • btcpay.store.canviewstoresettings
   • btcpay.store.canmodifyinvoices
   • btcpay.store.webhooks.canmodifywebhooks
   • btcpay.store.canmodifypaymentrequests
   • btcpay.store.canmanagepullpayments
   • btcpay.store.canmanagepayouts
   • btcpay.store.canviewcustodianaccounts
   • btcpay.store.candeposittocustodianaccount

Imho these are sane defaults we can provide as common server-level roles.

When the admin invites new users, they'd start as Store Owner and can invite Employees (and Store Managers) themselves.

[dennisreimann]

I just finished the user approval PR and would continue with this, once #5647 is merged. What do you think about the roles proposed above, @pavlenex @Kukks?

[pavlenex]

I've asked two third-party hosts who use custom roles to provide us more details on what they use so we can flash these out more precisely, will update here when I get a reply.

[dstrukt]

Love the notion of having pre-defined defaults (as we all usually agree on, smart defaults, with the ability to customize as needed), and your list looks great @dennisreimann, concise and clear, probably covers 95% of use-cases outside of custom needs. Using this as a basis for drawing scope around app screens, but curious to hear the feedback from @pavlenex's out-reach.

Other question I might raise is there any distinction between the Owner and an Admin? Should there be?

[dennisreimann]

is there any distinction between the Owner and an Admin?

Yes, the admin manages the whole server/instance, a store owner can only manage their stores.

[pavlenex]

@dennisreimann I've made a table comparing what you outline vs what one of the ambassadors proposed.

Permission	Bitcoin People	D11's Suggestion
Owner
btcpay.store.canmodifystoresettings	✅	✅
btcpay.store.cantradecustodianaccount	✅	✅
btcpay.store.canwithdrawfromcustodianaccount	✅	✅
btcpay.store.candeposittocustodianaccount	✅	✅
Store Admin / Brand Admin
btcpay.store.canmodifystoresettings	✅	❌
Employee
btcpay.store.canmodifyinvoices	✅	✅
btcpay.store.canmodifypaymentrequests	✅	✅
btcpay.store.cancreatenonapprovedpullpayments	✅	✅
btcpay.store.canviewpayouts	✅	✅
btcpay.store.canviewpullpayments	✅	✅
Store Manager
btcpay.store.canviewstoresetting	✅	❌
btcpay.store.canmodifyinvoices	✅	✅
btcpay.store.webhooks.canmodifywebhooks	✅	✅
btcpay.store.canmodifypaymentrequests	✅	✅
btcpay.store.canmanagepullpayments	✅	✅
btcpay.store.canmanagepayouts	✅	✅
btcpay.store.canviewcustodianaccounts	✅	✅
btcpay.store.candeposittocustodianaccount	✅	✅
Employee Readonly
btcpay.store.canviewinvoices	✅	❌
Guest
btcpay.store.canviewstoresettings	❌	✅
btcpay.store.canmodifyinvoices	❌	✅
btcpay.store.canviewcustodianaccounts	❌	✅
btcpay.store.candeposittocustodianaccount	❌	✅

[dennisreimann]

@pavlenex A few notes regarding the roles:

• I think we can omit the Guest role here: We are not changing but rather deprecating it — just leaving it there to not interupt existing users
• Employee Readonly should then also have read permissions for payment requests and maybe even pull payments/payouts
• Store Manager: I'm fine with adding canviewstoresettings
• Store Admin / Brand Admin: Can you inquire about the use case? I'm not convinced yet that it would make sense to have this as a default role, because it sounds very similar to Store Owner and I'd rather avoid ambiguity and make the default case simple. If it's a rather niche case, store owners can always add custom roles and fullfill that use case that way.

[dstrukt]

• Employee Readonly should then also have read permissions for payment requests and maybe even pull payments/payouts
• Store Manager: I'm fine with adding canviewstoresettings
• Store Admin / Brand Admin: Can you inquire about the use case? I'm not convinced yet that it would make sense to have this as a default role, because it sounds very similar to Store Owner and I'd rather avoid ambiguity and make the default case simple. If it's a rather niche case, store owners can always add custom roles and fullfill that use case that way.

ACK to all of the above, and agree wrt minimal groups as possible, we can always add another case/group if we get more feedback like BP

[pavlenex]

• Employee Readonly should then also have read permissions for payment requests and maybe even pull payments/payouts

I agree with what you said, remove all redundancies and let's keep it simple, including not adding brand admin since it's similar to store owner.

Employer readonly may also not be needed, I guess the role is more of a cashier (POS operator) or is there something else?

[dennisreimann]

Some more things to clarify:

• Should we keep pre-setting the user password when inviting users? Otherwise they will have to set it for themselves before initial login.
• Should users invited by an admin be auto approved?
• Should admins also get an email (in addition to the notification) when a new user registered?
• How to handle user approval when invite is made on the store-level? The admin might not know anything about a new user when a store owner invited an employee.
• For how long should an invitation token be valid? I chose 7 days for now.

[pavlenex]

Should we keep pre-setting the user password when inviting users? Otherwise they will have to set it for themselves before initial login.

Having option here like we do is good, people can choose.

Should users invited by an admin be auto approved?

Yes!

Should admins also get an email (in addition to the notification) when a new user registered?

I think that's a good idea.

How to handle user approval when invite is made on the store-level? The admin might not know anything about a new user when a store owner invited an employee.

Good question, I think this may align with our 1.14 where we wanted to give access to stores for server admins as well, so perhaps we don't have to answer this question now?

For how long should an invitation token be valid? I chose 7 days for now.

I have no preference here, expiration period to 48-72 hours should be sufficient imo.

[dstrukt]

Should admins also get an email (in addition to the notification) when a new user registered?

Yes! Was going to suggest this in the other PR

How to handle user approval when invite is made on the store-level? The admin might not know anything about a new user when a store owner invited an employee.

Could arguably be a notification for the admin...? Not sure an email is necessary here, assuming the role is just Employee, maybe anything higher triggers an email .. not sure. Agree with @pavlenex can address specifics once we see the Store level invites, etc..

For how long should an invitation token be valid? I chose 7 days for now.

I like 7 days, 48-72 hours could be a little restrictive, assuming you invite an employee on Friday, but maybe they don't claim until the following Monday.

[pavlenex]

As long as 7 days is not a security risk, sounds good to me, no hard preference here from the user-perpective.

[dennisreimann]

I like 7 days, 48-72 hours could be a little restrictive, assuming you invite an employee on Friday, but maybe they don't claim until the following Monday.

I thought so too and think it's a valid scenario. I don't see a downside security-wise, where 3 vs. 7 days would make a big difference, because the signup is tight to having access to the token anyways.