How to...

io.Connect Desktop allows showing a login screen before the first app is loaded. This is useful if you have shared authentication between your apps (SSO) and you want the user to log in just once.

To enable using a login screen, you have to modify the system configuration of io.Connect Desktop and create a configuration 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.

Configuration

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 defining a standalone SSO app configuration file, adding it to a system app store of io.Connect Desktop and enabling SSO authentication from 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 configuration file. This is 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 configuration file for your SSO app, follow these steps:

1. Enable the login screen using the "ssoAuth" top-level key in the system.json file of io.Connect Desktop located in %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config and set its "authController" property to "sso":

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

See also the authentication controller schema.

2. Create a configuration file for your SSO app.

⚠️ Note that it is 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 configuration for 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"
    }
}

3. 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 system app store and provide the location of your SSO app definition. The system app store can be a local or a remote app store.

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 using the "ssoAuth" top-level key in the system.json file of io.Connect Desktop located in %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config and set 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:

The "window" object has the following properties:

See also 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.

To hide or show the login screen via configuration, use the "hidden" property.

For standalone SSO app definitions the "hidden" property is located under 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, the "hidden" property is located in 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 service object injected in the global window object:

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

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

Authentication

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:

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 at runtime, use the getAuth() method of the iodesktop object:

const authInfo = await iodesktop.getAuth();

In the standard io.Connect Desktop deployment model, app definitions aren't stored locally on the user machine, but are served remotely. Remote apps and Layouts can be hosted and retrieved using io.Manager stores and/or REST stores.

The settings for the app and Layout stores are defined in the system.json file of io.Connect Desktop located in %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config. The app store settings are under the "appStores" top-level key, the Layout store settings are under the "layouts" top-level key.

⚠️ Note that io.Connect Desktop respects the FDC3 standards and can retrieve standard io.Connect, as well as FDC3-compliant app definitions. For more details on working with FDC3-compliant apps, see the FDC3 Compliance section, the FDC3 App Directory documentation and the FDC3 Application schema.

io.Manager

Apps

To configure io.Connect Desktop to fetch app definitions from io.Manager, set the "type" property of the app store configuration object to "server":

{
    "appStores": [
        {
            "type": "server"
        }
    ]
}

For more details, see App Stores > io.Manager Stores.

Layouts

To configure io.Connect Desktop to fetch Layouts from io.Manager, set the "type" property of the "store" object to "server":

{
    "layouts" : {
        "store": {
            "type": "server"
        }
    }
}

For more details, see Layout Stores.

REST Stores

Apps

To configure a connection to the REST service providing the app store, add a new entry to the "appStores" top-level key in the system.json file:

{
    "appStores": [
        {
            "type": "rest",
            "details": {
                "url": "http://localhost:3000/appd/v1/apps/search",
                "auth": "no-auth",
                "pollInterval": 30000,
                "enablePersistentCache": true,
                "cacheFolder": "%LocalAppData%/interop.io/io.Connect Desktop/UserData/%GLUE-ENV%-%GLUE-REGION%/configCache/"
            }
        }
    ]
}

The remote store must return app definitions in the following response shape:

{
    "applications": [
        // List of app definition objects.
        {}, {}
    ]
}

For more details, see App Stores > Remote.

Layouts

To configure a connection to the REST service providing the Layout store, edit the "layouts" top-level key in the system.json file:

{
    "layouts": {
        "store": {
            "type": "rest",
            "restURL": "http://localhost:8004/",
            "restFetchInterval": 20,
            "restClientAuth": "no-auth"
        }
    }
}

The remote store must return Layout definitions in the following response shape:

{
    "layouts": [
        // List of Layout definition objects.
        {}, {}
    ]
}

For more details, see Layout Stores.

Example Store Implementations

Apps

For a reference implementation of a remote app definitions store, see the Node.js REST Config example that implements the FDC3 App Directory and is compatible with io.Connect Desktop. This basic implementation doesn't take the user into account and returns the same set of data for all requests. For instructions on running the sample server on your machine, see the README file in the repository.

For a .NET implementation of a remote app definitions store, see the .NET REST Config example.

Layouts

For a reference implementation of a remote Layout definitions store, see the Node.js REST Config example. The user Layouts are stored in files with the same structure as local Layout files. This basic implementation doesn't take the user into account and returns the same set of data for all users. New Layouts are stored in files using the name of the Layout and there isn't validation for the name. The operation for removing a Layout isn't implemented and just logs to the console. For instructions on running the sample server on your machine, see the README file in the repository.

For a .NET implementation of a remote Layout definitions store, see the .NET REST Config example.

io.Connect Desktop allows running it in different environments and regions. Environments usually include development, testing, quality assurance, production environments, etc., in which io.Connect Desktop is tested or integrated. Regions can be any semantic groups - geographic regions, user groups, product categories, etc., defined by the client adopting io.Connect Desktop.

To enable io.Connect Desktop to run in different environments/regions, you must:

• create a separate system configuration file for each environment/region combination. You can use the system.json file of io.Connect Desktop located in %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config as a base system configuration template, common for all environments/regions;

• create different shortcuts pointing to the io.Connect Desktop executable file for each environment/region, and set command line arguments specifying the respective environment/region configuration file that will be merged with the base system configuration file;

System Configuration Files

To set different environments/regions in which to run io.Connect Desktop, use the system.json configuration file of io.Connect Desktop as a common configuration. Create separate system configuration files for all environments/regions and in each one define only the settings specific for the environment/region. When you start io.Connect Desktop in a certain environment/region, the respective configuration file will be merged with the base system.json file, overriding the settings in it.

See also the system configuration and the io.Connect Gateway configuration schemas.

It is important to either specify a different port for the io.Connect Gateway for each environment/region, or to use a Dynamic Gateway Port by setting the io.Connect Gateway port to 0 in the base system configuration file. Otherwise, you won't be able to run multiple instances of io.Connect Desktop simultaneously in different environments/regions, as the first started instance will occupy the specified port and the other instances won't be able to connect.

Use the "gw" top-level key in the system.json file to set the port number. The following example demonstrates how to configure io.Connect Desktop to use a random free port for each of its instances by setting the io.Connect Gateway port to 0:

{
    "gw": {
        "configuration": {
            "port": 0
        }
    }
}

The following example demonstrates creating a system configuration file for a "PROD" environment and an "EMEA" region, named system-PROD-EMEA.json. The port for the io.Connect Gateway isn't specified, as it is set to 0 in the common system configuration file. The only setting that will be overridden is for the app stores under the "appStores" top-level key:

// system-PROD-EMEA.json
{
    "env": "PROD",
    "region": "EMEA",
    "appStores": [
        {
            "type": "rest",
            "details": {
                "url": "https://my-domain.com/my-app-store",
                "auth": "no-auth",
                "pollInterval": 30000,
                "enablePersistentCache": true,
                "cacheFolder": "%LocalAppData%/interop.io/io.Connect Desktop/UserData/%GLUE-ENV%-%GLUE-REGION%/configCache/"
            }
        }
    ]
}

Keep in mind that by default io.Connect Desktop is configured to create sub-folders for each environment/region in the UserData and Cache folders by using the %GLUE-ENV% and %GLUE-REGION% environment variables:

{
    "folders": {
        "userData": "%LocalAppData%/interop.io/io.Connect Desktop/UserData/%GLUE-ENV%-%GLUE-REGION%/",
        "cache": "%LocalAppData%/interop.io/io.Connect Desktop/Cache/%GLUE-ENV%-%GLUE-REGION%/"
    }
}

This means that the information stored in these folders by default will be separated per environment/region. To avoid overwriting data in case you decide to change the locations of the /UserData and /Cache folders in your base configuration, either use the %GLUE-ENV% and %GLUE-REGION% environment variables to create sub-folders for each environment/region, or make sure that each environment/region configuration file specifies different locations for these folders.

Shortcuts

It's possible to create any number of shortcuts to io.Connect Desktop, which will allow you to launch it with custom configuration according to your requirements. The entry point executable is found in %LocalAppData%/interop.io/io.Connect Desktop/Desktop/io-connect-desktop.exe. Running it without arguments will use the default configuration located in %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config/system.json. To override the base configuration with the specific configuration for an environment/region, use the following template to provide command line arguments for each shortcut:

io-connect-desktop.exe [optional Electron arguments] -- config=<base config file> configOverrides config0=<custom config override> config1=...

Substitute <base config file> with the location of your base configuration file (usually config/system.json), and <custom config override> with the location of your configuration override file. It's possible to supply more than one configuration override files.

The following example demonstrates how to use the system.json file as a base configuration for io.Connect Desktop and override it with a file named system-PROD-EMEA.json and also placed in the %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config folder:

io-connect-desktop.exe -- config=config/system.json configOverrides config0=config/system-PROD-EMEA.json

⚠️ Note that to specify command line arguments using a shortcut to the io.Connect Desktop executable file, you must right click on the shortcut, select the "Properties" menu option, go to the "Target" field and add the arguments after the name of the executable file. Note the space before and after the double dash.

For details on how to automatically create shortcuts during installation when using the io.Connect Desktop installer app for deployment, see the Installer > Shortcuts section. Otherwise, you can use PowerShell or any other deployment technology to create shortcuts.

The configuration of io.Connect Desktop can be extended with configuration files hosted on io.Manager or on another REST service. The configurations from the remote location will be fetched on startup of io.Connect Desktop and will be merged with the locally available ones. You can also supply different remote configurations for each environment and region in which io.Connect Desktop runs.

The following minimal conditions must be met in order for io.Connect Desktop to function properly when extending its configuration with files from a remote location:

• There must be a locally available system.json file and the "region", "env", "folders", "registerHtmlContainer", "switches", "flash", "protocolHandler", "allowMultipleInstances" and "build" properties must be defined in it. All other properties of the system.json file can be defined in a remote location file.

• The stickywindows.json, channels.json and themes.json files must be present locally at least as empty files. The logger.json file must be present locally and must not be empty - there must be some configuration settings present in it.

Configuration

To enable io.Connect Desktop to fetch configurations from a remote location, use the "remoteConfig" top-level key in the gilding.json configuration file located in the %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config folder. This file contains settings for the so called gilding executable file, which is a thin wrapper around the actual io.Connect Desktop executable. One of its goals is to allow io.Connect Desktop to fetch its configurations from a remote location before initialization.

The following example demonstrates how to enable io.Connect Desktop to fetch configuration files from io.Manager:

{
    "remoteConfig": {
        "enabled": true,
        "url": "https://<URL-to-my-io.Manager>/api/systemConfig/get",
        "wipeFolder": true
    }
}

The "remoteConfig" object has the following properties, all of which are optional:

The REST endpoint must return data in the following format:

{
    "system.json": {
        // Overriding JSON configuration for the `system.json` file of io.Connect Desktop.
        "contents": { ... }
    },
    "stickywindows.json": {
        // Overriding JSON configuration for the `stickywindows.json` file of io.Connect Desktop.
        "contents": { ... }
    }
}

Each top-level key in the returned JSON object represents an io.Connect Desktop configuration file to be overridden and accepts an object with the following properties as a value:

Different Environments & Regions

To enable fetching remote configurations per environment and region for io.Connect Desktop, you must provide different versions of the gilding.json file for each environment and region. This way, each version of the gilding.json can have different settings for the "remoteConfig" object.

To provide a configuration file for the gilding executable as a command line argument, use the --gildingConfigFile=<file name> argument, where <file name> must be replaced with the name of your configuration file:

io-connect-desktop.exe --gildingConfigFile=gilding-DEV.json

You can also create different versions of the gilding.json file, named by using the gilding-<environment>-<region>.json pattern, where <environment> and <region> must be replaced with the environment and region in which io.Connect Desktop will run. For instance, if a file is named gilding-DEV-EMEA.json, the configuration in it will be used when io.Connect Desktop is started with the following system settings:

// In `system.json`.
{
    "env": "DEV",
    "region": "EMEA"
}

The environment and region specifiers in the file name are case insensitive, so naming your file gilding-DEV-EMEA.json or gilding-dev-emea.json makes no difference.

You can filter the io.Connect notifications, enable or disable notification toasts and specify their size and duration through configuration. For more details on how to configure the default notification apps or your custom Notifications App, see the Notifications section.

io.Connect Desktop has a built-in Feedback Form that allows users to send feedback with improvement suggestions or bug reports. The form can be configured to send an email with the report to the io.Connect team and/or to automatically create a Jira ticket with the issue reported by the user. Both on-premise and cloud-based Jira solutions are supported. For more details, see the More > Features > Issue Reporting section.

Feedback Button

The Feedback Form can be opened directly from an app instance by using the "Feedback" button in the app window header. The "Feedback" button is disabled by default and can be enabled globally from the system configuration of io.Connect Desktop or per app from the app definition file. The app definition will override the global system configuration. For more details, see the More > Features > Issue Reporting > Feedback Button section.

Configuration

The Feedback Form is configurable on a system level from the system.json file of io.Connect Desktop. For more details, see the More > Features > Issue Reporting > Configuration section.

io.Connect Desktop offers default confirmation dialogs that will be shown on system shutdown or restart and when a window that prevents closing is about to be closed. The default dialogs are configurable on a system level from the system.json file of io.Connect Desktop. you can also show your own custom dialogs programmatically. For more details on configuring the default dialogs and showing dialogs at runtime, see the More > APIs > Dialogs section.

Multiple Instances

To control running multiple instances of io.Connect Desktop, use the "allowMultipleInstances" top-level key in the system.json file.

The following example demonstrates how to prevent users from running multiple instances of io.Connect Desktop:

{
    "allowMultipleInstances": "never"
}

The "allowMultipleInstances" property accepts the following values:

Multiple Versions

It's possible to install multiple versions of io.Connect Desktop on the same machine. If you plan on supporting multiple installations, ensure that the different versions are installed in separate folders, and use relative paths in the system.json configuration file in order to avoid data overwriting.

⚠️ Note that the MS Office Adapters are integrated with the registered MS Office app at installation time. This means that only their last-installed version will be available.

Global Protocol Handler

The default name of the io.Connect global protocol is ioconnect, but you can change this prefix using the "protocol" property of the "protocolHandler" top-level key in the system.json file of io.Connect Desktop:

{
    "protocolHandler": {
        "protocol": "mycustomprotocol"
    }
}

The following example demonstrates how to start an interop-enabled app using the app protocol option after you have changed the default protocol name:

mycustomprotocol://app/clientlist

Client Certificates

The dialog that allows the user to choose from the available client certificates (certificates used in private organizations for user identification) can be configured on a system level from the system.json file of io.Connect Desktop. For more details, see the More > Features > Client Certificates section.

Logging

The logging mechanism of io.Connect Desktop is based on log4js-node and can be customized through the logger.json configuration file. You can modify the configuration for the default log appenders used by io.Connect Desktop or add your custom log appenders. For more details, see the Developers > Configuration > System > Logging section.