# Admin UI

Source: https://docs.interop.io/manager/configuration/admin-ui/index.html

## Overview

The following sections provide a comprehensive reference documentation of the available settings for configuring the **io.Manager** Admin UI via the [component properties](#component_properties) of the `<AdminUI />` React component exported by the [`@interopio/manager-admin-ui`](https://www.npmjs.com/package/@interopio/manager-admin-ui) library and via the respective [environment variables](#environment_variables), depending on your [deployment](https://docs.interop.io/manager/deployment/index.md) approach.

## Component Properties

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

```javascript
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, provided to you upon purchase of **io.Manager**. |
| `apiURL` | `string` | URL of the **io.Manager** Server to which the Admin UI will connect. Defaults to `"http://localhost:4356/api"`. |
| `auth` | `"none"` \| `"basic"` \| `"auth0"` \| `"okta"` \| `object` | Authentication method for the Admin UI. Use one of the supported authentication methods, or specify a [custom](https://docs.interop.io/manager/authentication/custom/index.md) authentication implementation by providing an [`AuthProvider`](#component_properties-authprovider) object. Defaults to `"basic"`. |
| `auth_auth0` | `object` | Configuration for [Auth0](https://docs.interop.io/manager/authentication/auth0/index.md) authentication. Accepts an [`Auth0ProviderOptions`](#component_properties-auth0provideroptions) object as a value. Valid only if the `auth` property is set to `"auth0"`. |
| `auth_basic` | `object` | Configuration for [Basic](https://docs.interop.io/manager/authentication/basic/index.md) authentication. Accepts a [`BasicAuthOptions`](#component_properties-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](https://docs.interop.io/manager/authentication/okta/index.md) authentication. Accepts an [`OktaAuthOptions`](#component_properties-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`](#component_properties-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](https://docs.interop.io/manager/authentication/auth0/index.md) 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](https://auth0.github.io/auth0-react/interfaces/Auth0ProviderOptions.html).*

### AuthProvider

[Custom](https://docs.interop.io/manager/authentication/custom/index.md) 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` | `Error` \| `undefined` | **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; email?: 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](https://docs.interop.io/manager/authentication/basic/index.md) 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](https://axios-http.com/docs/interceptors).*

| 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: unknown) => 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](https://docs.interop.io/manager/authentication/okta/index.md) 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`](https://github.com/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](https://github.com/InteropIO/manager-examples/tree/main/manager-template/1-basic) via the [template repository](https://docs.interop.io/manager/deployment/index.md#template_repository) approach).*

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

```ini
# 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, provided to you upon purchase of **io.Manager**. *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](https://github.com/InteropIO/manager-examples/tree/main/manager-template/1-basic) via the [template repository](https://docs.interop.io/manager/deployment/index.md#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:

```ini
# 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](https://docs.interop.io/manager/deployment/index.md#health_checks-docker_health_checks-iomanager_admin_ui) 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`. |