DEPRECATED: How to connect Firefox for Android to self-hosted Firefox Account and Firefox Sync servers

Sat 05 July 2014 / tagged: android, sync


Firefox for Android 44 and above no longer require an addon to connect to custom Firefox Account and Firefox Sync servers.

The documentation at https://docs.services.mozilla.com/howtos/run-sync-1.5.html and https://docs.services.mozilla.com/howtos/run-fxa.html has been updated and is now the canonical documentation for configuring custom servers in Firefox for Android.

The contents of this blog post have been maintained for interested parties to inspect.

Original content

Firefox 29 was a huge release. The two largest items were, by most measures, the new Australis Desktop theme, and the new Firefox Accounts sign-in to Firefox Sync. In the rush to land the new Firefox Account sign-in, we pared our feature set aggressively. One of the things that got delayed was support in Firefox for Android for connecting to self-hosted Firefox Account auth servers, and to self-hosted Firefox Sync servers. I’m thrilled to announce that support for such self-hosted servers has just landed in Firefox Nightly, and should make it to release as part of Firefox 33.


Historically, connecting Firefox to a self-hosted Firefox Sync server was — if not easy — at least possible and supported in all products, including Firefox for Android. The new Firefox Accounts system introduces a redesigned, easy to use sign-up/sign-in flow that delivers great user value, but it’s complicated to host your own servers. Instead of talking to a single Firefox Sync server, you need to talk to a Firefox Accounts auth server and a Firefox Sync server, both working in tandem to provide your service. Dan Callahan has been leading the effort to clarify the self-hosted server side of the story, and we have work in progress documentation explaining how to use self-hosted servers (in Firefox Desktop).


Firefox for Android 33 lets you

  • specify your Firefox Account and Sync servers before connecting your device to an account, and
  • see what servers your device is talking to after you have connected your device.

Let’s see how to use the new features.

Determine your custom server URLs

These URLs are a bit magic, and it’s not currently possible to change them on your Android device without deleting the Android Account and starting again.

Firefox Account auth server

The Firefox Account auth server URL should look like:

Type Auth server URL
Custom http://domain.com:5001/v1
Mozilla production https://api.accounts.firefox.com/v1
Mozilla testing https://api-accounts.stage.mozaws.net/v1

This should match the identity.fxaccounts.auth.uri preference in your Desktop Firefox configuration.

You can get a decent idea if your URL is correct by doing an HTTP POST with /account/login appended to your auth server URL. You should get an HTTP 400 response, like:

chocho:~ nalexander$ curl -X POST https://api.accounts.firefox.com/v1/account/login
{"code":400,"errno":107,"error":"Bad Request","message":"Invalid parameter in request body",...

Firefox Sync token server

The Firefox Sync token server URL should look like:

Type Token server URL
Custom http://domain.com:5001/token/1.0/sync/1.5
Mozilla production https://token.services.mozilla.com/1.0/sync/1.5
Mozilla testing https://token.stage.mozaws.net/1.0/sync/1.5

This should match the identity.sync.tokenServerURI preference in your Desktop Firefox configuration. (Prior to Firefox 42, the token server preference name for Firefox Desktop was services.sync.tokenServerURI. While the old preference name will work in Firefox 42 and later, the new preference is recommended: the old preference name will be reset when the user signs out from Sync, potentially causing confusion.)

If you are using a custom token server, it’s "public URL" should be set to http://domain.com:5001.

You can get a decent idea if your URL is correct by doing an HTTP GET after dropping the 1.0/sync/1.5 from your token server URL. You should get a list of services; for example:

chocho:~ nalexander$ curl https://token.services.mozilla.com
{"services": {"sync": ["1.5"]}, "auth": "https://token.services.mozilla.com"}

Install Firefox for Android 33

First, let’s install Firefox version 33 (or higher). You can download a recent Firefox Nightly here. Download the fennec-33.0a1.multi.android-arm.apk file and install it on your device. Open Firefox.

Install the fxa-custom-server-addon Firefox for Android add-on

Tap back several times to return to Firefox. We need to install a custom Firefox for Android add-on called fxa-custom-server-addon. This add-on lets us specify self-hosted servers [1].

Tap the link above in Firefox for Android, and click the (hopefully green!) Add to Firefox button. Since this add-on is hosted at the Firefox for Android Add-ons site, you should not see a warning when you install. (If you do, Allow the installation, and then Install the downloaded add-on — and please let me know.)

After you see a toast saying that the add-on is installed, tap the menu. You should see a new Custom Firefox Account menu item, right at the bottom.

Launch the Sync set-up flow with self-hosted server URLs

From the menu, tap the new Custom Firefox Account menu item. Now you can enter your self-hosted server URLs! The Save button closes the dialog but keeps your entered URLs for next time; it makes it easy to copy-and-paste your URLs from elsewhere. When you’ve got your URLs correct, tap Launch Setup. (It can help to flip your device to landscape mode.)

You should skip right past the Get Started screen and go directly to the sign-up/sign-in flow. Most importantly, you should see big boxes loudly announcing that you are using non-standard server URLs [2]. If you tap Already have an account? Sign in, you’ll see the sign-in flow, still with the non-standard server URL boxes.

The server URLs I’ve entered are Mozilla’s staging test servers. Our quality assurance team uses these servers to verify that new versions of the Sync client and server are working before they get released. The accounts and data on Mozilla’s staging servers are frequently deleted, so you shouldn’t use these staging test servers. (You should either self-host your own servers — that’s why you’re here — or use Mozilla’s standard production servers.)

I have already created an account on Mozilla’s staging test servers, so I’m going to sign-in to it. I tap Sign in, and I see that my account has already been verified. I tap Back to browsing, and I’m back in Firefox, with my shiny new Firefox Account ready to Sync.

Note: When this was written, there was a bug with custom servers with non-standard ports (in Firefox for Android 33 and 34 only). Bug 1046020 fixes an issue where custom servers with non-standard ports (i.e., servers with a non-80 port for HTTP or non-443 port for HTTPS) failed to sync. The failure looked like an authentication error when requesting a token from the token server. The fix is in Nightly 34, has been uplifted to Firefox 33, and should be present in Aurora 33 by the end of August. Many thanks to user Ben Curtis for reporting and fixing this issue!

Verify that Firefox Sync is using self-hosted server URLs

Let’s verify that our device is connected to a Firefox Account and is healthy by inspecting our server URLs in the Firefox Account settings. Tap the menu, and then Settings > Sync. Observe that we have two new sections, labeled Account server and Sync server. You should see the self-hosted server URLs you entered in the sign-up/sign-in flow [3].

You can also watch the adb logcat while syncing to see what URLs are being used [4].

The fxa-custom-server-addon has done its job, and you can safely remove it entirely: tap the menu and then select Tools > Add-ons to uninstall it.


Firefox 33 allows you to

  • specify self-hosted Firefox Account and Sync servers when connecting a device, and
  • see what servers your device is connected to.

We hope Firefox for Android works well with your self-hosted servers!


[1]You can see the fxa-custom-server-addon‘s source code and you can write your own add-on using the brand new Accounts.jsm add-on API that we built to support these features.
[2]The boxes are red because we absolutely don’t want a new user to accidentally use a non-standard, non-Mozilla server when they didn’t choose to do so explicitly. If changing the server is too easy, or the change is not visible, there is a possible attack on the user’s private Sync data.

Changing the (self-hosted) servers after you’ve connected your device is a non-goal. If you want to change servers, delete your account using the Android Settings App, and create a new one with the updated server URLs.

Why is this? There are two main reasons.

  • Sync on Android maintains a number of caches and partial sync states to provide an efficient sync experience. It’s very difficult to sync smoothly through a change of servers.

  • Sync on Android is not like Desktop. It’s not written in C++ and JavaScript, like the rest of the Firefox Desktop; as my colleague Richard says,

    It’s best to think of Sync on Android as being a separate pure-Java application that’s bundled with Firefox. Sync doesn’t use the same network stack, or any of the Gecko features that you might be used to from desktop.

This means that we can’t just edit a few preferences using about:config or some JavaScript. We would have to provide a Java user-interface (or a Gecko-to-Java bridge that respects Sync’s runtime lifecycle) to allow such changes, and that is an on-going maintenance burden.


The sure-fire way to know what Sync on Android is really doing is to observe the Android device log using adb logcat.

You’ll want to bump your log-level:

adb shell setprop log.tag.FxAccounts VERBOSE

Then, you can observe the log using:

adb logcat | grep FxAccounts

It’s best to observe the log while you force a sync from the Android Settings App. You should see output like:

D FxAccounts(...) fennec :: BaseResource :: HTTP GET https://token.stage.mozaws.net/1.0/sync/1.5
D FxAccounts(...) fennec :: BaseResource :: HTTP GET https://sync-4-us-east-1.stage.mozaws.net/...

See How to file a good Android Sync bug for details.


  • Mon 21 July 2014: Updated link to fxa-custom-server-addon to point to Firefox for Android Add-ons site. Thanks to IRC user zombie for testing!
  • Mon 18 August 2014: Added note about bug with custom server ports.
  • Wed 5 August 2015: Per Bug 1003708, replaced services.sync.tokenServerURI with identity.sync.tokenServerURI.
  • Mon 1 February 2016: deprecated entire post and linked to new documentation.
Nick Alexander

About Nick Alexander

Mathematician. Mozillian. Runner. Master of Disguise.