Configuring policies

Firefox enterprise policies can be applied using Group Policy for Active Directory-joined devices, Intune for cloud-based device management, or by creating a file called policies.json and setting the contents of the JSON file.

Configuring Firefox using `policies.json`

Using a policies.json file is a cross-platform method for configuring the Firefox browser. Firefox checks for the existence of a policies.json file and applies configuration based on its contents. For each operating system, there is a defined location that Firefox will check:

On Windows, create a directory called distribution where the Firefox executable is located and place the policies.json file there.
On macOS, the policies.json file goes into Firefox.app/Contents/Resources/distribution.
On Linux, the policies.json file goes into firefox/distribution, where firefox is the installation directory for firefox, which varies by distribution. Alternatively, you may specify system-wide policy by placing the file in /etc/firefox/policies. For Flatpak, see Configuring a Flatpak package below.

An example policy looks as follows:

{
  "policies": {
    "Homepage": {
      "URL": "https://internal.example.com",
      "Locked": true
    }
  }
}

Configuring a Flatpak package

The Flatpak build of Firefox runs in a sandbox and cannot read the host's /etc/firefox/policies directory. It reads system-wide policies from an Flatpak extension named org.mozilla.firefox.systemconfig in the sandbox at /app/etc/firefox. Nothing needs to be installed with flatpak install, admins create the directory structure on the host and place policies.json inside it.

To get started, place a policies.json file in a policies subdirectory of the extension directory on the host:

/var/lib/flatpak/extension/org.mozilla.firefox.systemconfig/<arch>/<branch>/policies/policies.json

Replace <arch> with the Flatpak architecture of the installed app, such as x86_64 or aarch64, and <branch> with its branch, which is typically stable. Run flatpak list --app --columns=application,arch,branch to check which values apply to a given machine.

For example, on an x86-64 machine running the release channel:

sudo mkdir -p /var/lib/flatpak/extension/org.mozilla.firefox.systemconfig/x86_64/stable/policies
sudo cp policies.json /var/lib/flatpak/extension/org.mozilla.firefox.systemconfig/x86_64/stable/policies/

Restart Firefox for the policies to take effect, then open about:policies to confirm that they were applied.

Policy annotations

JSON does not support comments, but it is possible to add extra members to JSON which can serve as comments or annotations. For example, Authentication_Comment is an internal value used for documentation in the following policy:

{
  "policies": {
    "Authentication": {
      "SPNEGO": ["mydomain.com", "https://myotherdomain.com"]
    }
    "Authentication_Comment": "These domains are required for us"
  }
}