| 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.
...
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.
...
Replacing step 2.
- The email address entered by Alice doesn't exist.
- System sends an email to Alice to notify her of the problem.
- Alice tries again with a different email address.
Mockups
| View file | ||||
|---|---|---|---|---|
|
Use case B - Alice wants to invalidate the invitation she sent previously.
...
Alice wants to invalidate the invitation she sent previously.
...
- Alice has sent an email invitation to Bob.
- Bob hasn't accepted the email invitation yet.
...
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
...
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 7. The web client displays Alice's invitation to Bob.
Step 8. Bob accepts Alice's team invitation.
...
| 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 | ||||
|---|---|---|---|---|
|
| View file | ||||
|---|---|---|---|---|
|
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.
...
Bob wants to sign in to his existing Synapse account and accept Alice's invitation.
...
Primary actor
...
Bob
...
- Alice has sent an email invitation to Bob.
- Bob has one or more Synapse accounts.
...
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.
...
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.
...
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 |
| 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.
| Goal | Bob wants to create a Synapse account and accept Alice's invitation. |
Primary actor | Bob |
| Secondary actor | Alice |
| Preconditions |
|
| 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 | 85. Bob accepts Alice's team invitation. Step | 96. System sends a notification email to Alice saying that | Bob has joined her team.
Mockups
| View file | ||||
|---|---|---|---|---|
|
| 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.
Complete workflow 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 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
Option 1
Models to implement or modify
...
inviteeEmail
teamId
createdBy
id
...
emailMembershipInvitationId
timestamp
hmac
...
results - ARRAY<EmailMembershipInvitation>
nextPageToken
...
email
timestamp
hmac
emailValidationSignedToken
emailMembershipInvitationSignedToken (optional)
...
inviteeId
emailMembershipInvitationId
timestamp
hmac
...
firstName
lastName
emailValidationToken
emailValidationSignedToken
username
password
...
email
lastName
firstName
userName
EmailMembershipInvitationSignedToken (optional)
Services to implement or modify
...
Create an email membership invitation.
Send an email containing an invitation link to the invitee. The link will contain a serialized EmailMembershipInvitationSignedToken.
...
New
...
Start the process of creating a new account, and optionally also the process of associating a membership invitation to the new account.
Send a 'validation email' message to the provided email address. The email will contain a link to complete the registration process.
The link will contain a serialized AccountCreationToken.
Intended to be used in conjunction with POST /account.
...
/account/emailValidation
...
portalEndpoint
...
Verify whether the inviteeEmail of the indicated EmailMembershipInvitation is associated with the authenticated user.
If it is, the response body will contain an InviteeVerificationSignedToken.
If it is not, the response body will be null and an identity verification email containing a link will be sent to the inviteeEmail of the indicated EmailMembershipInvitation. The link will contain a serialized InviteeVerificationSignedToken.
...
Create a MembershipInvitation. The invitation is created from the team associated with the given email membership invitation to the currently authenticated user.
A valid InviteeVerificationSignedToken must have an inviteeId equal to the id of the authenticated user and an emailMembershipInvitationId equal to the id in the URI.
Doesn't send any email notifications.
...
Related services: POST /account, POST /session
...
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 7. The web client displays Alice's invitation to Bob. Step 8. Bob accepts Alice's team invitation. Step 9. System sends a notification email to Alice saying that Bob has joined her team. |
Mockups
| View file | ||||
|---|---|---|---|---|
|
| View file | ||||
|---|---|---|---|---|
|
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.
| 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
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. |
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 7. The web client displays Alice's invitation to Bob. Step 8. Bob accepts Alice's team invitation. Step 9. System sends a notification email to Alice saying that Bob has joined her team. |
Mockups
| View file | ||||
|---|---|---|---|---|
|
| 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.
Complete workflow 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 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
| New models | |||
|---|---|---|---|
| MembershipInvtnSignedToken | EmailValidationSignedToken | InviteeVerificationSignedToken | AccountCreationToken |
membershipInvitationId timestamp hmac | timestamp hmac | inviteeId membershipInvitationId timestamp hmac | emailValidationSignedToken membershipInvtnSignedToken (optional) |
...
| Existing models (modified) | ||
|---|---|---|
| MembershipInvtnSubmission | AccountSetupInfo | NewUser |
createdOn message id createdBy expiresOn inviteeId teamId inviteeEmail | firstName lastName
emailValidationSignedToken username password |
membershipInvtnSignedToken (optional) |
Services to implement or modify
| Existing or new | Description | Intended User | URI | Method | Request Parameters | Request Body | Response Body |
|---|---|---|---|---|---|---|---|
| Existing | Create a membership invitation. The team must be specified. Either an inviteeId or an inviteeEmail must be specified. If an inviteeEmail is specified, send an email containing an invitation link to the invitee. The link will contain a serialized MembershipInvtnSignedToken. | team administrator | /membershipInvitation | POST | acceptInvitationEndpoint (optional) notificationUnsubscribeEndpoint (optional) | MembershipInvtnSubmission | MembershipInvtnSubmission |
| New | Retrieve a membership invitation. | signed token holder | /membershipInvitation/{id} | POST | -- | MembershipInvtnSignedToken | MembershipInvtnSubmission |
Existing | Start the process of creating a new account, and optionally also the process of associating a membership invitation to the new account. Send a 'validation email' message to the provided email address. The email will contain a link to complete the registration process. The link will contain a serialized AccountCreationToken. Intended to be used in conjunction with POST /account. | public | /account/emailValidation | POST | portalEndpoint | NewUser | -- |
| New | Verify whether the inviteeEmail of the indicated MembershipInvitation is associated with the authenticated user. If it is, the response body will contain an InviteeVerificationSignedToken. If it is not, the response body will be null and an identity verification email containing a link will be sent to the inviteeEmail of the indicated MembershipInvitation. The link will contain a serialized InviteeVerificationSignedToken. This call will only succeed if the indicated MembershipInvitation has a null inviteeId and a non null inviteeEmail. | authenticated user | /membershipInvitation/{id}/verification | POST | portalEndpoint | -- | InviteeVerificationSignedToken |
New | Set the inviteeId of a MembershipInvitation. A valid InviteeVerificationSignedToken must have an inviteeId equal to the id of the authenticated user and a membershipInvitationId equal to the id in the URI. This call will only succeed if the indicated MembershipInvitation has a null inviteeId and a non null inviteeEmail. | authenticated signed token holder | /membershipInvitation/{id}/inviteeId | PUT | -- | InviteeVerificationSignedToken | -- |
...