1041074 - [Tracker] Fx Accounts/Basket Integration

Status: NEW

(Websites :: Basket, defect)

Description

[Brian Warner [:warner :bwarner]]

As discussed in https://github.com/mozilla/fxa-content-server/issues/993 ,
we'd like to make some changes to the Basket server API to make it easier to
setup "welcome to firefox accounts" email subscriptions during the
new-account creation process.

Each time a new FxA account finishes with the email-verification step, some
magic will cause an FxA backend server (which holds a secret API key) to use
the /news/subscribe API enhancements (described below) to establish a Basket
account for the new user, including an FxA uid (user id).

Later, when we finish building an FxA Account Dashboard page (where the user
can control various aspects of their account), we'll add a panel which lets
them manage their email subscriptions. They must sign into their FxA account
first, so the dashboard page will have a session token and a way to make
assertions. This page will use the new /news/fxa-login API (described below)
to talk to the Basket server and manipulate these subscriptions.

So we have three changes to make:

 1: new fxa_uid database column
 2: change /news/subscribe to add fxa_uid argument, let newsletters= be empty
 3: add /news/fxa-login API

1:

First, we need to add a new "FxA uid" column to the database. This will be
NULL for accounts created directly with an email address, but will use an FxA
uid (e.g. [e-mail]) when the
FxA New Account process or Dashboard is used to create the Basket account.

2:

Then, we need to enhance the existing /news/subscribe API to add an optional
"fxa_uid" argument. This argument must only be accepted if the request
includes an API key that is marked as enabling the "new account with fxa_uid"
feature: requests with no API key, or with API keys that aren't marked this
way, must be rejected if they include an "fxa_uid" argument. When "fxa_uid"
is accepted, the Basket server merely stores fxa_uid in the database along
with the rest of the information.

In addition, we need to make sure that /news/subscribe can accept an empty
newsletters= argument. We aren't necessarily subscribing these new users: we
just need to store the relationship between email address and fxa_uid to
enable FxA-based control later. If/when we decide to automatically subscribe
new FxA users to a newsletter, this call will stop using an empty
newsletters= argument.

The description of the new /news/subscribe method thus looks like:

 /news/subscribe
 method: POST
 fields: email, fxa_uid, format, country, lang, newsletters, optin, source_url, trigger_welcome, sync
 returns: { status: ok } on success
          { status: error, desc:, code: } on error

3:

We also need to create a new API, for use by the dashboard page. The
description is as follows:

 /news/fxa-login
 method: POST
 fields: assertion
 returns: { status: ok, token: token } on success
          { status: error, desc:, code: } on error

 The handler for this API must:

 1: send the assertion to the FxA verifier, passing a required audience of
    https://basket.mozilla.org/ , and receive a "success" response
    (response.status === "okay")
 2: extract the user's FxA uid from the response
 3: locate an existing DB entry with the matching FxA uid
 4: if there is no matching FxA uid, return an error
 5: if there is a match, return the access token for the matching user

Comment 1

[Chris Karlof [:ckarlof]]

> Then, we need to enhance the existing /news/subscribe API to add an optional
"fxa_uid" argument.

One detail to specify what happens when this is called with:

1) an existing email address in the Basket DB, but no associated fxa_uid
2) an existing email address in the Basket DB with a different associated fxa_uid
3) an existing fxa_uid in the Basket DB with a different email address, possibly associated with someone else (fxa_uid or not)

1) is probably straightforward (associate the fxa_uid with the pre-existing email addr), but 2) and 3) are wackier. 2) and 3) are probably errors, but we need to decide how to specify and recover from them.

Comment 2

[Ben (:bensternthal)]

I am splitting this into smaller tasks.

This bug will be used to track completion of the larger story, blocker bugs will be created for the sub-tasks.

Comment 3

[Paul [:pmac] McLanahan]

> In addition, we need to make sure that /news/subscribe can accept an empty
newsletters= argument. We aren't necessarily subscribing these new users: we
just need to store the relationship between email address and fxa_uid to
enable FxA-based control later. If/when we decide to automatically subscribe
new FxA users to a newsletter, this call will stop using an empty
newsletters= argument.

If this is the case, then I think we should create a new endpoint for FxA just for registration (adding the FxA ID to the DB). Using the "subscribe" method when not subscribing to anything seems odd.

Comment 4

[Chris Karlof [:ckarlof]]

> If this is the case, then I think we should create a new endpoint for FxA just for registration (adding the FxA ID to the DB). Using the "subscribe" method when not subscribing to anything seems odd.

Ok!