Authentication

When using Basic authentication, the io.Manager Server will use the "Basic" HTTP authentication scheme defined in RFC 7617 that transmits credentials as user ID and password pairs encoded in Base64 format. The client sends the user ID and password as a pair using the Authorization request header. The io.Manager Server will verify the user ID and password against the list of users and passwords it has in the database. If the user ID and password are valid, the io.Manager Server will sign a JWT with the user ID as the subject and will respond with the requested data, including a session cookie that contains the JWT for subsequent requests. This keeps the user logged in. If the user ID and password are invalid, the io.Manager Server will respond with a 401 Unauthorized status code.

⚠️ Note that as the user ID and password are passed over the network in the form of Base64-encoded text which is reversible, the "Basic" authentication scheme isn't secure. It's highly recommended to use HTTPS over TLS with Basic authentication. Without these additional security enhancements, Basic authentication shouldn't be used to protect sensitive information.

To enable Basic authentication, you must configure properly the io.Manager Server and Admin UI, as well as the io.Connect platform that will connect to io.Manager - io.Connect Desktop or io.Connect Browser.

Depending on the deployment approach you have chosen, you have the following options for configuring the io.Manager Server and Admin UI:

• If you are using the basic deployment scenario from the template repository approach, you must set properly the necessary environment variables.

• If you are using the NPM packages for deployment, or the advanced deployment scenario from the template repository approach, you must provide the necessary configuration settings when initializing the io.Manager Server and Admin UI.

The following sections provide examples of both options.

Server

To enable Basic authentication for the io.Manager Server, use the configuration object for initializing the io.Manager Server, or environment variables, depending on your deployment approach.

Environment Variables

To configure the io.Manager Server to use Basic authentication, register the following environment variables with the proper values. The API_AUTH_METHOD environment variable must be set to basic:

Example configuration with a user session length of two hours and CORS settings:

API_AUTH_METHOD=basic
API_AUTH_METHOD_BASIC_USERS="[\"admin:admin\"]"

# Configuring the user session length for the Admin UI.
API_AUTH_METHOD_BASIC_SESSION_LIFETIME=7200
# It's required to specify CORS options when session cookies are enabled.
API_CORS_OPTIONS={"credentials": true, "origin": "http://localhost:3000"}

Configuration Object

To enable Basic authentication for the io.Manager Server, set the auth_method property of the optional Config object for initializing the io.Manager Server to "basic". Use the auth_basic property to provide additional settings for the Basic authentication:

The auth_basic object has the following properties:

Example configuration with a user session length of two hours and CORS settings:

import { start } from "@interopio/manager";

const config = {
    // Enabling Basic authentication.
    auth_method: "basic",
    // Additional settings for Basic authentication.
    auth_basic: {
        predefinedUsers: ["admin:admin"],
        // Configuring the user session length for the Admin UI.
        sessionLifetime: 7200
    },
    // It's required to specify CORS options when session cookies are enabled.
    cors: {
        credentials: true,
        origin: "http://localhost:3000"
    }
};

const server = await start(config);

Admin UI

To access the io.Manager Admin UI, a user must be granted the GLUE42_SERVER_ADMIN role. The list of exclusive users with access to the Admin UI is defined in the io.Manager Server configuration. You can also grant this role to other users from the Admin UI.

To enable Basic authentication for the io.Manager Admin UI, use the <AdminUI /> component properties, or environment variables, depending on your deployment approach.

Environment Variables

To configure the Admin UI to use Basic authentication, set the REACT_APP_AUTH environment variable to basic:

REACT_APP_AUTH=basic

Component Properties

To enable Basic authentication for the Admin UI, set the auth property of the <Admin UI /> component to "basic":

<AdminUI
    apiURL="http://localhost:4356/api"
    auth="basic"
/>

By default, session cookies are enabled for the Admin UI which allows io.Manager to manage the Admin UI user sessions. To disable session cookies for Basic authentication, set the useSessionCookie property of the auth_basic object to false:

<AdminUI
    apiURL="http://localhost:4356/api"
    auth="basic"
    auth_basic={{
        useSessionCookie: false
    }}
/>

io.Connect Desktop

To enable Basic authentication for io.Connect Desktop, you must configure the connection to io.Manager and the login screen that's part of the Admin UI.

Connecting to io.Manager

To configure io.Connect Desktop to connect to io.Manager, use the "server" top-level key of the system.json system configuration file of io.Connect Desktop located in the <installation_location>/interop.io/io.Connect Desktop/Desktop/config folder. Add the following basic configuration to enable connection to io.Manager:

{
    "server": {
        "enabled": true,
        "url": "http://localhost:4356/api"
    }
}

This will add io.Manager as an additional app store and instruct it to store Layouts and app preferences. If you want io.Manager to be the only app store, set the "appStores" top-level key in the system.json file to an empty array.

To send client crashes to the io.Manager Server, edit the "output" property of the "crashReporter" top-level key in the system.json file:

{
    "crashReporter": {
        "output": {
            "type": "server",
            "serverUrl": "http://localhost:4356/api/crashes"
        }
    }
}

ℹ️ For more configuration options for connecting to io.Manager, see the Configuration > Platform section.

Login Screen

For Basic authentication to work properly in io.Connect Desktop, you must configure the login screen that's part of the Admin UI.

To enable the login screen, use the "ssoAuth" top-level key of the system.json file. Set the "authController" property of the "ssoAuth" object to "sso". Use the "options" object to provide the location of the login screen and settings for the io.Connect Window in which it will be loaded. The "url" property of the "options" object must point to the location of the Admin UI and must end with the gd query parameter, which will indicate that the login attempt is coming from io.Connect Desktop.

Example configuration:

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

io.Connect Browser

Connecting to io.Manager from an io.Connect Browser project requires modifying the configuration for initializing the @interopio/browser-platform library in the Main app.

To specify settings for the connection to the io.Manager, use the manager property of the optional configuration object when initializing the @interopio/browser-platform library. The following example demonstrates configuring the connection to io.Manager with Basic authentication:

import IOBrowserPlatform from "@interopio/browser-platform";

const config = {
    licenseKey: "my-license-key",
    manager: {
        // URL pointing to io.Manager.
        url: "https://my-io-manager.com:4242/api",
        // Basic authentication.
        auth: {
            basic: {
                username: "username",
                password: "password"
            }
        },
        fetchIntervalMS: 10000,
        tokenRefreshIntervalMS: 15000
    }
};

const { io } = await IOBrowserPlatform(config);

ℹ️ For more configuration options for connecting to io.Manager, see the Configuration > Platform section.

For a complete example of using Basic authentication in the io.Manager Server and Admin UI, see the Basic Authentication example on GitHub.