# Basic

Source: https://docs.interop.io/manager/authentication/basic/index.html

## Overview

When using Basic authentication, the **io.Manager** Server will use the "Basic" HTTP authentication scheme defined in [RFC 7617](https://datatracker.ietf.org/doc/html/rfc7617) 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.*

> ℹ️ *For a complete example of using Basic authentication in the **io.Manager** Server and Admin UI, see the [Basic Authentication](https://github.com/InteropIO/manager-examples/tree/main/auth-basic) example on GitHub.*

## Configuration

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](https://docs.interop.io/manager/deployment/index.md) 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](https://github.com/InteropIO/manager-examples/tree/main/manager-template/1-basic) from the [template repository](https://docs.interop.io/manager/deployment/index.md#template_repository) approach, you must set properly the necessary environment variables.

- If you are using the [NPM packages](https://docs.interop.io/manager/deployment/index.md#npm_packages) for deployment, or the [advanced deployment scenario](https://github.com/InteropIO/manager-examples/tree/main/manager-template/2-advanced) 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](https://docs.interop.io/manager/deployment/index.md) 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`:

| Environment Variable | Description |
|----------------------|-------------|
| `API_AUTH_EXCLUSIVE_USERS` | List of users that will be assigned to the `GLUE42_SERVER_ADMIN` group, which grants unrestricted access to the Admin UI and to every protected endpoint of the **io.Manager** Server. The users must already exist in the database. |
| `API_AUTH_METHOD` | **Required.** Type of the authentication mechanism. Must be set to `basic`. |
| `API_AUTH_METHOD_BASIC_SESSION_LIFETIME` | Interval in seconds at which the session will expire and the user will be logged out of the **io.Manager** Admin UI. Valid only if `API_AUTH_METHOD_BASIC_USE_SESSION_COOKIE` is set to `true` and the CORS options are configured properly via the `API_CORS_OPTIONS` environment variable. Defaults to `3600`. *Available since **io.Manager** Server 2.1.* |
| `API_AUTH_METHOD_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. If session cookies are enabled, it's required to specify CORS options via the `API_CORS_OPTIONS` environment variable. *Available since **io.Manager** Server 2.1.* |
| `API_AUTH_METHOD_BASIC_USERS` | List of predefined users that will be created in the database and will be assigned to the `GLUE42_SERVER_ADMIN` group, which grants unrestricted access to the Admin UI and to every protected endpoint of the **io.Manager** Server. Accepts an array of strings in the format `user-id:password`. |

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

```cmd
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"}
```

> ℹ️ *For details on all available environment variables for configuring the **io.Manager** Server, see the [Configuration > Server](https://docs.interop.io/manager/configuration/server/index.md#environment_variables) section.*

#### 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:

| Property | Type | Description|
|----------|------|------------|
| `auth_basic` | `object` | Settings for the Basic authentication mechanism. |
| `auth_exclusive_users` | `string[]` | List of users that will be assigned to the `GLUE42_SERVER_ADMIN` group, which grants unrestricted access to the Admin UI and to every protected endpoint of the **io.Manager** Server. The users must already exist in the database. |
| `auth_method` | `string` | **Required.** Type of the authentication mechanism. Must be set to `"basic"`. |

The `auth_basic` object has the following properties:

| Property | Type | Description|
|----------|------|------------|
| `predefinedUsers` | `string[]` | List of predefined users that will be created and added to the database and will be assigned to the `GLUE42_SERVER_ADMIN` group, which grants unrestricted access to the Admin UI and to every protected endpoint of the **io.Manager** Server. Accepts an array of strings in the format `user-id:password`. |
| `sessionLifetime` | `number` | Interval in seconds at which the session will expire and the user will be logged out of the **io.Manager** Admin UI. Valid only if `useSessionCookie` is set to `true` and the CORS options are configured properly via the `cors` property. Defaults to `3600`. *Available since **io.Manager** Server 2.1.* |
| `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. If session cookies are enabled, it's required to specify CORS options via the `cors` property. *Available since **io.Manager** Server 2.1.* |

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

```javascript
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);
```

> ℹ️ *For details on all available properties for configuring the **io.Manager** Server, see the [Configuration > Server](https://docs.interop.io/manager/configuration/server/index.md#configuration_object) section.*

### Admin UI

Every user can access the **io.Manager** [Admin UI](https://docs.interop.io/manager/overview/index.md#admin_ui); the operations available to them are determined by their [permission groups](https://docs.interop.io/manager/authorization/index.md). Users assigned to the `GLUE42_SERVER_ADMIN` group have unrestricted access. The exclusive users assigned to this group are defined in the **io.Manager** [Server configuration](#configuration-server); you can also assign it 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](https://docs.interop.io/manager/deployment/index.md) approach.

#### Environment Variables

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

```cmd
REACT_APP_AUTH=basic
```

> ℹ️ *For details on all available environment variables for configuring the **io.Manager** Admin UI, see the [Configuration > Admin UI](https://docs.interop.io/manager/configuration/admin-ui/index.md#environment_variables) section.*

#### Component Properties

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

```javascript
<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`:

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

> ℹ️ *For details on all available component properties for configuring the **io.Manager** Admin UI, see the [Configuration > Admin UI](https://docs.interop.io/manager/configuration/admin-ui/index.md#component_properties) section.*

### 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](https://docs.interop.io/desktop/developers/configuration/system/index.md) 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**:

```json
{
    "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:

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

> ℹ️ *For more configuration options for connecting to **io.Manager**, see the [Configuration > Platform](https://docs.interop.io/manager/configuration/platform/index.md#ioconnect_desktop) 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:

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

### io.Connect Browser

[Connecting](https://docs.interop.io/browser/capabilities/manager/index.md#setup) to **io.Manager** from an **io.Connect Browser** project requires modifying the configuration for initializing the [`@interopio/browser-platform`](https://www.npmjs.com/package/@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`](https://www.npmjs.com/package/@interopio/browser-platform) library. The following example demonstrates configuring the connection to **io.Manager** with Basic authentication:

```javascript
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](https://docs.interop.io/manager/configuration/platform/index.md#ioconnect_browser) section.*