| Table of Contents |
|---|
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.
...
| Table of Contents |
|---|
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.
| Goal | Alice wants to invite Bob to join her Synapse team. |
| Primary actor | Alice |
| Secondary actor | Bob |
| Precondition | Alice has created a team and she is at her team's page. |
| Postcondition | Bob receives an email invitation to join Alice's team. |
Workflow
Main success scenario | Step 1. Alice invites Bob to join her team by entering his email address and an optional invitation message. Step 2. System sends Bob an email containing an invitation link to join Alice's team. |
| Error scenarios | Replacing step 2.
|
Mockups
| View file | ||||
|---|---|---|---|---|
|
Use case B - Alice wants to invalidate the invitation she sent previously.
| Goal | Alice wants to invalidate the invitation she sent previously. |
| Primary actor | Alice |
| Secondary actor | Bob |
| PreconditionPreconditions |
|
| PostconditionBob | receives an email invitation to join Alice's teamThe invitation link Bob received is no longer valid. |
Workflow
Main success scenario | Step 1. Alice invites Bob to join retrieves the pending invitations to her team by entering his email address and an optional invitation messageand removes the one associated with Bob. Step 2. System sends Bob an email containing an invalidates the invitation link to join Alice's team. |
| Error scenarios | Replacing step 2.
|
Mockups
| View file | ||||
|---|---|---|---|---|
|
Use case B - Alice wants to invalidate the invitation she sent previously.
| Goal | Alice wants to invalidate the invitation she sent previously. |
| Primary actor | Alice |
| Secondary actor | Bobsent to Bob. |
Mockups
| View file | ||||
|---|---|---|---|---|
|
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.
| Goal | Bob wants to create a Synapse account and accept Alice's invitation. |
Primary actor | Bob |
| Secondary actor | Alice |
| Preconditions |
|
| Postcondition | The invitation link Bob received is no longer valid. |
Workflow
...
Main success scenario
...
Step 1. Alice retrieves the pending invitations to her team and removes the one associated with Bob.
Step 2. System invalidates the invitation link sent to Bob.
Mockups
| View file | ||||
|---|---|---|---|---|
|
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.
...
Bob wants to create a Synapse account and accept Alice's invitation.
...
Primary actor
...
Bob
...
- Alice has sent an email invitation to Bob.
- Bob doesn't have a Synapse account.
...
Workflow
Main success scenario | Step 1. Bob clicks on the invitation link in the email he received
|
| Postcondition | Bob is part of Alice's team. |
Workflow
Sub use case C1 Success scenario | Step 1. Bob clicks on the invitation link in the email he received and is directed to the Synapse web client. Step 2. The web client presents Bob with the option to create a Synapse account or sign in with an existing account. Step 3. Bob creates his new Synapse account. Step 4. The web client displays Alice's invitation to Bob. Step 5. Bob accepts Alice's team invitation. Step 6. System sends a notification email to Alice saying that Bob has joined her team. | |||
Sub use case C2 Success scenario | Step 1. Bob clicks on the invitation link in the email he received and is directed to the Synapse web client. Step 2. The web client presents Bob with the option to create a Synapse account or sign in with an existing account. Step 3. Bob creates his new Synapse account. Step 4. System sends a verification email to the address to which Alice sent the invitation. Step 5. The web client prompts Bob to verify that he owns the above email address by clicking the link in the verification email. Step 6. Bob clicks on the verification link and is directed to the Synapse web client. Step | 2. The web client presents Bob with the option to create a Synapse account or sign in with an existing account.7. The web client displays Alice's invitation to Bob. Step | 58. Bob accepts Alice's team invitation. Step | 69. System sends a notification email to Alice saying that Bob has joined her team. |
Mockups
| View file | ||||
|---|---|---|---|---|
|
...
| Goal | Bob wants to sign in to his existing Synapse account and accept Alice's invitation. |
Primary actor | Bob |
| Secondary actor | Alice |
| Preconditions |
|
| Postcondition | Bob is part of Alice's team. |
Workflow
| Main success |
Workflow
Sub use case D1 Success scenario | Step 1. Bob clicks on the invitation link in the email he received and is directed to the Synapse web client. Step 2. The web client presents Bob with the option to create a Synapse account or sign in with an existing account. Step 3. Bob signs in with his existing Synapse account. Step 4. The web client displays Alice's invitation to Bob. Step 5. Bob accepts Alice's team invitation. Step 6. System sends a notification email to Alice saying that Bob has joined her team. |
Mockups
| View file | ||||
|---|---|---|---|---|
|
Use case E - Bob wants to create a new Synapse account but doesn't want to accept Alice's invitation yet.
...
Bob wants to create a new Synapse account but doesn't want to accept Alice's invitation
...
Primary actor
...
Bob
...
- Alice has sent an email invitation to Bob.
- Bob doesn't have a Synapse account.
...
Workflow
Main success scenario | Step 1. Bob clicks on the invitation link in the email he received Sub use case D2 Success scenario | Step 1. Bob clicks on the invitation link in the email he received and is directed to the Synapse web client. Step 2. The web client presents Bob with the option to create a Synapse account or sign in with an existing account. Step 3. Bob signs in with his existing Synapse account. Step 4. System sends a verification email to the address to which Alice sent the invitation. Step 5. The web client prompts Bob to verify that he owns the above email address by clicking the link in the verification email. Step 6. Bob clicks on the verification link and is directed to the Synapse web client. Step | 27. The web client | presents Bob with the option to create a Synapse account or sign in with an existing accountdisplays Alice's invitation to Bob. Step | 38. Bob | creates his new Synapse account.Step 4. The web client displays accepts Alice's team invitation. Step 9. System sends a notification email to Alice saying that Bob has joined her team. |
Mockups
| View file | ||||
|---|---|---|---|---|
|
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.
Flow Diagram
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.
The following content, colored in gray, is outdated.
Models to implement
...
emailAddress
teamId
...
emailAddress
inviterId
teamId
hmac
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.
- Alice invites Bob to her team by entering his email address.
- 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.
- Backend constructs a signed MembershipInvtnSignedToken with Bob's email address, Alice's team's id and Alice's id.
- Backend serializes the MembershipInvtnSignedToken, embeds it into an invitation link to the web client and sends the link to Bob's email address.
- Bob clicks on the link and does one of the following:
- Registers a new Synapse account.
- Web client constructs an AccountSetupInfo [1], then uses it to create Bob's account through POST /account and receives a session token.
- Signs in to his existing Synapse account.
- Web client retrieves a session token through POST /session.
- Registers a new Synapse account.
- 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.
- Backend validates the MembershipInvtnSignedToken and inviteeId and creates a MembershipInvitation from Alice's team to Bob's account.
- 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
- Bob accepts Alice's invitation (using the existing MembershipInvitation services).
...
Alternative implementations
...
POST /emailInvitation and POST /tokenMembershipInvitation
(Proposal described above)
...
+ Supports most use cases (all but B)
+ Simple -> less development time
...
Same as option 1, but store EmailInvitation in the database and implement REST methods for it.
I.e. GET /emailInvitation, GET /emailInvitation/{id}, DELETE /emailInvitation/{id}, etc.
...
+ Supports use case B
+ RESTful
...
...
+ Supports use case B
+ More easily extensible (future support for operations other than inviting to a team)
+ RESTful
- Even more complex -> more development time
...
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
New models to implement and existing models to modify
| New models | Existing models (modified) | ||||
|---|---|---|---|---|---|
| EmailMembershipInvitation | EmailMembershipInvitationId | EmailValidationSignedToken | InviteeVerificationSignedToken | AccountSetupInfo | NewUser |
teamId id | emailMembershipInvitationId | timestamp hmac | inviteeId emailMembershipInvitationId timestamp hmac | firstName lastName
EmailValidationSignedToken username password |
|
New services to implement
| Description | Intended User | URI | Method | Request Parameters | Request Body | Response Body |
|---|---|---|---|---|---|---|
| Create and send email membership invitation containing an invitation link. The link will contain a serialized EmailMembershipInvitationId. | team administrator | /emailMembershipInvitation | POST | portalEndpoint | EmailMembershipInvitation | EmailMembershipInvitation |
| Retrieve pending email membership invitation by ID. | team administrator | /emailMembershipInvitation/{id} | GET | -- | -- | EmailMembershipInvitation |
| Retrieve pending email membership invitations from a Team. | team administrator | /team/{id}/emailMembershipInvitations | GET | limit, offset | -- | PaginatedResults<EmailMembershipInvitation> |
| Delete and invalidate pending email membership invitation. | team administrator | /emailMembershipInvitation/{id} | DELETE | -- | -- | -- |
Starts the process of creating a new account, similarly to POST /account/emailValidation, but also the process of associating a membership invitation to the new account. Sends a 'validation email' message to the provided email address. The email contains a link to complete the registration process. The link will contain a serialized EmailValidationSignedToken (used for new account registration) and a serialized EmailMembershipInvitationId (used to create membership invitation). Intended to be used in conjunction with POST /account. | public | /emailMembershipInvitation/{id}/account/emailValidation | POST | portalEndpoint | NewUser | -- |
Send an identity verification email to the address associated with the provided EmailMembershipInvitation. The link contains a serialized InviteeVerificationSignedToken. | authenticated user | /emailMembershipInvitation/{id}/verification | POST | portalEndpoint | -- | -- |
Create a MembershipInvitation. The invitation is created from the team associated with the given email membership invitation to the currently authenticated user. At least one of the following conditions must be met in order for this service to succeed:
Doesn't send any email notifications. | authenticated user | /emailMembershipInvitation/{id}/membershipInvitation | POST | InviteeVerificationSignedToken (optional) | -- | MembershipInvtnSubmission |
Related services: POST /account, POST /session
Additional notes
Tracking request and acceptance counts