Support pre-verified emails in /account/create

[ckarlof]

Marketplace is in the process of migrating from Persona to FxA for authentication. One migration case they want to make easier is when the user is already authenticated with a verified Persona account. In this case, they want to bypass the email verification step when user creates a FxA, because the user presumably already verified her email via Persona.

I propose we augment /account/create to take an additional optional parameter, preVerifyToken, which is an authenticated JWT with the following format:

JWT claims:

{
  "iss": "marketplace.firefox.com", // issuer (relier domain)
  "exp": 1300819380,  // expiry time
  "aud": "api.accounts.firefox.com", // audience (domain of the FxA API server)
  "sub": "foo@example.com" // user's email to be pre-verified
}

JWS header:

{
  "typ": "JWT",
  "alg": "HS256" // HMAC-SHA256
}

Reliers that need to migrate would add this token to GET /authorization in the FxA Oauth flow, and the FxA login page would append this value to the /account/create request.

[ckarlof]

We could also email users "migration" links that include this token.

[ckarlof]

@dannycoates, I'd like to get this done during the train-20 cycle.

[ckarlof]

I'll work on more detailed specification soon, but I think there's enough here to at least get started.

[dannycoates]

What's the advantage of having the JWS payload be a JWT instead of just the email address?

[ckarlof]

What's the advantage of having the JWS payload be a JWT instead of just the email address?

It's good to have the token self describing, e.g., have an expiration time, who it came from, and who it was intended for. There are of course many ways to do this. JWTs are pretty verbose, but they get the job done. Using a JWT will also allow us to easily extend the payload if need be.

The other reason is "standards": we should use them when they're an option. There are JWT libraries available for most languages.

Do you have concerns?

[dannycoates]

Its not a code issue, I've already got the code to parse either.

Do you have concerns?

No, its just that all the info we need can be included in or inferred from the JWS header. The "token" being the JWS message is still self describing whether the payload is the email string or a JWT object. Using a JWT when a string is sufficient just adds incidental complexity.

Using a JWT will also allow us to easily extend the payload if need be.

Firstly, we shouldn't assume we'll need more. Second, the JWS "cty" can specify the payload type if we ever decide we do need a full JWT for anything.

[ckarlof]

Using a JWT when a string is sufficient just adds incidental complexity.

Using a JWT with iss and aud fields minimizes the likelihood of things getting confused in the future. The aud field makes it clear who it is intended for. For example, if we went with public keys and in the future Marketplace had a reason to send signed email addresses to someone else, then a signed email originally sent to FxA could be re-sent to the other service as well without any way to distinguish who it was originally intended for.

I admit I don't exactly know what future use cases of JWT/JWS might arise, and if this is our first and last use of them, then yes, we wouldn't see much benefit of using a JWT vs. email.