...

Use cases

Background

Alice is a researcher at a lab and she is in the process of starting a new project. She has already contacted Bob and Claire who each work in different labs in other parts of the world and they have agreed is trying to recruit people to join her research team . Alice has used Synapse in the past and wants to use it for to work on her new project, but she doesn't know if Bob and Claire have used Synapse before. Alice does know Bob and Claire's email addresses. . Alice thinks that her friend Bob who is a researcher at a different lab might be interested in joining her team.

Use case A - Alice wants to invite

...

Bob to join her

...

Synapse team.

Workflow

Mockups

...

2. System detects that the email address entered already has a Synapse account associated with it, presumably it's Bob's account.

1. 1. System sends Bob a membership invitation to Alice's team.
   2. Bob accepts the invitation and joins Alice's team.

3. Alice decides not to collaborate with Bob anymore and wants to cancel her invitation.

1. 1. Alice navigates to her team's page and clicks on the remove button associated with the pending invitation to Bob.
   2. System invalidates the invitation link sent to Bob.
      1. The link Bob received is no longer valid and directs to an error page.

4a. Bob already has a Synapse account associated with a different email address and is already signed in in his browser.

1. 1. System adds Bob's account to Alice's team.

4b. Bob already has a Synapse account associated with a different email address but isn't signed in.

1. 1. Bob clicks on "Sign in" and signs in with his existing account.
   2. System adds Bob's account to Alice's team.

5. Bob clicked on the invitation link a long time* after it was issued. (* definition of long time to be specified)

1. 1. System sends a membership request to Alice's team instead of directly adding Bob to Alice's team.

Relevant questions

At step 4 in the main success scenario, should we skip the email validation process that precedes registering an account?
+ Easier to use for the user.
- Forces the user to register Synapse account with the email address the invitation was sent to.

Leaning towards yes, we should skip it.

Related to the above, should the invitation email have one link to a sign in/registration page; or two links, one to a sign in page and one to a registration page?

Tentatively a single link is preferred.

Should we allow batch inviting? Currently only one user can be invited at a time.

Not necessary.

Should we display pending invitations in Alice's team page and allow her to cancel them? This would remove the need for the alternative scenario on step 5.

Yes, it's a good idea as it enables alternative scenario step 3.

What happens if the invitee is already signed in to Synapse when they click the invitation link(s)?

Addressed by alternative scenario step 4a.

Should we allow existing users to be searched by their email address?

No, we shouldn't allow reverse searches because user email addresses aren't public.

Mockups

API

...

Use case B - Alice wants to invalidate the invitation she sent previously.

Workflow

Mockups

Use case C - Bob wants to create a Synapse account and accept Alice's invitation.

Sub use case C1 - Bob wants to create a Synapse account using the same email address to which Alice sent the email invitation.

Sub use case C2 - Bob wants to create a Synapse account using a different email address, not the one to which Alice sent the email invitation.

Workflow

Mockups

Use case D - Bob wants to sign in to his existing Synapse account and accept Alice's invitation.

Sub use case D1 - Bob wants to sign in to his existing Synapse account which is associated with the same email address to which Alice sent the invitation.

Sub use case D2 - Bob wants to sign in to his existing Synapse account which is not associated with the email address to which Alice sent the invitation.

Workflow

Mockups

Use case E - Bob wants to create a new Synapse account but doesn't want to accept Alice's invitation yet.

This use case is covered by use case C.

Complete workflow diagram

Image Added

Security concerns

Guaranteeing the security of our users' data is a top priority. Inviting a person to join your team is effectively giving that person access to all the data contained in all the projects your team has access to. This means that inviting someone through email inherently carries some risk.

Consider the following scenarios that could result in data breaches:

• Alice sends an email invitation to join her team to Bob, granting him access to the data accessible by Alice's team. However, Bob forwards his invitation to Claire. Now Claire has access to all the data Bob was supposed to have access to. Alice may not have intended for this to happen.
• Alice makes a typo when typing Bob's email address, sending it to some other (existent) email address.

In order to protect our users from these types of situations, we could make the following design decisions:

• Inform our users of the risks in the email invitation widget.
• Require the user to type the recipient email address a second time for confirmation.
• Allow the user to invalidate pending invitations.
• Make all invitation links single-use. Also, make them expire after a certain period of time. This prevents a malicious person from using an invitation link they found in an email inbox they hacked.
• Require the consumer of the invitation link to prove that they are the owner of the email address to which Alice sent the email invitation, i.e. prove that they are Bob.
  We can do this by sending a verification email to Bob's email address when the invitation link is used.

Proposal

Models to implement or modify

Services to implement or modify

Related services: POST /account, POST /session

Statistics to track

• Which users create invitations, when they create them, and from what teams they create them.
  • These statistics are captured by the MembershipInvitation (formerly MembershipInvtnSubmission) model, which is stored in the database.
• How many invitations are accepted and when they are accepted.
  • There is no easy way to track when the invitation to the team is accepted, but we can know how many times the invitee will use the email link to create a new account or sign in to their existing account. This is essentially the number of times that PUT /membershipInvitation/{id}/inviteeId is called.
• How many invitees choose to register a new account and how many choose to sign in.
  • We know the total number of membership invitations created from the number of POST /emailMembershipInvitation/{id}/membershipInvitation requests.
  • We know the total number of invitees who chose to register a new account from the number of POST /emailMembershipInvitation/{id}/account/emailValidation requests.
  • We can derive the total number of invitees who chose to sign in with an existing account from the above two numbers.
• We can know how often invitees attempt to sign in using an email address that is not associated with the inviteeEmail of the MembershipInvitation by looking at how often GET /membershipInvitation/{id}/inviteeVerificationSignedToken calls respond with 403 status.

Implementation outline

Phase 1

I expect that in most cases, invitees will choose to sign in or register with the invited email address. I'll refer to this as the "happy" case.

In phase 1 I will implement use cases A, B, C1, D1 and E. These use cases represent the happy case.

Phase 2

There will be some invitees that want to sign in or register with a different email address. I expect that the number of users who choose this path will be low enough that this will be an edge case.

In phase 2 I will implement use cases C2 and D2. These use cases represent the edge case described above.

Progress

Phase 1

Create new models

•  MembershipInvtnSignedToken
•  EmailValidationSignedToken
•  InviteeVerificationSignedToken
•  AccountCreationToken

Update existing models

•  MembershipInvtnSubmission
•  AccountSetupInfo
•  NewUser

Update existing services

•  POST /membershipInvitation
•  POST /account/emailValidation

Create new services

•  POST /membershipInvitation/{id}
•  POST /membershipInvitation/{id}/verification
•  PUT /membershipInvitation/{id}/inviteeId

Update web client

•  Make everything work

Sequence of events

Image Added

Made on https://sequencediagram.org/ with the following markup:

entryspacing 0.9
Frontend->Backend:Invite the new user (POST membershipInvitation)
Backend->OUT OF BAND: Send email that contains MembershipInvtnSignedToken
OUT OF BAND->Frontend: User clicks Join link in email
Frontend->Backend:Get corresponding membershipInvitation (POST membershipInvitation/id)
Backend-->Frontend:Membership Invitation
note over Frontend,Backend:Already has an account
Frontend->Frontend:User clicks "Already have an Account?"
Backend->OUT OF BAND
OUT OF BAND->Frontend
Frontend->Backend: Login
Backend-->Frontend:Successful Login
Frontend->Backend:GET membershipInvitation/id/inviteeVerificationSignedToken
Backend-->Frontend:Return InviteeVerificationSignedToken
Frontend->Backend: Update invitation with user id: PUT /membershipInvitation/{id}/inviteeId
Backend-->Frontend:
Frontend->Frontend: User sent back to the Team page. Single click Join (since there's an open invitation)
note over Frontend,Backend:New account
Frontend->Frontend:User click "Send Registration Info"
Frontend->Backend:POST/account/emailValidation
Backend->OUT OF BAND: Send validation email
OUT OF BAND->Frontend: User clicks create account link
Frontend->Backend:Standard account creation (sign ToU...)
Backend-->Frontend:Standard account creation
Frontend->Frontend: User sent to associated Team page. Single click Join (since there's an open invitation)

Related JIRA issues