Current as of April 17, 2023

Communication with Firefox via WebChannels

Mozilla accounts communicates with Firefox desktop and Fennec using WebChannels. WebChannels provide secure two-way communication between the browser and web content. Messages sent from content to the browser utilize WebChannelMessageToChrome custom events. Messages sent from the browser to content utilize WebChannelMessageToContent custom events.

Firefox Desktop

Context

WebChannels are used to communicate Sync related information when service=sync&context=<context> query parameters are specified. <context> should be one of:

• fx_desktop_v3
• fx_fennec_v1
• oauth_webchannel_v1

Commands

A command is a WebChannelMessageToChrome custom event sent from FxA to the browser using the account_updates WebChannel.

Command format is explained in the section titled Command/Request format.

fxaccounts:fxa_status

Sent on startup to fetch the FxA state from supporting browsers (only Firefox Desktop 55+). Used to get the browser's currently signed in user as well as browser capabilities.

request data

{
  isPairing: <boolean>,
  service: <string>
}

• isPairing: whether or not accounts.firefox.com is executing a pairing flow
• service: the service name or OAuth client-id that is requesting authentication

response data

{
  capabilities: <capabilities>
  signedInUser: <signed in user> || null
}

• capabilities - A list of capabilities supported by the browser. See capabilities.
• signedInUser - the user currently signed into Sync on the browser. See signedInUser.

fxaccounts:loaded

Sent on startup. Sent after the first screen is visible. No data is sent. No response is expected.

fxaccounts:can_link_account

Sent on signin or signup after a user has entered their credentials and submit the form. A response with an ok field is expected.

request data

{
  email: <email>
}

response data

{
  ok: true | false;
}

fxaccounts:login

Sent when a user successfully authenticates with Mozilla accounts and sync can begin. This includes after a user signs up but before they verify their email address, after an account unlock, and after a password reset. No response is expected.

data

See Login Data.

fxaccounts:verified

The user has successfully verified their email address.

data

See Login Data.

fxaccounts:delete_account

Sent after the user successfully deletes their account. No response is expected. Expected by Fennec.

data

{
  email: <email>,
  uid: <user id>
}

• email - User's email address.
• uid - The user identifier.

fxaccounts:delete

Sent after the user successfully deletes their account. No response is expected. Expected by Fx Desktop.

data

{
  email: <email>,
  uid: <user id>
}

• email - User's email address.
• uid - The user identifier.

fxaccount:change_password

Sent after the user successfully changes their password. No response is expected.

data

See Login Data.

fxaccounts:logout

Called whenever the user signs out of their account. No response is expected.

data

{
  uid: <user id>
}

• uid - The user identifier.

profile:change

Sent after the user changes their avatar or display name. No response is expected.

data

{
  uid: <user id>
}

• uid - The user identifier.

Command data values

loginData

{
  declinedSyncEngines: [<array of declined sync engines>],
  email: <email>,
  keyFetchToken: <key fetch token>,
  offeredSyncEngines: [<array of displayed sync engines>],
  sessionToken: <session token>,
  uid: <user id>,
  unwrapBKey: <unwrap b key>,
  verified: (true|false),
  verifiedCanLinkAccount: (true|false)
}

• declinedSyncEngines - An array of Sync engines the user has deselected. See declinedSyncEngines, offeredSyncEngines.
• email - User's email address.
• keyFetchToken - Token used to fetch wrapWrapKB from the server.
• offeredSyncEngines - An array of Sync engines that were displayed to the user. See declinedSyncEngines, offeredSyncEngines.
• sessionToken - The current session token that can be used to interact with FxA's auth server.
• uid - The user identifier.
• unwrapBKey - Used to unwrap wrapWrapKB fetched from the server, resulting key is called kB. Keys derived from kB are used for data encryption for Sync, Send, and Notes.
• verified - Is the user verified?
• verifiedCanLinkAccount - Has the user verified they want to link accounts, if signing into a different account than previously signed in to?

capabilities

An object containing browser supported capabilities. Only available with browser support.

{
  engines: [list of optional supported engines],
  choose_what_to_sync : <boolean>[default: false],
  multiService: <boolean>[default: false],
  pairing: <boolean>
}

• engines - A list of optional supported engines.
• choose_what_to_sync - (OAuth WebChannel Only) - Whether to show the Choose What to Sync screen
• multiService - true if the user is signing into a "Sync Optional" flow where the user can sign into the browser but not enable Sync, e.g., about:welcome or the protection report. false if the user is signing into Sync.
• pairing - Whether the browser can act as a pairing authority.

engines

A list of optional supported engines. If we are unsure whether an optional engine should be displayed, it will only be displayed if the engine is in the list.

Possible values (Firefox Desktop)

• addresses
• creditcards

Possible values (OAuth WebChannel Flow)

See engines capability in Fenix & WebExtensions.

declinedSyncEngines, offeredSyncEngines

• addons
• addresses
• bookmarks
• creditcards
• history
• passwords
• preferences
• tabs

signedInUser

• email - User's email address
• sessionToken - The current session token that can be used to interact with FxA's auth server.
• uid - The user identifier.
• verified - Is the user verified?

Command/Request format

Each custom event is created as follows:

new CustomEvent('WebChannelMessageToChrome', {
  detail: {
    id: 'account_updates',
    message: {
      command: <command>,
      data: <data>,
      messageId: <message id>
    }
  }
});

• command is one of the commands specified below.
• data is an optional JavaScript object.
• messageId is an opaque identifier that should be specified when responding to to a message.

Response format

Responses to FxA use the WebChannelMessageToContent custom event, which is handled by the WebChannel.jsm module's send function. The message parameter should the following format:

{
  command: <command>,
  data: <data>,
  messageId: <message id>
}

• command is one of the commands specified above.
• data is an optional JavaScript object.
• messageId is the message ID sent in the WebChannelMessageToChrome custom event.

Example command order for a signin/signup

1. fxaccounts:fxa_status (if supported)
2. fxaccounts:loaded
3. fxaccounts:can_link_account
4. fxaccounts:login
5. fxaccounts:email_verified (if supported)

OAuth WebChannels

OAuth WebChannels is an extension of the FxA WebChannel Desktop Flow. It consists of similar messages as the Desktop Sync flow, however is more generic because of the use of OAuth in the background. Some behaviours in the OAuth flow are different.

This flow currently supports the following messages:

• fxaccounts:fxa_status
• fxaccounts:oauth_login

The fxaccounts:fxa_status message in the OAuth flow supports specifying a custom list of Sync engines that the app supports. See engines for details of engine capabilities.

GeckoView applications

To enable this feature in applications with GeckoView we ship a WebExtension as part of the firefox-accounts Android component.

Communication channel is established from web content to this class via webextension, as follows:

Commands

fxaccounts:fxa_status

See the fxaccounts:fxa_status section of the WebChannel Protocol document.

engines capability

Unlike the Desktop WebChannel integration, the OAuth WebChannel integration expects all supported engines to be enumerated within the engines capability. Possible values are:

• addons
• addresses
• bookmarks
• creditcards
• history
• passwords
• preferences
• tabs

fxaccounts:oauth_login

Sent when a user successfully authenticates via a WebChannel OAuth flow.

data

{
  "code": "02f3cfea84ac4c143662b38d6c7f0c82c6f91eb041befc7cecda446b1b4887c1",
  "state": "vHao1p6OizzwReCkQMSpZA",
  "redirect": "urn:ietf:wg:oauth:2.0:oob:oauth-redirect-webchannel",
  "action": "signin",
  "declinedSyncEngines": ["history"],
  "offeredSyncEngines": ["history"]
}

support

Supported by oauth_webchannel_v1 context.