DOCSEARCHbyAlgolia
Submit Docs

Firefox Accounts (FxA) Self-Hosting

repository·master·Indexed 41 days ago

https://github.com/jackyzy823/fxa-selfhosting

A self-hosted implementation of the Firefox Accounts (FxA) server for hosting private account and sync services. Includes deployment guides via Docker Compose, configuration for Fenix clients, and support for self-signed HTTPS environments. Requires FxA version >= 1.338.0 for Firefox 154.0+ compatibility.

Tokens
1.9K
Snippets
2
Records
10
Agent score
52%

What's inside fxa-selfhosting

  1. Important: FxA Version Compatibility for Firefox >= 154.0

    master

    If you are using Firefox version 154.0 or newer, you MUST use an FxA version >= 1.338.0.

    Newer Firefox clients use a different authorization header format (e.g., prefixes like fxs_xxxx) that older FxA servers cannot process. FxA version 1.342.2 is the first version in this project verified to work with these changes.

  2. Configure Fenix client for self-hosted FxA

    master

    To use the Fenix client with your custom server:

    1. Server-side Setup (Pre-requisite):
      • Edit /_init/auth/oauthserver-prod.json to set the Fenix redirect URI and add the scope: "scope": "https://identity.mozilla.com/tokens/session".
      • Edit _init/content/contentserver-prod.json to set the oldsync redirect URI to oauth/success/a2270f727f45f648.
    2. Client-side Setup:
      • Install the newest version of Fenix.
      • Open the app and navigate to: Settings -> About Firefox -> Click Firefox icon 5 times.
      • Go back and edit:
        • Custom Firefox Account server: Set to your content server URL (e.g., https://www.fxa.example.local).
        • Custom Sync server: Set to your sync server URL (e.g., https://token.fxa.example.local/token/1.0/sync/1.5).

  4. Configure Firefox for optimization via about:config

    master

    To optimize the Firefox client experience with your self-hosted FxA server, you can adjust the following about:config settings:

    webextensions.storage.sync.enabled: true
services.sync.extension-storage.skipPercentageChance: 0
services.sync.scheduler.activeInterval: 10
services.sync.scheduler.fxa.singleDeviceInterval: 10
services.sync.scheduler.idleInterval: 10
services.sync.scheduler.idleTime: 10
services.sync.scheduler.immediateInterval: 10
services.sync.syncInterval: 60
services.sync.syncThreshold: 10

  5. Install the self-hosted Firefox Accounts server

    master

    Follow these steps to deploy the FxA server using Docker Compose:

    1. DNS Setup: Create DNS records for the following subdomains (sharing the same base APEX domain):
      • www (content-server)
      • profile (profile-server)
      • token (syncserver)
      • api (auth-server)
      • oauth (oauth-server) Refer to the domain section in config.yml.sample for details.
    2. SSL/TLS: Obtain certificates for each subdomain or a wildcard certificate covering all subdomains.
    3. Configuration:
      • Copy config.yml.sample to config.yml and edit it with your actual configuration.
    4. Initialization:
      • Run ./init.sh after every edit to config.yml or files in _init. This generates docker-compose.yml and other configs in the ./dest folder.
      • Note: You can change the destination folder using DEST=somefolder ./init.sh.
    5. Deployment:
      • Navigate to the destination folder: cd dest
      • Start the services: docker compose up -d
    6. Client Configuration:
      • Follow the instructions provided in the output of ./init.sh to configure your Firefox browser.
      • CRITICAL: You MUST restart the browser after configuration to avoid bugs like non-responsive sign-up pages or unverified accounts.

    Requirements:

    • At least 2GB RAM
    • Docker
    • Docker-compose (v1.29.0+) or the docker compose plugin.
    # Example initialization and deployment flow
cp config.yml.sample config.yml
# Edit config.yml with your domains/certs
./init.sh
cd dest
docker compose up -d

  6. Understand TTL constraints in syncserver(py) MySQL storage

    master

    When using the Python version of syncserver with MySQL, be aware of the constraints on the bso.ttl (Basic Storage Object Time To Live) value. The ttl is treated as a signed integer.

    • Maximum Value: 2147483647 (represents Tue Jan 19 11:14:07 2038).
    • Default Value: 2100000000 (represents Fri Jul 18 21:20:00 2036).

    Note that there may be a conceptual confusion between ttl and expiry_time within the database and the Basic Storage Object (BSO) implementation.

  7. Set up a fully self-signed HTTPS environment

    master

    This guide describes how to configure a fully self-signed HTTPS setup for the Firefox Accounts (FxA) server, which is useful for local LAN environments where HTTPS is required. The process involves generating certificates on the host machine and configuring the client (user machine) to trust the self-signed Root CA.

    Host Machine Setup

    1. Generate Certificates: Modify the certificate parameters (Common Name, Subject Alternative Name, days) in ./examples/full_selfsign/generate-cert.sh and execute it.
    2. Configure Domain: Edit the domain.name field in config.yml to match your environment.
    3. Configure Nginx/Reverse Proxy:
      • If using a reverse proxy: Use the certificates generated by generate-cert.sh in your reverse proxy configuration. Refer to ./examples/reverse_proxy_nossl/reverse_proxy.conf or ./examples/reverse_proxy_ssl/reverse_proxy.conf for reference.
      • If not using a reverse proxy: Modify config.yml to make Nginx listen on port 443 and use the certificates generated by generate-cert.sh. See ./examples/full_selfsign/config.yml for the configuration template.

    User Machine Setup (Client)

    Note: All steps are critical for successful connection.

    1. DNS/Hosts Mapping: Update the /etc/hosts file on the user machine to point all required subdomains to the Host Machine's IP address (e.g., 192.168.100.101).
    2. Firefox Configuration: Update the Firefox configuration settings based on the output provided by the init.sh script.
    3. Import Root CA: Import RootCA.crt into Firefox:
      • Navigate to about:preferences#privacy.
      • Go to View certificates -> import.
      • Ensure you check the box Trust this CA to identify websites.
    4. Authentication: Attempt to sign in.
    # Example Host Machine Steps
./examples/full_selfsign/generate-cert.sh

# Example User Machine Steps
# Update /etc/hosts with Host IP
# Import RootCA.crt in Firefox (about:preferences#privacy)

  9. Upgrade notices and breaking changes

    master

    Upgrading to v1.330

    • The graphql subdomain and its certificate are no longer required.
    • debug.full_self_sign_workaround = true is no longer needed.

    Upgrading from v1.277.3

    • Firefox now uses oauth_webchannel_v1 instead of fx_desktop_v3 as the context parameter.
    • To continue using fx_desktop_v3, set identity.fxaccounts.oauth.enabled to false (Note: this may break the content-server).

    Upgrading from v1.242.4

    • [BREAKING] MySQL upgraded from 5.7 to 8.0. It is recommended to use version 8.0.16+ for auto-upgrades; otherwise, run mysql_upgrade manually.

    Upgrading from v1.215.2

    • [BREAKING] MySQL upgraded from 5.6 to 5.7. You must manually run docker-compose exec mysqldb mysql_upgrade.
    • Requires a docker-compose version that supports the service_completed_successfully condition for depends_on.