Authentication

Overview

When using Auth0 authentication, the io.Manager Server will use Auth0 to authenticate incoming requests based on an Auth0 token. The io.Manager Admin UI will use Auth0 login to authenticate users and send the Auth0 token to the io.Manager Server.

Configuration

To enable Auth0 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:

The following sections provide examples of both options.

Server

To enable Auth0 authentication for the io.Manager Server, choose one of the following options depending on your deployment approach.

Environment Variables

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

Environment Variable Description
API_AUTH_AUTH0_AUDIENCE URL pointing to the resource that will consume the authentication token.
API_AUTH_AUTH0_ISSUER URL pointing to the issuer to be used for validation of authentication tokens.
API_AUTH_AUTH0_JWKSURI URL pointing to a JSON Web Key Set.
API_AUTH_EXCLUSIVE_USERS List of users that will be granted the GLUE42_SERVER_ADMIN role. This role is required to access the io.Manager Admin UI. The users must already exist in the database.
API_AUTH_METHOD Type of the authentication mechanism. Must be set to auth0.

Example configuration:

API_AUTH_METHOD=auth0
API_AUTH_AUTH0_AUDIENCE=https://example.com
API_AUTH_AUTH0_ISSUER=https://example.auth0.com
API_AUTH_AUTH0_JWKSURI=https://example.auth0.com/example/jwks.json
API_AUTH_EXCLUSIVE_USERS="[\"admin\"]"

Runtime Configuration

To enable Auth0 authentication for the io.Manager Server, set the auth_method property of the optional Config object for initializing the io.Manager Server to "auth0". Use the auth_exclusive_users and auth_auth0 properties to provide additional settings for the Auth0 authentication:

Property Type Description
auth_auth0 object Settings for the Auth0 authentication mechanism.
auth_exclusive_users string[] List of users that will be granted the GLUE42_SERVER_ADMIN role. This role is required to access the io.Manager Admin UI. The users must already exist in the database.
auth_method string Type of the authentication mechanism. Must be set to "auth0".

The auth_auth0 object has the following properties:

Property Type Description
audience string URL pointing to the resource that will consume the authentication token.
issuerBaseURL string URL pointing to the issuer to be used for validation of authentication tokens.
tokenSigningAlg string Algorithm for signing the authentication tokens.

Example configuration:

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

const config = {
    // Enabling Auth0 authentication.
    auth_method: "auth0",
    // List of users that will be granted the `GLUE42_SERVER_ADMIN` role.
    auth_exclusive_users: ["admin"],
    // Additional settings for Auth0 authentication.
    auth_auth0: {
        audience: "https://example.com",
        issuerBaseURL: "https://example.auth0.com",
        tokenSigningAlg: "RS256"
    }
};

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 Auth0 authentication for the io.Manager Admin UI, choose one of the following options depending on your deployment approach.

Environment Variables

To configure the Admin UI to use Auth0 authentication, set the following environment variables with the proper values. The REACT_APP_AUTH environment variable must be set to auth0:

Environment Variable Description
REACT_APP_AUTH Type of the authentication mechanism. Must be set to auth0.
REACT_APP_AUTH0_AUDIENCE URL pointing to the resource that will consume the authentication token.
REACT_APP_AUTH0_CLIENT_ID The "Client ID" found in the app settings of the Auth0 "Applications" page.
REACT_APP_AUTH0_DOMAIN URL pointing to your Auth0 account domain.
REACT_APP_AUTH0_REDIRECT_URL URL to which users will be redirected after a successful login. It's not required to set this variable. If not set, the location of the Admin UI will be used as a callback URL.

Example configuration:

REACT_APP_AUTH=auth0
REACT_APP_AUTH0_AUDIENCE=https://example.com
REACT_APP_AUTH0_CLIENT_ID=UujkIaDfKLrsTroKadsWgsFGw
REACT_APP_AUTH0_DOMAIN=https://example.auth0.com

Runtime Configuration

To enable Auth0 authentication for the Admin UI, set the auth property of the <Admin UI /> component to "auth0" and use the auth_auth0 property to provide additional settings for the Auth0 authentication.

The auth_auth0 object has the following properties:

Property Type Description
audience string URL pointing to the resource that will consume the authentication token.
clientId string The "Client ID" found in the app settings of the Auth0 "Applications" page.
domain string URL pointing to your Auth0 account domain.
redirectUri string URL to which users will be redirected after a successful login. It's not required to set this property. If not set, the location of the Admin UI will be used as a callback URL.

Example configuration:

<AdminUI
    apiURL="http://localhost:4356/api"
    auth="auth0"
    auth_auth0={{
        audience: "https://example.com",
        clientId: "UujkIaDfKLrsTroKadsWgsFGw",
        domain: "https://example.auth0.com"
    }}
/>

io.Connect Desktop

To enable Auth0 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 %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config folder. Add the following 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 in io.Manager. If you want io.Manager to be the only app store, set the "appStores" top-level key to an empty array.

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

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

Login Screen

For Auth0 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.

⚠️ Note that for this configuration for work properly, you must not set the REACT_APP_AUTH0_REDIRECT_URL environment variable, or the redirectUri property of the auth_auth0 object in the <Admin UI /> component.

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 Auth0 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",
        // Auth0 authentication.
        auth: {
            username: "username",
            token: {
                bearer: "my-auth-token"
            }
        },
        fetchIntervalMS: 10000,
        tokenRefreshIntervalMS: 15000,
        critical: true
    }
};

const { io } = await IOBrowserPlatform(config);

Example

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