Use cases

Background

Alice is a researcher at a lab and she is in the process of starting a new project. She is trying to recruit people to join her research team to work on her new project. 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.

...

Use cases

Background

Alice is a researcher at a lab and she is in the process of starting a new project. She is trying to recruit people to join her research team to work on her new project. 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

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 B - Alice wants to invalidate the invitation she sent previously.

...

Alice wants to invalidate the invitation she sent previously.

...

1. Alice has sent an email invitation to Bob.
2. Bob hasn't accepted the email invitation yet.

...

Workflow

Mockups

...

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.

Workflow

Mockups

Use case

...

Bob wants to create a new Synapse account but doesn't want to accept Alice's invitation

...

Primary actor

...

Bob

...

1. Alice has sent an email invitation to Bob.
2. Bob doesn't have a Synapse account.

...

Workflow

Mockups

Use case F - Tracking request and acceptance counts

Flow Diagram

Image Removed

Discussion about the rationale behind some design decisions

We always want to allow Bob to choose the account he joins Alice's team with. This led to the following design decisions:

• In earlier versions of the design, if the email entered by Alice was already associated with an existing Synapse account, a membership invitation to that account would be created instead of sending an email invitation. The current design changes this behavior and instead, the system always sends an email invitation to Bob and the membership invitation to the Synapse account isn't created.
• Even if Bob is already signed in to Synapse in his browser, clicking on the invitation link should always ask Bob to sign in again. This avoids the case where Bob accidentally joins the team with the account with which he is currently signed in.

Bob should not be automatically added to the team after registering a new account / signing in to his account, but instead he should need to manually accept the membership invitation. This separates the process of registering for a Synapse account and joining the team, giving Bob the chance to explore Synapse without committing to join Alice's team.

Proposal

Use cases to support

I propose to support all the use cases except use case B. After multiple discussions about the necessity of use case B, I have come to the conclusion that it's an edge case that would incur significant development cost for little benefit. Supporting it would require our system to keep track of the invitation sent by Alice in some form, which is a requirement that none of the other use cases impose on usF - Tracking request and acceptance counts

Flow 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 Bob, but Bob forwards it 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 validation email to Bob's email address when the invitation link is used.
  (This validation email would be in addition to the validation email associated with registering an account, making the process quite cumbersome for the user).

Proposal

Use cases to support

Option 1 - Support all use cases.

Pros

• Allows Bob to choose what email address to use to register or sign in to Synapse and consequently receive the team invitation

Cons

• Bob will need to validate both the link and the email address he wants to register or sign in with, making the user experience more cumbersome.

Option 2 - Support all use cases except C2 and D2.

This option essentially restricts Bob to accepting the invitation with a Synapse account that is associated with the email address to which the invitation was sent.

Pros

• Better user experience, as Bob will only need to validate his email address once.

Cons

• Restricts Bob's choices.

...

Models to implement

Related models: AccountSetupInfo, MembershipInvtnSubmission

Services to implement

Related services: POST /principal/available, POST /account, POST /session, POST /membershipInvitation

Example implementation with Synapse web client

As the use cases above, the inviter is Alice and the invitee is Bob.

1. Alice invites Bob to her team by entering his email address.
2. Web client constructs an EmailInvitation using Bob's email address and Alice's team's id, then uses it to send a POST /emailInvitation request to the backend.
3. Backend constructs a signed MembershipInvtnSignedToken with Bob's email address, Alice's team's id , and Alice's id and a null inviteeId (because we don't know Bob's account's id yet).
4. Backend serializes the MembershipInvtnSignedToken, embeds it into an invitation link to the web client and sends the link to Bob's email address.
5. Bob clicks on the link and does one of the following:
   1. Registers a new Synapse account. ^[1]
      Web client checks that Bob's email address is a valid account alias through POST /principal/availablenew Synapse account.
      
      1. Web client constructs an AccountSetupInfo ^[2^1], then uses it to create Bob's account through POST /account and receives a session token.
   2. Signs in to his existing Synapse account.
      1. Web client retrieves a session token through POST /session.
6. Web client deserializes and validates the MembershipInvtnSignedToken in the link, then sets the inviteeId to the id of the account Bob used (extracted from the session token).
7. Web client re-signs the MembershipInvtnSignedToken, then uses it to send a POST /tokenMembershipInvitation request to the backend.
8. Backend validates the MembershipInvtnSignedToken and uses it to create a MembershipInvitation from Alice's team to Bob's account.
9. Web client receives backend's 201 response, then directs Bob to his profile's Team tab, where he has a pending MembershipInvitation to Alice's team
10. Bob accepts Alice's invitation (using the existing MembershipInvitation services).

...

1. 1. 1. a session token.
   2. Signs in to his existing Synapse account.
      1. Web client retrieves a session token through POST /session.
2. Web client deserializes and validates the MembershipInvtnSignedToken in the link and extracts the inviteeId out of Bob's session token, then sends a POST /tokenMembershipInvitation request to the backend.
3. Backend validates the MembershipInvtnSignedToken and inviteeId and creates a MembershipInvitation from Alice's team to Bob's account.
4. Web client receives backend's 201 response, then directs Bob to his profile's Team tab, where he has a pending MembershipInvitation to Alice's team
5. Bob accepts Alice's invitation (using the existing MembershipInvitation services).

Alternative implementations