Configuration

Overview

The following sections provide a comprehensive reference documentation of the available settings for configuring the io.Manager Admin UI via the component properties of the <AdminUI /> React component exported by the @interopio/manager-admin-ui library and via the respective environment variables, depending on your deployment approach.

Component Properties

The following example demonstrates basic configuration of the <AdminUI /> component:

import AdminUI from "@interopio/manager-admin-ui";
import "@interopio/manager-admin-ui/styles.css";

const App = () => {
    return(
        <AdminUI
            // URL of the io.Manager Server to which the Admin UI will connect.
            apiURL="http://localhost:4242/api"
            // Base path that will be added to the URL of the Admin UI.
            baseName="/admin-ui"
            // Authentication method.
            auth="none"
            // License for AG Grid.
            agGridLicKey="my-ag-grid-license-key"
        />
    )
}

export default App;

Top-Level Properties

The following table describes all top-level properties of the <AdminUI /> component:

Property	Type	Description
`agGridLicKey`	`string`	AG Grid license key. If provided, will enable AG Grid Enterprise features in the Admin UI. For more details, see the AG Grid official site.
`apiURL`	`string`	URL of the io.Manager Server to which the Admin UI will connect. Defaults to `""`.
`auth`	`"none"` \| `"basic"` \| `"auth0"` \| `"okta"` \| `object`	Authentication method for the Admin UI. Use one of the supported authentication methods, or specify a custom authentication implementation by providing an `AuthProvider` object. Defaults to `"basic"`.
`auth_auth0`	`object`	Configuration for Auth0 authentication. Accepts an `Auth0ProviderOptions` object as a value. Valid only if the `auth` property is set to `"auth0"`.
`auth_basic`	`object`	Configuration for Basic authentication. Accepts a `BasicAuthOptions` object as a value. Valid only if the `auth` property is set to `"basic"` Available since io.Manager* Admin UI 3.1*.
`auth_okta`	`object`	Configuration for Okta authentication. Accepts an `OktaAuthOptions` object as a value. Valid only if the `auth` property is set to `"okta"`.
`authUser`	`string`	Username to be used for all logins in the Admin UI when the `auth` property is set to `"none"`. If the Admin UI is accessed from io.Connect Desktop, the local machine username will be used instead. Defaults to `"admin"`.
`baseName`	`string`	Base path that will be added to the Admin UI origin. If you set this to `"/admin-ui"`, the Admin UI will be served at `<origin>/admin-ui` (e.g., `http://localhost:3000/admin-ui`). Defaults to `""`.
`interceptor`	`object`	Custom Axios interceptor for handling responses from the io.Manager Server. Accepts an `Interceptor` object as a value.
`logOutUrl`	`string`	Absolute URL of the Admin UI logout page (e.g., `http://localhost:3000/admin-ui/logout`). Defaults to `<origin>/<baseName>/logout`.
`theme`	`"dark"` \| `"light"`	Sets the default theme of the Admin UI. Users can change the theme from the UI. Defaults to the OS theme.

Auth0ProviderOptions

Configuration for Auth0 authentication.

Property	Type	Description
`authorizationParams`	`object`	Authorization parameters passed to the Auth0 authorization server.
`cacheLocation`	`"memory"` \| `"localstorage"`	Cache location for the access tokens. Set to `"localstorage"` to store the access tokens in local storage instead of in-memory. Defaults to `"memory"`.
`clientId`	`string`	Required. The client ID found in the app settings of the Auth0 "Applications" page.
`domain`	`string`	Required. URL pointing to your Auth0 account domain.
`useRefreshTokens`	`boolean`	If `true`, will enable refresh token rotation.

The authorizationParams object has the following properties:

Property	Type	Description
`audience`	`string`	URL pointing to the resource that will consume the access token.
`redirect_uri`	`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.

ℹ️ For more details on the Auth0ProviderOptions object and its properties, see the @auth0/auth0-react official documentation.

AuthProvider

Custom authentication implementation.

Property	Type	Description
`addCredentialsToRequest`	`boolean`	Required. Passed to the `withCredentials` property of the `XMLHttpRequest` object.
`addCustomHeaders`	`boolean`	If `true`, all headers defined in the `customHeaders` property will be added to all requests sent to the io.Manager Server.
`addTokenToRequest`	`boolean`	Required. If `true`, will send the token retrieved via `getAccessToken()` with each request sent to the io.Manager Server.
`addUsernameToRequest`	`string` \| `boolean`	Required. If `true`, will send the user ID retrieved via `getUserInfo()` with each request sent to the io.Manager Server. Use this only for testing or demo purposes.
`customHeaders`	`object`	Object with headers in the form of key/value pairs. If `addCustomHeaders` is set to `true`, all headers defined here will be added to all requests sent to the io.Manager Server.
`disablePeriodicChangeDetection`	`boolean`	If `true`, will disable the internal change detection mechanism. Set to `true` if the data fields defined in the `AuthProvider` object will only change from within the React execution context or during the execution of any of the methods defined in `AuthProvider`. Valid only for custom authentication implementations. Defaults to `false`.
`error`	`any`	Required. Indicates an unrecoverable error in the authorization flow (e.g., misconfiguration). The error will be shown to the user.
`getAccessToken()`	`function`	Required. Function with the following signature: `() => Promise<string \| undefined>`. If `addTokenToRequest` is set to `true`, this method will be invoked for every request sent to io.Manager and its return value will be set as a bearer token in the `Authorization: Bearer <token>` header.
`getUserInfo()`	`function`	Required. Function with the following signature: `() => Promise<{ id?: string } \| undefined>`. If `addUsernameToRequest` is set to `true`, this method will be invoked for every request sent to io.Manager and its return value will be used to set the value of the `user` header.
`isAuthenticated`	`boolean`	Required. If `true`, indicates that the user has been authenticated. If `false`, the authentication flow will be initiated by calling the `loginIfNeeded()` method.
`isLoading`	`boolean`	Required. If `true`, indicates that the authentication process is in progress and the app will display a loading screen.
`logOut()`	`function`	Function with the following signature: `() => Promise<void>`. If provided, will be invoked when the user attempts to log out. If not provided, a "Log out" button won't be available in the app.
`loginIfNeeded()`	`function`	Required. Function with the following signature: `() => Promise<void>`. Initial login logic that will be initiated if `isAuthenticated` is set to `false`.
`onUnauthorizedResponse()`	`function`	Function with the following signature: `(error: AxiosError) => Promise<void>`. If provided, will be invoked when requests to the io.Manager Server fail with a `401 Unauthorized` or `403 Forbidden` HTTP response error.

BasicAuthOptions

Configuration for Basic authentication.

Property	Type	Description
`useSessionCookie`	`boolean`	If `true` (default), io.Manager will use a signed JWT stored in a session cookie to manage the Admin UI user sessions. Set to `false` to disable session cookies.

Interceptor

Custom Axios interceptor for handling responses from the io.Manager Server.

ℹ️ For more details, see the Axios official documentation.

Property	Type	Description
`response`	`object`	Required. Response interceptor configuration.

The response object has the following properties:

Property	Type	Description
`onError()`	`function`	Function with the following signature: `(error: any) => void`. Callback that will be invoked when a request to the io.Manager Server fails.
`onSuccess()`	`function`	Function with the following signature: `(data: ResponseData) => void`. Callback that will be invoked when a request to the io.Manager Server succeeds.

OktaAuthOptions

Configuration for Okta authentication.

Property	Type	Description
`clientId`	`string`	The client ID found in the app settings of the Okta "Applications" page.
`issuer`	`string`	Required. URL pointing to the issuer to be used for validation of access tokens.
`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.
`scopes`	`string[]`	Scopes for the requests sent to the Okta authorization server.

ℹ️ For more details on the OktaAuthOptions object and its properties, see the documentation in the @okta/okta-auth-js GitHub repo.

Environment Variables

The io.Manager Admin UI is a React app built with Vite that can be configured via environment variables. In development mode, you can use a .env file from which the Admin UI will attempt to read the provided environment variables.

⚠️ Note that using environment variables is the only supported option for configuring the io.Manager Admin UI when using Docker images to deploy io.Manager (e.g., when using the basic scenario via the template repository approach).

The following example demonstrates basic configuration for the io.Manager Admin UI via environment variables:

# URL of the io.Manager Server to which the Admin UI will connect.
REACT_APP_SERVER_BASE=http://localhost:4242/api
# Base path that will be added to the URL of the Admin UI.
REACT_APP_BASE=/admin-ui

# Authentication method.
REACT_APP_AUTH=none
# License for AG Grid.
REACT_APP_AG_GRID_LICENCE_KEY=my-ag-grid-license-key

Environment Variable	Description
`REACT_APP_AG_GRID_LICENCE_KEY`	AG Grid license key. If provided, will enable AG Grid Enterprise features in the Admin UI. For more details, see the AG Grid official site. Available since io.Manager* Admin UI 2.0.4*.
`REACT_APP_AUTH`	Authentication method for the Admin UI. Use one of the supported authentication methods: `none`, `basic`, `auth0`, or `okta`. Defaults to `basic`.
`REACT_APP_AUTH_USER`	Username to be used for all logins in the Admin UI when `REACT_APP_AUTH` is set to `none`. If the Admin UI is accessed from io.Connect Desktop, the local machine username will be used instead. Defaults to `admin`.
`REACT_APP_AUTH0_AUDIENCE`	URL pointing to the resource that will consume the access token.
`REACT_APP_AUTH0_CACHE_LOCALSTORAGE`	Cache location for the access tokens. Set to `true` to store the access tokens in local storage instead of in-memory.
`REACT_APP_AUTH0_CLIENT_ID`	The client ID found in the app settings of the Auth0 "Applications" page. Required when using Auth0 authentication.
`REACT_APP_AUTH0_DOMAIN`	URL pointing to your Auth0 account domain. Required when using Auth0 authentication.
`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.
`REACT_APP_AUTH0_USE_REFRESH_TOKENS`	If `true`, will enable refresh token rotation.
`REACT_APP_BASE`	Base path that will be added to the Admin UI origin. If you set this to `/admin-ui`, the Admin UI will be served at `<origin>/admin-ui` (e.g., `http://localhost:3000/admin-ui`). Defaults to `""`.
`REACT_APP_BASIC_USE_SESSION_COOKIE`	If `true` (default), io.Manager will use a signed JWT stored in a session cookie to manage the Admin UI user sessions. Set to `false` to disable session cookies.
`REACT_APP_LOGOUT_URL`	Absolute URL of the Admin UI logout page (e.g., `http://localhost:3000/admin-ui/logout`). Defaults to `<origin>/<REACT_APP_BASE>/logout`.
`REACT_APP_OKTA_CLIENT_ID`	The client ID found in the app settings of the Okta "Applications" page.
`REACT_APP_OKTA_ISSUER`	URL pointing to the issuer to be used for validation of access tokens. Required when using Okta authentication.
`REACT_APP_OKTA_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.
`REACT_APP_OKTA_USE_REFRESH_TOKEN`	If `true`, will set the scopes for the requests sent to the Okta authorization server to `["openid", "email", "profile", "offline_access"]`.
`REACT_APP_SERVER_BASE`	URL of the io.Manager Server to which the Admin UI will connect. Defaults to `http://localhost:4356/api`.

Docker Image

The io.Manager Admin UI can be deployed via the manager-admin-ui Docker image (e.g., when using the basic scenario via the template repository approach). The manager-admin-ui Docker image can be configured via environment variables.

The following example demonstrates providing settings for the manager-admin-ui Docker image:

# Port for the internal web server that provides the Admin UI.
ADMIN_UI_PORT=81

# Health check mode for the `manager-admin-ui` Docker image.
DOCKER_HEALTHCHECK_MODE=none

The following environment variables are available for configuring the manager-admin-ui Docker image:

Environment Variable	Description
`ADMIN_UI_PORT`	Defines the port on which the web server listens internally. Defaults to `80`.
`DOCKER_HEALTHCHECK_MODE`	Health check mode for the Docker image. Set to `http-connectivity` to check whether the static file server responds to requests. Set to `none` to disable the health check handler and instruct it to always report a healthy status. Defaults to `http-connectivity`.

io.Manager Documentation

Configuration