Skip to main content

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:

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.