Deploying on macOS

If you want to deploy at scale on macOS we recommend using the macOS Browser helper.

The Browser helper passes the user's macOS account name (short name) to the Trelica Browser extension to transparently identify the user, regardless of web browser, avoiding any log in step.

This can be deployed with an MDM which can also help you force deploy the browser extensions too.

Why is the macOS Browser helper useful?

The browser extension needs to know the identity of the user to tell Trelica which business apps they are accessing.

Trelica has various ways to identify this. At the simplest level, the user can login to Trelica, although other approaches are available (e.g. if they're logged in to the web browser with a work account, or by sending the user a link to click to identify them).

Each of these approaches has downsides, particularly if multiple browsers are being used.

What is the macOS Browser helper?

The macOS Browser helper is a light-weight (under 200k) executable which uses the Native Messaging browser protocol to communicate with Chrome, Edge and Firefox.

The browser extension tells the browser to load the helper and all communication is through the browser.

Source code is available to customers upon request.

Installing the Browser helper

Go to Admin > Settings > Browser extension

Click to download the macOS browser helper package, and you will be shown the commands used to install and configure it:

Alternatively you can download the installer using curl:

curl -o ~/Downloads/TrelicaBrowserHelper.pkg \
    https://app-files.trelica.com/public/browserxtn/TrelicaBrowserHelper.pkg

Manual installation

You can install the package, simply by running the package from Finder, or by calling:

sudo installer -pkg ~/Downloads/TrelicaBrowserHelper.pkg -target /

Once installed, you will need to set the Organization ID and domain, which are shown when you download the package.

sudo /Library/Trelica/TrelicaBrowserHelper \
    init \
    --orgid xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
    --domain app.trelica.com

Alternatively you can set environment variables prior to calling the installer:

sudo launchctl setenv TRELICA_ORGID xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
sudo launchctl setenv TRELICA_DOMAIN app.trelica.com

sudo installer -pkg ~/Downloads/TrelicaBrowserHelper.pkg -target /

sudo launchctl unsetenv TRELICA_DOMAIN
sudo launchctl unsetenv TRELICA_ORGID

Replace the xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx with the Organization ID you took from Trelica.

If you are using Trelica's European hosting center, then please use eu.trelica.com for the domain.

Deployment at scale

We recommend distributing the helper and extensions to all users using an end-point management solution like JAMF or Kandji.

This 9 minute video takes you through end-to-end deploying for Chrome, Edge, Firefox and Safari on a clean VM, with steps and download links below.

Deployment sequencing

The order that you deploy elements will impact the user experience. We strongly recommend the sequence described below:

Configuration settings for the Browser Helper – this means that when the Browser Helper itself is deployed, it knows the correct domain and organization and won't need further configuration.
Browser Helper package – having this installed before the extension helps because then when the extension is installed it will try to interact with the Browser Helper to find out who the logged in user is.
Force install the browser extensions – the policy to force installed the extension should be applied last as this will ensure that when the extension loads it can talk to a correctly configured Browser Helper and log in should then be transparent.

If you can't control the order of deployment for the first two steps, it might be worth using a pre-install step to set the environment variables described above (depending on your MDM the installer might not have access to these). Alternatively a post-install step could be used to call sudo /Library/Trelica/TrelicaBrowserHelper initpassing the --orgid and --domain parameters.

We recommend deploying to a test machine first.

1. Configuration settings for the Browser Helper

Download the profile and load it into a text editor.

Find the PayloadContent section and edit the OrgId and Domain key values.

Unsigned profile: UNSIGNED_trelica-helper.mobileconfig

You can find your Organization ID by going to your Profile in Trelica:

Scroll down the page and copy the Organization ID to the clipboard

<key>PayloadContent</key>
<dict>
  <key>com.trelica.macapp</key>
  <dict>
    <key>Forced</key>
    <array>
      <dict>
        <key>mcx_preference_settings</key>
        <dict>
          <key>OrgId</key>
          <string><!-- YOUR ORG ID HERE --></string>
          <key>Domain</key>
          <string>app.trelica.com</string>
        </dict>
      </dict>
    </array>
  </dict>
</dict>

Save the file and upload it to your MDM

2. Deploy the Browser Helper

You must push the Browser Helper Configuration settings profile before you deploy the Browser Helper itself.

The Browser Helper package is a system-level installer (prior versions were user-scoped which often led to MDM issues).

It installs to /Library/Trelica. For troubleshooting, it writes a detailed install log to /var/log/trelica_postinstall.log which you can view with:

sudo cat /var/log/trelica_postinstall.log

Download: TrelicaBrowserHelper.pkg

3. Force install browser extensions

Download the profile below and upload it to your MDM.

The profile will force install the Trelica browser extension for Chrome, Edge and Firefox.

If you use managed Chrome settings in Google Workspace to 'force install' extensions, force-installing using a configuration profile will overwrite the Google Workspace settings. To prevent this, remove Chrome from the supplied configuration profile, and force install the Trelica extension in Google Admin (Chrome Browser > Apps & extensions) instead.

Unsigned profile: UNSIGNED_trelica-extensions.mobileconfig
Signed profile: trelica-extensions.mobileconfig

JumpCloud

The standard Trelica Browser Helper is a so-called 'component package'. JumpCloud's MDM system will only let you deploy 'distribution packages'. We've packaged up a distribution package (TrelicaBrowserHelper-Installer.pkg) to use with JumpCloud:

Download: TrelicaBrowserHelper-Installer.pkg

Safari

Extensions in Safari work differently to other browsers.

The extension is wrapped in a binary executable.
Extensions can't be force-installed — each user must manually enable the extension.
Users have to click an additional box to grant the extenson access to all web-pages.

Since the extension is wrapped in a binary you don't need to deploy the Browser helper separately (although you may want to do this for other browsers on the user's machine).

However, because the installation process requires manual steps, you may want to send emails to users with Authentication links to prompt them to install it.

The Safari extension wrapper app will read in the Organization ID and Domain from the device profile, like the Browser helper. It then saves this information to a Group Container that the extension can access. For troubleshooting, this is located at ~/Library/Group Containers/2MXR75AJYH.com.trelica.macgroup/Library/Application Support/Trelica/BrowserHelper.plist

Troubleshooting

The helper identifies the logged in user by the equivalent of the whoami command.

Trelica then tries to match the username returned to a Trelica person identity using any verified domains you have configured.

e.g. if you have the domains 'example.org' and 'example.com' registered as verified domains in Trelica, the user name 'jane.doe' will match to a person in Trelica with the email 'jane.doe@example.org' or 'jane.doe@example.com'.

If the user name doesn't contain an email address or if more than one user might be matched, then you may need to map user accounts to Trelica identities. Please contact support@trelica.com for help with this.

I'm having trouble deploying via an MDM

There's a script in this GitHub repository which can help with MDM deployment issues. It manually sets up the various files that the installer would normally deploy.

https://github.com/trelica/be-deployment

Where is the Browser helper installed?

The helper is installed to the /Library/Trelica folder.

Where is the Organization ID and domain stored?

The Organization ID and domain are stored in an XML file called BrowserHelper.plist. This is in the same folder as the Browser helper.

How does a browser know to run the Browser helper?

On macOS, browsers look for a file called com.trelica.browser_helper.json in a folder

/Library/Google/Chrome/NativeMessagingHosts
/Library/Application\ Support/Mozilla/NativeMessagingHosts
/Library/Microsoft/Edge/NativeMessagingHosts

This JSON manifest file contains a path attribute which tells the extension where to find the binary file.

Pre version 1.3 installers

In May 2025 a new version (1.3) of the BrowserHelper was released. This is a system-wide installer rather than user-scoped. This makes MDM deployment a lot simpler and less troublesome.

This applies to the binary as well as the browser-specific native messaging configuration.

For reference, earlier versions were installed to an App Group container.

The installer was deployed to:

~/Library/Group\ Containers/2MXR75AJYH.com.trelica.macgroup/Library/Application\ Support/Trelica

com.trelica.browser_helper.json was deployed to:

~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts
~/Library/Application\ Support/Mozilla/NativeMessagingHosts
~/Library/Application\ Support/Microsoft/Edge/NativeMessagingHosts

The v1.3 installer will automatically deinstall older versions but you can also use this script to remove the older BrowserHelper.

chmod +x ./trelica-old-beh-uninstall.sh && ./trelica-old-beh-uninstall.sh

Download: trelica-old-beh-uninstall.sh