Skip to main content

Pairing authentication

Overview​

A Firefox Account user can connect a new device to their account without entering a password, by instead "pairing" with an already-connected device in order to obtain account credentials.

Currently, the pairing implementation is limited to a mobile device (Firefox Android and iOS) scanning a QR code displayed on a computer (Firefox Desktop) already connected to a Firefox Account. We hope to expand these capabilities in future.

User Flow​

Let's assume that the user is already signed-in to their Desktop Firefox profile.

On their mobile device, Firefox invites them to navigate to firefox.com/pair on their Desktop browser, and offers to scan the QR code which will be generated by that device. Like this:

The Firefox Mobile pairing screen

When they visit that URL on their Desktop device, it will confirm their intent to connect another device, and then generate and display a QR code. Like this:

The Firefox Desktop pairing screen

When the user scans the QR code, each device will show a confirmation screen, and after user approval the new device will be connected to their account.

A detailed technical user-flow is available here.

Implementation​

High-level description of the flow​

  1. The two devices exchange a one-time secret key via QR code, and use it to create a shared, encrypted and authenticated communication channel over websockets.
    • The Channel Server is responsible for proxying communication between the two devices.
    • The Pairing Channel library provides the crypto necessary to authenticate and encrypt the channel, using TLS1.3 in pre-shared-key mode.
    • The Desktop device is responsible for creating the channel and its corresponding secret key, and advertising those details in a QR code.
    • The Mobile device connects to the channel using the details it scans from the QR code.
  2. The Mobile device prepares an OAuth request for connecting to FxA, but instead of redirecting to a webpage on https://accounts.firefox.com, it sends the OAuth request to the Desktop device over the pairing channel.
  3. The Desktop device receives the OAuth request, confirms user consent, and uses its existing credentials to tell the FxA server to grant a corresponding OAuth authorization code. Instead of delivering the code via the usual OAuth HTTP redirect, it sends the code back to the Mobile device over the pairing channel.
  4. The Mobile device receives the code and processes it just as it would for an ordinary web-based OAuth flow, by talking to the FxA server to exchange the code for some OAuth tokens.

There is some additional message-passing the takes place over the pairing channel in order to show confirmation screens and help smooth out the experience, but the high-level abstraction is "do an OAuth flow, but using the pairing channel instead of HTTP redirects".

Detailed implementation description​

The implementation is described here.

Please note that the FxA Pairing Flow - Application Layer Lucidchart diagram should be treated as the source of truth regarding the pairing protocol and kept up-to-date. There is also a rendered png of the diagram available on the detailed architecture docs.

Where does the code live?​

Security concerns and desired security properties​

Described here.

Possible evolutions​

  • Reverse pairing: allow a computer to connect to an account by scanning a QR code with an already connected mobile Firefox.
  • Pairing using a code to type: more accessible, allows device without a back camera to pair (i.e. 2 computers).