Installing the USS Agent SSL certificate in Firefox

USS Agent for Windows performs SSL Interception to filter and control secure HTTPS web sites. For Edge, Internet Explorer and Chrome, the certificate is automatically installed during the agent installation process. However, for Firefox users the procedure is different and may require manual steps.

If you do not install the certificate, you will encounter security warnings in the browser.

This article provides a number of methods for installing the certificate.

This article is provided as a guide. Seek additional information from your Firefox administrator or community if required.

Method 1 - Manual Installation

To install the certificate, please follow these steps:

Right-click on the USS Agent tray icon and select Download root CA certificate.

Save the file to your computer e.g. ussagent.crt.

Open Firefox.

Navigate to Options / Advanced / Certificates / View Certificates and click the Authorities tab. Click Import and select the previously saved ussagent.crt file.

When prompted, check "Trust this CA to identify web sites".

Restart Firefox.

Method 2 - Configure Firefox to use Root Authorities manually

As of Firefox version 49, an option was included to allow Firefox to trust Root Authorities (external) within the Windows certificate store.  This means that certificates can be deployed via group policy as normal and Firefox will trust the same Root Authorities that browsers using the Windows Certificate store trust.

At the time of writing this article, Mozilla have not enabled this feature by default, so this method still requires some additional configuration. To enable this setting the security.enterprise_roots.enabled must be set to true.  For more details please see this issue report (external).

To enable this feature on a single computer, follow these steps:

  1. Within Firefox, type about:config in the address bar
  2. If prompted, accept any warnings
  3. Right-click to create a new boolean value, and enter security.enterprise_roots.enabled as the Name
  4. Set the value to true

Method 3 - Preference file and Group Policy:

You can use a preferences file to configure the security.enterprise_roots.enabled setting.

Use a text editor such as Notepad++ and ensure the files are created with ANSI encoding.

Create a new file called local-settings.js and add:

pref("general.config.obscure_value", 0);
pref("general.config.filename", "USS_Agent_Cert_Firefox.cfg");

Create a new file called USS_Agent_Cert_Firefox.cfg and add:

lockPref("security.enterprise_roots.enabled", true);
  1. The USS_Agent_Cert_Firefox.cfg file must be placed in the root of the Firefox directory. For example: c:\Program Files\Mozilla Firefox\USS_Agent_Cert_Firefox.cfg
  2. The local-settings.js file must be placed in the \defaults\pref sub-directory. For example: c:\Program Files\Mozilla Firefox\defaults\pref\local-settings.js

Microsoft Group Policy (GPO) can be used to distribute the Firefox preference files. 

The following instructions assume Firefox is installed in its default location. Paths may need to be updated depending on your environment.
  1. Add the files USS_Agent_Cert_Firefox.cfg and and local-settings.js to a network share.  Ensure that the share has read permissions for Domain Computers
  2. Create/Edit a group policy in Group Policy Management
  3. Edit the settings in Computer Configuration, Preferences, Windows Settings and then Files
  4. Right-click and select New File
  5. Point the Source File to USS_Agent_Cert_Firefox.cfg on the Network Share
  6. Point the Destination file to c:\Program Files\Mozilla Firefox\USS_Agent_Cert_Firefox.cfg and Apply
  7. Repeat the above step to copy the same file to c:\Program Files (x86)\Mozilla Firefox\USS_Agent_Cert_Firefox.cfg
  8. Repeat these steps to copy local-settings.js to c:\Program Files\Mozilla Firefox\defaults\pref\local-settings.js
  9. Repeat these steps to copy local-settings.js to c:\Program Files (x86)\Mozilla Firefox\defaults\pref\local-settings.js

Method 4 - Preference file and Script

The files created in the previous step can be deployed via a script to the required location during installation if you are planning to install Firefox via a script.  Information on how to perform a scripted installation of Firefox can be found here (external).

How did we do?