Feat: Sign up verification codes instead of verification links

[shane-tomlinson]

The current signup verification flow requires a user to exit the FxA flow and open a verification link from their email.

This causes several problems:

• Users often open verification links in a different tab/browser, causing an explosion of paths we have to worry about. @ryanfeeley and I had a spreadsheet tracking the combinatoric explosion. It's awful.
• Users sometimes never get back to the app they were trying to sign up for because the links opens in a browser.
• Mobile devices may kill apps that go into the background.

For Lockbox, we ask users that are signing in to copy a short "confirmation code" from their email into a screen on FxA to ensure that users make it back to FxA to sign in. Perhaps @irrationalagent has some details on signin performance of codes vs links that can help guide prioritization.

@rfk wrote some comments in an email that I'm copying here:

For the current email-codes experiment on login, we maintain a separate "email code" column in the db with the shorter code. This is nice and simple but it has a couple of drawbacks. Chiefly, we haven't implemented the ability to regenerate this code once it expires, so any attempts to re-send the verification email will fall back to sending a link rather than a code.

Taking the same approach for verifying sign-up would mean adding new "emailShortCode" and "emailShortCodeExpiry" columns to the 'accounts' and/or 'emails' table, and probably figuring out a way to safely regenerate these when they expire.

However, we already know another technique for turning a high-entropy long-lived secret into a short time-limited code: TOTP.

If we treated the current email link code as a TOTP master secret, we could easily generate and verify short email confirmation codes in a way that doesn't require new db columns and doesn't require any extra logic to handle regeneration after expiry.

@rfk has also expressed an interest in getting this for Fenix.

cc @davismtl, @ryanfeeley

[shane-tomlinson]

cc @bbangert and @johngruen for the work you are doing too. I think this could simplify those flows for users who do not already have an account.

[irrationalagent]

Here's the conversion % after the email is sent, Lockbox codes vs. Links. They appear to be pretty comparable, though I would caution that Lockbox users are probably more competent than the average FxA user (not that I'm biased). @shane-tomlinson

[ryanfeeley]

It's worth noting that Google now uses codes to verify new accounts. It's become frowned upon to encourage users to click on links delivered by email. Codes are safer from this POV.

…

On Wed, Mar 20, 2019 at 10:54 AM Leif Oines ***@***.***> wrote: Here's the conversion % after the email is sent, Lockbox codes vs. Links <https://analytics.amplitude.com/mozilla-corp/chart/dib5asr>. They appear to be pretty comparable, though I would caution that Lockbox users are probably more competent than the average FxA user (not that I'm biased). @shane-tomlinson <https://github.com/shane-tomlinson> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <https://github.com/mozilla/fxa-auth-server/issues/2981#issuecomment-474867358>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEKdf2zRF-xxzLdku9_RIxslCiH2AQGks5vYkumgaJpZM4b_EJU> .

-- Ryan Feeley // Toronto Staff Designer // FxA & Sync IRC & Slack: rfeeley

[rfk]

@rfk has also expressed an interest in getting this for Fenix.

I'll also add that this becomes more important as we bring on more non-brower services, because we expect more users to be signing up through a web-based OAuth flow, and need to do everything we can to keep them from diverging off out of that funnel.

It's become frowned upon to encourage users to click on links delivered by email.

We'll also need to consider the password-reset flow in this case.

If there's general interest in moving away from links and towards codes for all our emails, I would be very happy to collaborate with someone on a concrete proposal for how to do this on top of TOTP, help with secreview etc.

[davismtl]

Coming from a meeting, SUMO brought up codes and how they would really like that we have this for launch.

[rfk]

The signin code flow also received positive reviews from Lockbox and Reference Browser teams recently, FWIW.

they would really like that we have this for launch

Which is when? :-)

[davismtl]

Which is when? :-)

May

[rfk]

It's worth noting that Google now uses codes to verify new accounts.
It's become frowned upon to encourage users to click on links delivered by email.
Codes are safer from this POV.

Ref https://bugzilla.mozilla.org/show_bug.cgi?id=1543160 for an example of where codes would be superior to links from a safety perspective.

[davismtl]

@shane-tomlinson I tentatively put this for train-137 since it lines up approximately to SUMO's migration to FxA.

I'll try to work on a feature doc with @ryanfeeley but ultimately, let's do what we're doing with Lockbox everywhere.

Do we have a similar bug open for logins?

[rfk]

It's worth noting that Google now uses codes to verify new accounts.
It's become frowned upon to encourage users to click on links delivered by email.
Codes are safer from this POV.

Ref https://bugzilla.mozilla.org/show_bug.cgi?id=1543160 for an example of where codes would be superior to links from a safety perspective.

[rfk]

If we treated the current email link code as a TOTP master secret,
we could easily generate and verify short email confirmation codes in a
way that doesn't require new db columns and doesn't require any extra
logic to handle regeneration after expiry.

So a few more notes on how I see this playing out.

When sending a verification email, rather than making a link containing the high-entropy secret key, use it as input to the TOTP algorithm to derive a short-lived secret code. That's the easy bit.

When verifying the short-lived code, you need to know how to look up the corresponding high-entropy secret key. This probably means making /recovery_email/verify_code be optionally authenticated with a sessionToken. You'd use the sessionToken to look up the tokenVerificationId associated with that session, to use as input to the TOTP algorithm as above.

AFAICT the same technique should work with /password/forgot/send_code and /password/forgot/verify_code, the latter of which is already authenticated with the passwordForgotToken.

I've been thinking about this on-and-off and trying to poke holes in the scheme, but it seems like it would all hold together to me. We'd have to get security folks to check it for us as well though :-)

[shane-tomlinson]

@ryanfeeley - here are my engineering driven designs.

Sync flow

OAuth flow

Perhaps the "Enter your code" screen should say which service the user is signing into?

[clouserw]

@davismtl @ryanfeeley -- any progress on that feature doc? It would be good to get this in the next sprint or two for Rina.

[ryanfeeley]

Looking pretty great! Some nits:

• First screenshot primary button, small c on Verify code
• Update illustrations and logo to master brand
• Should we use generic language for code email? So it's less Sync specific?
• What inline and full page errors do we need to design? (code expired, too short, etc)
• Verify code screens likely need another link to use a different email (in the event that they mistype their email)

[davismtl]

@clouserw Diane has started working on one:
https://docs.google.com/document/d/1fqyXTcAfJ8HPaCsEtML_bfIItlYYtG5yk32ZRaOXorY/edit#

[davismtl]

CC @dianehuang11

[dianehuang11]

@irrationalagent / @shane-tomlinson
Re: Lockbox Links vs Codes
Did we document this experiment and was there a feature doc created? Seems like it has been running since Feb this year.

The data shows that links have actually been out-performing codes for login completion. Interestingly, retention of "link" users > "codes" users as well. Retention Analysis

Should explore causes behind this to improve code verification experience for the new FxA flow (i.e. UX changes?)

[vbudhram]

Quick breakdown of engineering items from https://docs.google.com/document/d/1i003YoL4cchn8fOpA9yb0ntnD-rHhq4zO-WMyX6Y_IE/edit#heading=h.j4ues9d2p7up

• Refactor account verify into helper function
• Update auth server routes, /account/create, /session/verify_code, /session/resend_code
• Add unit and functional tests for routes
• Update email templates for sign-up codes
• Add content server pages
• Update js-client
• Update content-server unit and functional tests
• Add feature flagging

[dianehuang11]

New related issues after user testing this feat:

• Reconsider including verification codes in email subject #2235
• Modify copy to clarify verification being a required step #2237
• Reduce code expiration from 20 to 5 minutes #2238

Keeping all our resources in one place:
PRD
User Testing Doc
Shared Drive

[vbudhram]

Closing this here because all of the development parts for sign-up codes have landed. Bugs from QA will be filed as new issues.