Requirements

• Loop should allow users to sign-up/sign-in into the service using either an MSISDN or a Firefox Account email in Desktop and Mobile.
• Loop should allow users to have an MSISDN or a Firefox Account email as identifier to receive calls in Desktop and Mobile.
• Loop should allow users to link an MSISDN to a Firefox Account and vice versa at any point from Desktop and Mobile (Not an MVP requirement, but nice to have :)).

Tracking bugs

// TBD

High Level Architecture

HAWK

Following Austin Kings's recommendation we will be using HAWK to secure client requests and server responses. During the sign up process, the client will be providing either a Firefox Account assertion or an MSISDN (or both if available). The server will be responsible for using the verification mechanisms for both of these identities. For Firefox Accounts, Firefox Accounts verifier, which will provide the user's email. For MSISDNs, an SMS based authentication service (details TBD). Once the server verifies the given identity/identities, an UUID and a private key will be generated, stored in the server associated to the given identities/identity and provided to the client. These values will be used to authenticate HAWK requests for following requests. The UUID uniquely identifies a Loop user (we can even use Mongo's _id field for each user document).

MSISDN verification service

Loop will be using an MSISDN verification service with the following architecture:

User Data Schema

Current Data Model

  urlStoreSchema {
    simplepushURL: <string>,
    userMac: <string>
  }

Proposed Data Model

(Rename urlStore to userStore)

  userStoreSchema {
    id: <string>,
    privateKey: <string>,
    alias: [{
      type: <string>,
      _id: <string>,
      verificationKey: <string>,
      verified: <boolean>
    }],
    simplepushEndpoint: [{
      url: <string>,
      online: <boolean>
    }],
    dirty: <boolean>
  }

• id: Uniquely identifies a Loop user. One id can contain multiple alias. HAWK requests will contain this value within the authentication header.
• privateKey: Server generated key that will be used to create the HAWK requests MAC values. There will be one key per loop user and will be shared with clients that proof ownership of the identity used to login in Loop (Firefox Accounts and/or MSISDN).
• alias (subdocument): Personal information about the owner of the Loop account. Can be multiple. Firefox Accounts emails and MSISDNs so far.
• alias._id: Primary key. MAC created from email or msisdn.
• alias.type: "fxa" or "msisdn"
• alias.verificationKey: Loop server delegates the verification of MSISDNs to an external MSISDN verification service. Clients that register themselves using the MSISDN will be given this temporary server generated key that will allow them to make HAWK authenticated requests. Until the MSISDN verification service notifies the server about the actual verification of the MSISDN, HAWK requests authenticated with the verificationKey will be rejected. Once the MSISDN is verified HAWK requests authenticated with the verificationKey will be given the privateKey value (only once) and will be asked to repeat the same request.
• alias.verified: Flag that indicates if the stored identity has been verified or not. The server should only progress requests from/to verified identities.
• simplepushURL: List of SimplePush endpoints to notify users about calls. There will be one SimplePush endpoint per device and we should be able to set them as online/offline.
• dirty: Flag to allow account linkage. If true means that the alias of this account has been associated with other account and so it is no longer valid. In this case, we expect clients containing the credentials of the 'dirty' account to renew them.

Data flows

Most of these data flows are very similar between them, but each case is explained in detail for clarity.

Login

This document assumes that an user can log into Loop using her MSISDN or her Firefox Accounts email in any Firefox platform (Firefox Desktop and Firefox OS so far).

User logs in with new Firefox Accounts email (Sign Up)

User logs in with new MSISDN (Sign Up)

If the login is done from Desktop, the MSISDN verification SMS won't be sent to the Loop client, but to the phone specified by the user.

The following is a HAWK request done with the unverified credentials (verificationKey) after the MSISDN has been verified.

User logs in with registered Firefox Accounts email (Sign In)

User logs in with registered MSISDN (Sign In)