Security

Overview

The following sections provide general guidelines on how to:

Configure your io.Connect Desktop platform in order to optimize the security measures applied to the io.Connect Gateway connections and the Electron window containers created by the underlying Electron framework.
Configure various security-related settings for your interop-enabled apps.

The io.Connect Gateway acts as a message bus between the io.Connect platform and all client apps, facilitating the communication and the data sharing between all interop-enabled apps. io.Connect Desktop provides settings for the io.Connect Gateway that allow you to fully control which clients will be able to connect to the io.Connect Gateway.

The configuration settings for the io.Connect Gateway are located under the "configuration" property of the "gw" top-level key in the system.json system configuration file of io.Connect Desktop. It's possible to configure the network access to the io.Connect Gateway and filter the connections by origin.

Network Access

By default, the io.Connect Gateway is accessible only to processes running on the same machine. To configure the network access to the io.Connect Gateway, use the "ip" property:

{
    "gw": {
        "configuration": {
            // Set to `127.0.0.1` by default.
            // If set to `0.0.0.0`, will allow access to the io.Connect Gateway to all processes in the same network.
            // Use this with caution in production environments.
            "ip": "127.0.0.1"
        }
    }
}

Origin Filtering

The io.Connect Gateway supports connection filtering based on the Origin header of the connection. By default, all origins are allowed and you should restrict this only to the trusted origins for your organization.

To configure the origin filter for the io.Connect Gateway, use the "origin_filters" property of the "security" object. The following example demonstrates how to allow connections from a trusted origin, block connections from other origins, and block connection requests in which the Origin header is missing:

{
    "gw": {
        "configuration": {
            "security": {
                "origin_filters": {
                    "whitelist": ["#https://my-org.com/.*"],
                    "missing": "blacklist",
                    "non_matched": "blacklist"
                }
            }
        }
    }
}

The "origin_filters" object has the following properties:

Property	Type	Description
`"blacklist"`	`string[]`	List of origins to block from connecting to the io.Connect Gateway. You can also use regular expressions (patterns must start with `#`). Defaults to `[]`.
`"missing"`	`"whitelist"` \| `"blacklist"`	Action to take if the `Origin` header in the connection request is missing. Defaults to `"whitelist"`.
`"non_matched"`	`"whitelist"` \| `"blacklist"`	Action to take if the origin isn't matched by the filters for allowing or blocking origins. Defaults to `"whitelist"`.
`"whitelist"`	`string[]`	List of origins for which to allow connections to the io.Connect Gateway. You can also use regular expressions (patterns must start with `#`). Defaults to `["#.*"]`.

Electron App

io.Connect Desktop uses the Electron framework for hosting web apps in windows on the desktop. This means that the security of your interop-enabled web apps is largely affected by the underlying security features and policies of the Electron framework. To avoid any potential security risks in the underlying Electron framework, the io.Connect Desktop platform is updated with the latest Electron version with each release. Therefore, it's highly recommended that clients upgrade their platforms to the latest io.Connect version too.

While regular upgrades can help improve your platform security, it's also important to be aware of and properly configure the available security settings related to the Electron window containers.

All security settings related to Electron windows are available on system level via the "system" top-level key in the system.json system configuration file of io.Connect Desktop, and per app (for web apps only) via the "system" property of the "details" top-level key in the app definition files. The settings in the app definition will override the settings in the system configuration.

All settings, except "onCertificateError" and "allowedExternalURISchemes", correspond exactly to the settings found in the WebPreferences object that describes the options for creating a BrowserWindow instance. The settings imported directly from the WebPreferences object have the same default values as in Electron.

ℹ️ For more details and best practices regarding the Electron security settings, see the Security Tutorial in the official Electron documentation.

The "security" object has the following properties:

Property	Type	Description
`"allowedExternalURISchemes"`	`string[]`	List of external URI schemes that are allowed to be opened. Use this to allow opening external URI schemes that aren't handled by the Electron framework by default.
`"allowRunningInsecureContent"`	`boolean`	If `true`, will allow an HTTPS page to run JavaScript, CSS or plugins from HTTP URLs. Defaults to `false`.
`"contextIsolation"`	`boolean`	If `true`, will allow running code in preload scripts and in Electron APIs in a dedicated JavaScript context. Context isolation allows each script running in the renderer process to make changes to its JavaScript environment without conflicting with scripts in the Electron API or preload script. Defaults to `false`.
`"navigateOnDragDrop"`	`boolean`	If `true`, dragging and dropping a file or a link onto the page will trigger navigation. Defaults to `false`.
`"nodeIntegration"`	`boolean`	If `true`, will enable Node.js integration. Defaults to `false`.
`"onCertificateError"`	`object`	Settings for handling web pages with invalid certificates.
`"sandbox"`	`boolean`	If `true` (default), the renderer associated with the window will be sandboxed, making it compatible with the Chromium OS-level sandbox and disabling the Node.js engine.
`"webSecurity"`	`boolean`	If `true` (default), web security will be enabled. Set to `false` to disable the same-origin policy (e.g., for testing purposes) and to set `"allowRunningInsecureContent"` to `true`.

The "onCertificateError" object has the following properties:

Property	Type	Description
`"action"`	`"allow"` \| `"deny"` \| `"ask"`	Controls the behavior for loading web pages with invalid certificates - whether to allow or deny loading the page, or to ask the user. Defaults to `"deny"`.
`"reportURL"`	`string`	URL pointing to a page that will be shown to the user and will allow them to report the issue. Only valid if `"action"` is set to `"ask"`.

io.Connect Apps

The system configuration of io.Connect Desktop and the app definition files enable you to configure various permission settings for your interop-enabled apps on a global level and per app respectively. You can use these settings to grant or deny permissions to your apps for accessing environment resources (cookies, OS info, environment variables, and more) or for performing certain actions (overriding app definition properties programmatically, executing code, manipulating request and response headers, and more).

The following example demonstrates using the "allowOverrides" property of the "details" top-level key in the app definition to prevent apps from overriding the "url" property in a web app definition when attempting to start this app programmatically via the io.Connect APIs:

{
    "details": {
        "url": "https://my-org.com/my-app",
        "allowOverrides": {
            // This is set to `true` by default and it's highly recommended to explicitly set it to `false`.
            "url": false
        }
    }
}

The following example demonstrates using the "allowOverrides" property of the "details" top-level key in the app definition to prevent apps from overriding the "command" property in a native app definition when attempting to start this app programmatically via the io.Connect APIs:

{
    "details": {
        "command": "MyApp.exe",
        "allowOverrides": {
            // This is set to `true` by default and it's highly recommended to explicitly set it to `false`.
            "command": false
        }
    }
}

For configuring other permissions for your apps, see the following sections:

Access to environment variables.
Access to OS info.
Access to auth info.
Allowing script execution.
Allowing cookies manipulation
Allowing request headers manipulation.
Allowing response headers manipulation.
Allowing proxy settings manipulation.
Allowing clearing DNS & HTTP cache.
Filtering URLs when opening new windows.
Handling the browser native window.open()