Firefox Enterprise deployment

Force-install SafePrompt and pre-configure your tenant key on a Firefox ESR fleet (Windows, macOS, Linux) through the official Mozilla policies.json file.

This guide is intended for IT administrators maintaining a Firefox fleet — typically finance, public sector or healthcare organizations that standardize on Firefox ESR for licensing or sovereignty reasons. By the end, SafePrompt will be installed automatically on every targeted device (Windows, macOS, Linux) and pre-configured with your tenant key via storage.managed — your users will not need to do anything.

Step 1 — Get your tenant_api_key

Sign in to the SafePrompt dashboard with your admin account. Your tenant_api_key and tenant_id are listed under Settings → Deployment. Copy both values — you will paste them into the policies.json file in the next step.

Step 2 — Download the policies.json file

Download the policies.json file below, open it in a text editor, and replace the three placeholders (<XPI_VERSION_ID>, <TENANT_API_KEY>, <TENANT_UUID>) with the values collected in step 1 and the XPI identifier provided by our team. The final file weighs less than 1 KB.

firefox-policies.json
{
  "policies": {
    "ExtensionSettings": {
      "[email protected]": {
        "installation_mode": "force_installed",
        "install_url": "https://addons.mozilla.org/firefox/downloads/file/<XPI_VERSION_ID>/safeprompt.xpi",
        "default_area": "navbar",
        "allowed_types": ["extension"]
      }
    },
    "3rdparty": {
      "Extensions": {
        "[email protected]": {
          "tenant_api_key": "<TENANT_API_KEY>",
          "tenant_id": "<TENANT_UUID>"
        }
      }
    }
  }
}

Download firefox-policies.json

Step 3 — Drop the file at the right location

Firefox reads policies.json at startup from a standard location that differs per platform. Drop the file with read permissions for every user (chmod 644 on Unix).

Windows

Drop policies.json in the Firefox distribution folder. If the distribution folder does not exist, create it. GPO or Intune-based deployments can write this file automatically.

text
C:\ProgramData\Mozilla\Firefox\distribution\policies.json

macOS

Drop policies.json inside the Firefox application bundle. For an MDM deployment (Jamf, Mosyle), push the file to the same path via a File payload.

text
/Applications/Firefox.app/Contents/Resources/distribution/policies.json

Linux

Drop policies.json in /etc/firefox/policies/. If the policies folder does not exist, create it (mkdir -p /etc/firefox/policies). Recommended permissions: 644 root:root.

text
/etc/firefox/policies/policies.json

Step 4 — Restart Firefox and check about:policies

On a target device, restart Firefox then verify that the policy is applied through the internal diagnostic page.

  1. Restart Firefox

    Close every Firefox window and relaunch the browser. Policies are only loaded on startup.

  2. Open about:policies

    Type about:policies in the address bar and press Enter. This page lists every active policy for the current user profile.

  3. Inspect the "Active" tab

    Select the "Active" tab. You should see the ExtensionSettings entry with [email protected] in force_installed mode, plus the 3rdparty section holding your tenant values.

Step 5 — Verify propagation inside the extension

Make sure the extension actually receives the tenant values through the browser.storage.managed API.

  1. Open about:debugging

    Type about:debugging in the address bar and press Enter. This page lets you inspect every installed extension.

  2. Select "This Firefox"

    In the left-hand menu, click "This Firefox". The list of extensions installed on the current profile is displayed.

  3. Inspect SafePrompt

    Find the SafePrompt entry in the list and click "Inspect". A DevTools window opens, attached to the extension service worker.

  4. Run the verification command

    In the Console tab of DevTools, paste the command below. You should get back an object containing your tenant_api_key and tenant_id values. If the object is empty, double-check step 4 and restart Firefox again.
javascript
await browser.storage.managed.get(['tenant_api_key', 'tenant_id'])

Edge cases

A few common situations in multi-vendor deployments or in highly secured environments.

Multiple co-existing policies.json

If another vendor (antivirus, SSO, browser managed by your IT department) already drops a policies.json on the devices, Firefox prioritizes by location: the file at the standard enterprise location (distribution/ or /etc/firefox/policies/) wins and the others are ignored. There is no automatic merge mechanism — you must consolidate every policy from your organization into a single file.

BlockedInstallMessage option (off by default in V1)

Firefox ships a BlockedInstallMessage policy that blocks the install of any extension outside a safelist and shows a custom message to users. This option is useful for highly constrained environments (banks, defense) but can break legitimate user workflows (productivity extensions, translators). It is off by default in our V1 template — only enable it if your CISO requires it.

Need help?

Our team answers enterprise deployment questions within one business day. Send a message to [email protected].

← Back to deployment guides