Deploying the macOS Browser helper

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:

Manual installation

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

sudo installer -pkg TrelicaBrowserHelper.pkg -target /Applications

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

~/Library/Group\ Containers/2MXR75AJYH.com.trelica.macgroup/Library/Application\ Support/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 TrelicaBrowserHelper.pkg -target /Applications

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 to all users using an end-point management solution like JAMF or Kandji.

You should also distribute the extensions.

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/Group\ Containers/2MXR75AJYH.com.trelica.macgroup/Library/Application\ Support/Trelica folder.

Where is the Organization ID and domain stored?

The Organization ID and domain are stored in an XML file called BrowserHelper.plist.

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/Application\ Support/Google/Chrome/NativeMessagingHosts
~/Library/Application\ Support/Mozilla/NativeMessagingHosts
~/Library/Application\ Support/Microsoft/Edge/NativeMessagingHosts

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