notifications-api/docs/adrs/0003-implementing-invite-expirations.md

TITLE: Implementing User Invite Expirations

CREATED DATE	LAST UPDATED	STATUS	AUTHOR	STAKEHOLDERS
06/06/2023	06/15/2023	Proposed	@ccostino	@GSA/notify-contributors

CONTEXT AND PROBLEM STATEMENT

OPEN ISSUE(S): https://github.com/GSA/notifications-admin/issues/96

We've run into a situation where we want to re-invite users when their previous invites have expired. However, we're not currently able to do that because there is no mechanism in the app (specifically the API and the data model) to support expired invites.

Right now, users who are invited to the system receive an email invitation that includes a note that the invitation will expire after 24 hours.

However, on the backend side of things, no such expiration exists. Instead, there is a scheduled job that runs every 66 minutes to check for all InvitedUser objects that are older than 2 days and deletes them.

(Issue #96 in notifications-admin has more specific details.)

DECISION DRIVERS

We'd like to adjust the API and data model so that invited users are no longer deleted from the system and are instead tracked as active or expired. When an invite is expired, we'd like to be able to re-invite the person.

SECURITY COMPLIANCE CONSIDERATIONS

The system currently has a data model for capturing an invited user (InvitedUser), which is based on an authorized user of the system having the permission to invite others to it.

These changes should not deviate from the existing structures and contraints that are already in place, which prevent the following:

• Unauthorized users from accessing the system
• Users without the proper permissions from inviting others

CONSIDERED OPTIONS

These are the different approaches we're considering for implementing this change:

• Adjust InvitedUser management in the API: Instead of deleting InvitedUser objects, we manage them instead and track their created_at dates for when they need to expire. This would involve the following potential changes:

  • Add an expired flag to the InvitedUser model

  • Change the delete_invitations scheduled job to expire_invitations and change its behavior to check for InvitedUser objects that are older than 24 hours and flip the expired flag to True.

  • Add an additional INVITE_EXPIRED status to the API and include it in the INVITED_USER_STATUS_TYPES enum. This will be necessary for future UI changes.

  • Make sure the API responses that provided InvitedUser objects/data included the new expired field and status.

  • Update all tests related to InvitedUsers to account for the new behavior.

  The pros in making this change:

  • This will enable us to support expiring invites in the system, including frontend changes to enable seeing and managing expired invites.

  The cons in making this change:

  • Updated the tests might be a bit challenging depending on how many there are (especially any related to scheduled jobs).

PROPOSED OPTION: Adjust InvitedUser management in the API

I am proposing we adjust the InvitedUser management in the API and get these updates in place first for future UI changes, because without them we cannot display any expired invites nor offer a way of managing them or providing an option to re-invite folks.

After looking through the code and researching how the existing user invite flow works, these changes seem straight-forward and would yield us a lot of value for the effort.

Consequences

• Positive

  • Allows us to support expired invites
  • We could allow for custom expiration periods (either now or in the future)
  • Provides the mechanisms needed in the frontend to display and manage expired invites

• Negative

  • We might end up having to adjust a lot of tests; that's currently unclear.

VALIDATION AND NEXT STEPS

TBD, pending additional ideas and discussion!

Once a decision is made though, a seperate issue should be written up for the API changes that need to take place, and then follow-on work will be needed on the admin side in https://github.com/GSA/notifications-admin/issues/96 to make the UI adjustments.