Inviting Guests - Orodan/Hilary GitHub Wiki

Inviting guests is a feature that was built into the ability to share resources in the system. Anywhere you can add a user to some content, group, discussion, etc... you can now also invite an email address in the same way.

Note that the only reason Inviting Guests has its own page and not Share/Manage Access in general is because there is special handling about how an email invitation is accepted and an actual user account in the system becomes a member of the resource that was shared.

Inviting an Email Address

With the introduction of this feature, it is now possible to add an email address as an item with which to share a resource.

When the user enters an email address and saves the change, Hilary discerns between email addresses and user ids that are being shared with. In the case of user ids, the AuthzMembers table is updated and it is a standard share operation. In the case of an email address, an AuthzInvitation is created and associated to the email address.

Over a period of time, a single email address could come to acquire multiple invitations before the owner of the address finally accepts. It is important to know that once the owner of the email address accepts the invitation for their email, they will be granted access to all resources that were shared with the email address. It is not possible to only accept invitations to individual resources.

Authenticating an Email Address

When an email address has been invited into the system, a unique and private "invitation token" is generated for the email address and persisted into the authz data model. There is only one invitation token per email address.

There are 2 credentials required to authenticate the acceptance of an invitation:

  1. A valid user session for any user account in the system
  2. An "invitation token" that is associated to any invited email in the system

It is important to note that we don't, for example, validate that the email address of the user matches the email address that was invited. We only need a valid user session, and a valid invitation token.

Therefore, when an existing user account accepts an invitation into the system (Yes, there is a chicken-and-egg situation here, see "Accepting an Email Invitation" to see how the acceptance flow works) with a valid invitation token, we grant the user account access to all resources linked to the invitation token.

Notifying an Email Address

In order to communicate an invitation to an email address, an email is sent to the invited user using the activity email subsystem. The invitation email will aggregate all resources that the user has recently been invited to, and it will contain an "Accept Invitation" link back to the system that has the invitation token information with it. The link will look something like this:

https://oae.gatech.edu/signup?url=/me?invitationToken=17smRZCj9Yox&[email protected]

See the "Accepting an Email Invitation" section to see what the user can do from there.

Accepting an Email Invitation

As mentioned before, when a user follows the "Accept Invitation" screen, they are taken to the signup screen of the system as appropriate to the invited email domain. There are then several options in how the process will continue:

  1. If the user who was redirected already has an active user session with the tenant (i.e., they are already a member and have a saved session in their browser), then they will be redirected to their activity feed, and the accept action (/api/invitation/accept) will be immediately performed
  2. If the user has a user account, but no session, there is an "Already have an account?" message at the top of the page along with a sign-in link, where the user can sign in with their existing account. Once signed in, the user is redirected to their activity feed, and the /api/invitation/accept action is performed
  3. If the user does not have an account yet, then they can follow the instructions on the signup page to create their account. Once the account is created, they are sent to their activity feed where the /api/invitation/accept action is performed

Therefore, the process of accepting an invitation happens VIA an adventure of redirects in the system depending on the user's session state.

As part of the /api/invitation/accept action, the back-end will grant the desired role to the user account for all items that were associated to the invitation token. After all resources are granted, the invitation data is deleted and the token cannot be re-accepted.