Enforcing DNS-over-HTTPS (DoH) via Firefox Enterprise Policies

The Problem: Inconsistent DNS Resolution Across Managed Endpoints

When deploying Firefox across an organization, relying on user-level settings for DNS-over-HTTPS (DoH) leads to inconsistent security postures and resolution failures. If users manually enable DoH, they may bypass corporate DNS filters; if they leave it disabled, DNS queries remain unencrypted and vulnerable to spoofing or interception.

The solution is to deploy a policies.json file in the Firefox installation directory. This forces the browser to use a specific encrypted resolver for all public queries while ensuring internal corporate domains continue to resolve via the local network DNS.

How the DNSOverHTTPS Policy Works

Firefox reads the policies.json file from the distribution folder during the startup sequence. Settings defined here are treated as "Managed Policies," meaning they override user preferences and are often locked in the browser UI to prevent tampering.

When the DNSOverHTTPS policy is active, Firefox wraps DNS queries in HTTPS requests and sends them to the specified provider. This prevents local network observers from seeing which domains the browser is requesting. However, because DoH only affects the browser, other system applications and OS services will continue to use the standard system resolver.

Implementation Example

To implement DoH, you must create a policies.json file. This file must be placed in the distribution directory of the Firefox installation path (e.g., C:\Program Files\Mozilla Firefox\distribution\ on Windows or /usr/lib/firefox/distribution/ on Linux).

{
  "policies": {
    "DNSOverHTTPS": {
      "Enabled": true,
      "ProviderURL": "https://dns.cloudflare-dns.com/dns-query",
      "ExcludedDomains": [
        "internal.corp.local",
        "wiki.company.test",
        "dev-server.local"
      ]
    }
  }
}

Configuration Breakdown:

• Enabled: Sets the DoH state to active.
• ProviderURL: The HTTPS endpoint of your chosen resolver. Replace the example URL with your organization's approved DoH provider.
• ExcludedDomains: A critical list of domains that must not use DoH. This ensures that "split-horizon" DNS (where a domain resolves differently inside vs. outside the network) continues to work for internal resources.

Deployment and Verification

Because policies are loaded at startup, simply opening a new window is insufficient. You must fully quit the Firefox process and relaunch it.

Verification Steps

1. Check Policy Status: Type about:policies in the address bar. You should see the DNSOverHTTPS policy listed as "Active."
2. Inspect Low-Level Config: Navigate to about:config and search for network.trr.uri. The value should match your ProviderURL.
3. Functional Test: Attempt to resolve a public site (e.g., google.com) and an internal site listed in ExcludedDomains. If the internal site fails to load, verify that the domain is correctly spelled in the ExcludedDomains array.

Limitations and Common Pitfalls

Technical Limitations

• Scope: DoH only encrypts the DNS lookup. It does not hide the destination IP address from the network, nor does it encrypt the subsequent TLS handshake (though ECH/Encrypted Client Hello is a separate evolving standard).
• Fallback Behavior: Depending on the Firefox version and region, if the DoH provider is unreachable, the browser may fall back to the system resolver. DoH is a preference, not a guaranteed tunnel.

Common Mistakes

• Wrong Directory: Placing policies.json in the user's profile folder. It must be in the installation's distribution folder to be recognized as a managed policy.
• JSON Syntax Errors: Including comments (//) or trailing commas after the last array item. Firefox will ignore the entire policy file if the JSON is invalid.
• Missing Internal Domains: Forgetting to add local TLDs (like .local or .lan) to ExcludedDomains, which results in internal sites becoming unreachable because public DoH providers cannot resolve private IP space.

Rollback Procedure

To revert these changes and return DNS control to the user or the system default, delete the policies.json file from the distribution directory and restart the browser. If the file was deployed via a Group Policy Object (GPO) or MDM, remove the corresponding registry key or configuration profile before restarting.