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 or an MSISDN assertion (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, MSISDN verifier, which will provide the user's phone number. Once the server verifies the given identity/identities, an UUID and a shared 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

API extensions for supporting MSISDN verification in FxA auth server

User Data Schema

Current Data Model

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

Proposed Data Model

(Rename urlStore to userStore)

  userStoreSchema {
    _id: <string>,
    sharedKey: <string>,
    alias: [{
      type: <string>, // "fxa" or "msisdn"
      _id: <string>, // MAC from email or msisdn (bug 984288)
      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.
• sharedKey: 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.
• 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

User logs in with new MSISDN

Linking accounts

Based on the requirement that users should be able to log into Loop with any alias (MSISDN and/or Firefox Accounts email) from both Desktop and Mobile, the key differentiator of these use cases (apart from the chosen ID) is if the alias being linked is already a registered alias associated to a Loop account or not. That would affect the need of setting the existing alias as "dirty".

User links NOT registered Firefox Accounts email to registered MSISDN

• Alice is using a device (Desktop or Mobile) where she is logged in Loop using her MSISDN.
• Alice is logged in Firefox Accounts in her device with an email that is NOT registered in Loop.
• Alice wants to register and use her Firefox Accounts email to log in Loop. So she can use both MSISDN and Firefox Accounts email to make and receive Loop calls.

User links registered Firefox Accounts email to registered MSISDN

• Alice is using a device (Desktop or Mobile) where she is logged in Loop using her MSISDN.
• Alice is logged in Firefox Accounts in her device with an email that is ALREADY registered in Loop (because she signed up in Loop with her Firefox Accounts email from a different device for example).
• Alice wants to use her Firefox Accounts to log in Loop. So she can use both MSISDN and Firefox Accounts email to make and receive Loop calls.

This request is done from a device where Alice is logged into Loop with the account that has been marked as dirty (the one associated to her Firefox Accounts email) and so the client is asked to renew its credentials.

User links NOT registered MSISDN to registered Firefox Accounts email

• Alice is using a device (Desktop or Mobile) where she is logged in Loop using her Firefox Account.
• Alice MSISDN is NOT registered in Loop.
• Alice wants to register and use her MSISDN to log in Loop. So she can use both MSISDN and Firefox Accounts email to make and receive Loop calls.

User links registered MSISDN to registered Firefox Accounts email

• Alice is using a device (Desktop or Mobile) where she is logged in Loop using her Firefox Account
• Alice MSISDN is ALREADY registered in Loop.
• Alice wants to use her MSISDN to log in Loop. So she can use both MSISDN and Firefox Accounts email to make and receive Loop calls.

This request is done from a device where Alice is logged into Loop with the account that has been marked as dirty (the one associated to her MSISDN) and so the client is asked to renew its credentials.

Silent MSISDN verification on Firefox OS

There is a parallel work to allow privileged apps to get a verified MSISDN from the platform in Firefox OS. We will link the details here as soon as they are ready.

[1]