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 bound to loopback and is accessible only to local 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
            // and will render any origin filters useless.
            // 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.

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 `"blacklist"`.
`"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 `#`). The default origin filters are described below.

⚠️ Note that if you decide to open the network access instead of binding the io.Connect Gateway to loopback, the origin filters will be rendered useless since any untrusted app on the network can impersonate the Origin header.

Available since io.Connect Desktop 10.0

The default origin filters specified in the system.json file of io.Connect Desktop enable the platform to use the built-in launcher and the various demo apps distributed with the trial version. You should change these values to suit the needs of your project environment and improve the security of your platform.

The following example demonstrates the default io.Connect Desktop origin filters:

{
    "gw": {
        "configuration": {
            "security": {
                "origin_filters": {
                    // Allow apps that don't set the `Origin` header (e.g., Java, Node.js demo apps).
                    "missing": "whitelist",
                    "whitelist": [
                        // Allow apps loaded by the platform from local files (e.g., the built-in launcher).
                        "#file://.*",
                        // Allow apps that use the WebSocket protocol (e.g., .NET demo apps).
                        "#ws://.*",
                        // Allow apps loaded in the browser from local files.
                        "null",
                        // Allow apps hosted at `localhost`.
                        "#http(s)?://localhost:\\d+",
                        // Allow other demo apps hosted at the specified domains.
                        "#https://(.*\\.)?interop\\.io",
                        "#https://(.*\\.)?glue42\\.com",
                        "#https://(.*\\.)?tick42\\.com",
                        "#https://(.*\\.)?finos\\.org"
                    ],
                    // All other origins will be blocked.
                    "non_matched": "blacklist"
                }
            }
        }
    }
}

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).

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

Access to environment variables.
Access to OS info.
Access to auth info.
Allowing app definition overrides.
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()

Authentication

io.Connect Desktop doesn't provide a built-in support for any particular authentication mechanism, but rather provides mechanisms for easily integrating your already existing authentication processes. This design decision allows you to keep your existing authentication flows and processes unchanged, while still being able to leverage the io.Connect platform and its capabilities.

The io.Connect platform enables you to show a login screen (an SSO app) before the first client app has been loaded. The io.Connect API injected in the SSO app provides a method for signaling the platform when a user has been successfully authenticated. You can also pass to the platform any relevant information about the authenticated user, which the platform in turn will pass to io.Manager and to any other remote store connected to io.Connect Desktop. This information can later be retrieved by other apps in order to enhance the SSO flow when authentication is needed for additional services.

It's also possible to configure io.Connect Desktop to use SSO with Microsoft Entra ID.

Login Screen

To enable using a login screen, you have to modify the system configuration of io.Connect Desktop and create an app definition file for your SSO app. To complete the authentication process and allow the user access, you have to signal io.Connect that the user has logged in successfully.

The SSO app is a special system app that is loaded on startup of io.Connect Desktop and allows the user to authenticate. If authentication is successful, then all other app definitions are fetched and loaded based on user permissions.

There are two ways you can define your SSO app:

By creating a standalone SSO app definition file, adding it to a system app store of io.Connect Desktop, and enabling SSO authentication via the system.json file of io.Connect Desktop (see Standalone SSO App Definition). This is the recommended approach, as it allows you more freedom in configuring your SSO app.
By defining your SSO app directly in the system.json file of io.Connect Desktop (see SSO via System Configuration). Not recommended, as this way you can control only a very limited number of properties for the SSO app.

⚠️ Note that no matter how you choose to define your SSO app, it will have cookies manipulation and access to OS info enabled by default, even if you don't set these properties in its definition file, because SSO apps usually need such permissions in order to complete the authentication process.

Standalone SSO App Definition

If you decide to use a standalone app definition file for your SSO app, follow these steps:

Enable the login screen by using the "ssoAuth" top-level key in the system.json system configuration file of io.Connect Desktop and setting its "authController" property to "sso":

{
    "ssoAuth": {
        "authController": "sso"
    }
}

ℹ️ For details on the available properties for configuring the authentication mechanism of io.Connect Desktop, see the authentication controller schema.

Create an app definition file for your SSO app.

⚠️ Note that it's mandatory to use "sso-application" as a name for your app in the definition. Otherwise, io.Connect Desktop won't recognize your SSO app and will load the built-in login screen.

The following is an example definition of an SSO app:

{
    "name":"sso-application",
    "title":"My SSO App",
    "icon": "https://example.com/icon.ico",
    "type": "window",
    "details":{
        "url":"https://example.com",
        "mode": "html",
        "width": 400,
        "height": 400,
        "startLocation": "center"
    }
}

Add your SSO app definition to a system app store of io.Connect Desktop. A system app store contains system app definitions that are loaded before all other app definitions. Use the "systemAppStores" top-level key in the system.json file to define a local or a remote system app store and provide the location of your SSO app definition.

The following example demonstrates how to configure a local system app store:

{
    "systemAppStores": [
        {
            "type": "path",
            "details": {
                "path": "./config/system-apps"
            }
        }
    ]
}

SSO via System Configuration

⚠️ Note that this approach isn't recommended, because you can define only a very limited number of properties for your SSO app.

Enable the login screen by using the "ssoAuth" top-level key in the system.json system configuration file of io.Connect Desktop and setting its "authController" property to "sso". Use the "options" property to provide the location of the login screen and settings for the io.Connect Window in which it will be loaded:

{
    "ssoAuth": {
        "authController": "sso",
        "options": {
            "url": "http://localhost:3000/",
            "window": {
                "width": 500,
                "height": 730,
                "mode": "flat"
            }
        }
    }
}

The "options" object has the following properties:

Property	Type	Description
`"keepAlive"`	`boolean`	If `true`, io.Connect Desktop won't close the login window. This way, you can hide it yourself and use it to refresh the authentication arguments (user, token and headers) when necessary.
`"url"`	`string`	Location of the login screen. If not provided, will default to the location of the built-in login screen of io.Connect Desktop.
`"window"`	`object`	Settings for the io.Connect Window in which the login screen will be loaded.

The "window" object has the following properties:

Property	Type	Description
`"height"`	`integer`	Height in pixels for the login window.
`"hidden"`	`boolean`	If `true`, the login window will be hidden. Available since io.Connect Desktop* 9.4.*
`"mode"`	`string`	io.Connect Window mode. Possible values are `"html"` (default), `"flat"` and `"tab"`.
`"width"`	`integer`	Width in pixels for the login window.

ℹ️ For details on the available properties for configuring the authentication mechanism of io.Connect Desktop, see the authentication controller schema.

Visibility

Available since io.Connect Desktop 9.4

The visibility of the login screen can be controlled via configuration and programmatically.

For standalone SSO app definitions, use the "hidden" property of the "details" top-level key in the app definition:

{
    "name":"sso-application",
    "title":"My SSO App",
    "icon": "https://example.com/icon.ico",
    "type": "window",
    "details":{
        "url":"https://example.com",
        "mode": "html",
        "width": 400,
        "height": 400,
        "startLocation": "center",
        // Will hide the login screen from the user.
        "hidden": true
    }
}

For SSO apps defined via system configuration, use the "hidden" property of the "window" object under the "options" property of the "ssoAuth" top-level key in the system.json system configuration file of io.Connect Desktop:

{
    "ssoAuth": {
        "authController": "sso",
        "options": {
            "url": "http://localhost:3000/",
            "window": {
                "width": 500,
                "height": 730,
                "mode": "flat",
                // Will hide the login screen from the user.
                "hidden": true
            }
        }
    }
}

If you need to show or hide the SSO app dynamically, but don't want to initialize the entire @interopio/desktop library, use the showWindow() and hideWindow() methods of the iodesktop object injected in the global window object:

// Hide the login window.
await iodesktop.hideWindow();

// Show the login window.
await iodesktop.showWindow();

Signaling the Platform

To allow the user access after authenticating, you must signal io.Connect Desktop that the authentication process is complete. Use the authDone() method of the iodesktop object which is injected in the global window object. It accepts an optional object as an argument in which you can specify the name of the authenticated user, а token and headers:

const options = {
    user: "john.doe@org.com",
    token: "token",
    headers: {
        "name": "value"
    }
};

iodesktop.authDone(options);

The optional object passed as an argument to authDone() has the following properties:

Property	Type	Description
`headers`	`object`	JSON object with extra headers that will be passed to the remote stores or io.Manager.
`user`	`string`	The user ID will be set as a value of the `sid` property of `iodesktop`. Can be used for visualization purposes.
`token`	`string`	The token will be applied to each request to the remote stores or io.Manager.

The authentication information passed to the authDone() method can be later retrieved by other apps in order to enhance the SSO flow when authentication is needed for additional services. To allow apps to retrieve authentication information, use the "allowAuthInfo" property of the "details" top-level key in the app definition:

{
    "details": {
        "allowAuthInfo": true
    }
}

To retrieve the authentication information dynamically, use the getAuth() method of the iodesktop object:

const authInfo = await iodesktop.getAuth();

Microsoft Entra ID SSO

Available since io.Connect Desktop 9.12 & 10.0.4

io.Connect Desktop supports seamless SSO authentication with Microsoft Entra ID by automatically injecting Windows proof-of-possession cookies into requests to specified Microsoft Entra ID login URLs.

To enable SSO with Microsoft Entra ID, use the "entraSSO" top-level key in the system.json system configuration file:

{
    "entraSSO": {
        "urls": [
            "https://login.microsoftonline.com/*",
            "https://login.microsoft.com/*",
            "https://login.live.com/*",
            "https://*.microsoftonline.com/*"
        ]
    }
}

The "entraSSO" object has the following properties:

Property	Type	Description
`"urls"`	`string[]`	List of Microsoft Entra ID login URLs for which proof-of-possession cookies will be injected. Supports wildcard symbols (`*`). The default Microsoft Entra ID endpoints are included by default.