Send Sign In Links/Codes via SendGrid and Twilio

[Davinkjohnson]

Currently sign-in (and sign-up) magic links and verification SMS messages are sent directly from Firebase, using an NCI email for links. This system works but there are occasional issues where mostly links, but also sms codes, are not being delivered to participants/recruits. In these instances, we do not have visibility to determine whether the messages were actually delivered and there's some filtering or other issue on the participant side, or if there's an issue with Firebase attempting to send the message.

The sign up and sign in process relies heavily on the "black box" created by Firestore which manages all the calls necessary, but doesn't allow for editing of the GUI or customization of the process. We have implemented some of our own UI and built out sign in editing capabilities in the "My Profile" section of the PWA, which could be used as an example.

In the future, we'd like to have magic links and SMS verification codes sent to participants using SendGrid and Twilio, respectively. It will be important to continue having the magic link sent in a way that ensures unsubscribes from other study communications don't impact sign-in communications. This change should allow team members to determine whether messages were successfully delivered, and better troubleshoot sign-in issues.

We will want to keep the sign up and sign in flows as consistent as possible. The process and look and feel have been reviewed for and approved, and much of the process requires IRB review and approval to change.

[JoeArmani]

I’ve been researching this to find out what options we have and what each implementation would entail. Here’s an initial assessment:

Phone Auth (client-side in PWA):
We can achieve much better visibility from our current setup by using FirebaseUI-compatible error-handling callbacks that aren’t yet implemented. We can route these errors for DataDog visibility. These would include:

• captcha_check_failed
• invalid_phone_number
• quota_exceeded
• too_many_requests
• network_request_failed
• user_disabled

Each of the above could show a helpful message to the participant, hopefully reducing support cases. This is a medium lift.

Email Auth (client-side in PWA and transition to SendGrid):
We can start by adding error handling to the PWA's magic link process. That code block doesn't currently listen for errors from the server-side process. This would handle issues during magic link generation up to the point where the magic link email is sent.

Then, we can make the Microsoft Graph -> SendGrid transition for magic links, assuming we can get someone with admin access to this email account to update records and validate SendGrid for this email address. That should give us full visibility for sent emails through the SendGrid dashboard. It looks like we would be able to see some variation of the following statuses on a per-attempt basis:

• processed
• delivered
• deferred
• bounced
• opened

Note: I don’t have access to the SendGrid dashboard and am not yet familiar with it. This is a medium lift due to coordination with the NIH email account admin and the need to better understand how to report errors in DataDog so we can easily locate cases in SendGrid.

Phone Auth (transition to Twilio):
This is a large system update with significant security implications. It would require us to rewrite the SMS handling logic that’s currently “black boxed” within Firebase UI and Firebase Auth. The biggest risk is taking on several security issues that are currently abstracted away by the Firebase UI package and built in Firebase Auth features (cryptographically secure SMS codes, time-based code deactivation, attempt and success tracking, CAPTCHA handling, abuse prevention, automatic rate limiting, etc.). This is a major lift that would require more research on phone auth abuse + security testing.

I’ve developed a good, high-level framework for how this system would look during this research, and can go into much more detail on tracking some of these potential issues/abuses if you’d like. I would need to do more research to fully understand phone authentication abuse tactics.

While we can gain much more visibility with the “Phone (client-side in PWA)” updates mentioned above, this custom SMS/phone auth system is the only way to achieve carrier-level visibility if we require that granularity for phone auth.

---

Overall, it seems implementing the “Phone (client-side in PWA)” and “Email (client-side in PWA and transition to SendGrid)” changes will go a long way toward enhancing visibility. Perhaps we can see how much the additional visibility helps us solve authentication issues and look deeper into the custom SMS/Twilio/phone auth implementation only if necessary?