DEPRECATED: How to connect Firefox for Android to self-hosted Firefox Account and Firefox Sync servers
THIS BLOG POST IS DEPRECATED
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.
Background
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).
Guide
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.
Conclusion
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!
Footnotes
| [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. |
| [3] | 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.
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. |
| [4] | 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. |
Changes
- 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.
About Nick Alexander
Mathematician. Mozillian. Runner. Master of Disguise.
