Configuring the web browser whitelist

In Niagara 4.4 and later, using Workbench in a web browser is governed by the use of a whitelist, which adds security and customizability. The whitelist specifies exactly to which web addresses Workbench can navigate. Consequently, you can no longer use Workbench to freely browse external web addresses unless you configure the whitelist to allow it.

Prerequisites: You are aware of any security implications or organizational policies before allowing Workbench to browse the web unrestricted.

You configure the whitelist with approved hostnames, domains, and subdomains, optionally filtering on protocol, port, and path. For more customized filtering, you may also use the regex: prefix. If desired, you can completely disable the web browser.

Perform the following steps:

To navigate to the !defaults/system.properties file, expand My Host > My File System > Sys Home > defaults in the Nav tree and double-click system.properties.
The Text Editor view opens.
Scroll to the niagara.webbrowser.urlWhitelist property.
The default whitelist includes tridium.com” and “niagara-community.com, which are necessary to enable Cloud services, such as Device Registration.

Enter a comma-separated list of URL patterns that you have decided are acceptable for Workbench to navigate to.

To allow navigation to:	Enter the following value:
Web pages served by a particular hostname such as your localhost	`niagara.webbrowser.urlWhitelist=hostname`
Web server on any subdomain of a given domain such as `domain.com`, `www.domain.com`, `subdomain.domain.com`	`niagara.webbrowser.urlWhitelist=domain.com`
Specific subdomain such as allowing `www.domain.com`, but not `domain.com`	`niagara.webbrowser.urlWhitelist=www.domain.com`
Localhost but using only the specified protocol and port number, for example, using port 8088	`niagara.webbrowser.urlWhitelist=https://localhost:8088`
Any URL at domain.com, but filtering with a partial path such as `/public/`	`niagara.webbrowser.urlWhitelist=domain.com/public/`
Other whitelist configuration options:
Additional customizing is possible using regex syntax. The regex will match on any substring of the URL. For example, `regex:a` would match any URL that contains the letter “`a`”. Similarly, to match on any file ending in `.htm` at domain.com, but no other files	`niagara.webbrowser.urlWhitelist=regex:domain.com/.*/\\w+\\.htm$`
To specify multiple URL patterns, enter them in a comma-separated list	For example:`niagara.webbrowser.urlWhitelist=localhost,niagara-central.com,bacnet.org`
To effectively disable the whitelist, set it to an empty regex, which will match on any URL. Workbench can then be used to navigate to any URL. To set the property to an empty regex, enter:	`niagara.webbrowser.urlWhitelist=regex:`
To disable the web browser altogether, set the `niagara.webbrowser.disabled` property. Disabling the web browser, not only disables access to external URLs, but to all HTML content including the Workbench splash screen, the Px Editor Browser Preview mode, and all Web Widgets such as Property Sheet and Web Chart. To set the property enter:	`niagara.webbrowser.disabled=true`

On completion, save your configuration changes.
For your changes to take effect, exit Workbench by selecting File > Exit and restart it.
To use the whitelist, navigate to a URL using Workbench.
If the site is not allowed by the whitelist, click the Open In Desktop Browser command () in the toolbar to access the site in your desktop web browser.
The desktop browser opens.

If Cloud services does not work, your whitelist may be configured without tridium.com” and “niagara-community.com, which are required for Cloud services to work in Workbench. You will need to use your desktop browser instead. If the system property is missing, tridium.com,niagara-community.com serve as the default whitelist.

Configuring the web browser whitelist

Related Links