# Auth0

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

## Overview

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

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

## 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](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 Auth0 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 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 access token. |
| `API_AUTH_AUTH0_ISSUER` | URL pointing to the issuer to be used for validation of access tokens. Unnecessary if `API_AUTH_AUTH0_ISSUER_BASE_URL` is provided. |
| `API_AUTH_AUTH0_ISSUER_BASE_URL` | Base URL of the issuer to be used for validation of access tokens. Unnecessary if `API_AUTH_AUTH0_ISSUER` and `API_AUTH_AUTH0_JWKSURI` are provided. *Available since **io.Manager** Server 1.7.* |
| `API_AUTH_AUTH0_JWKSURI` | URL pointing to a JSON Web Key Set. Unnecessary if `API_AUTH_AUTH0_ISSUER_BASE_URL` is provided. |
| `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 `auth0`. |

> ⚠️ *Note that it's required to provide either `API_AUTH_AUTH0_ISSUER_BASE_URL` or `API_AUTH_AUTH0_ISSUER` and `API_AUTH_AUTH0_JWKSURI` together.*

Example configuration:

```cmd
API_AUTH_METHOD=auth0
API_AUTH_AUTH0_AUDIENCE=https://example.com
API_AUTH_AUTH0_ISSUER_BASE_URL=https://example.auth0.com
API_AUTH_EXCLUSIVE_USERS=["admin"]
```

> ℹ️ *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 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_auth0`, `auth_exclusive_users`, and `token` properties to provide additional settings for the Auth0 authentication:

| Property | Type | Description|
|----------|------|------------|
| `auth_auth0` | `object` | **Required.** Settings for the Auth0 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 `"auth0"`. |

The `auth_auth0` object has the following properties:

| Property | Type | Description|
|----------|------|------------|
| `audience` | `string` | URL pointing to the resource that will consume the access token. |
| `issuer` | `string` | URL pointing to the issuer to be used for validation of access tokens. Unnecessary if `issuerBaseURL` is provided. |
| `issuerBaseURL` | `string` | Base URL of the issuer to be used for validation of access tokens. Unnecessary if `issuer` and `jwksUri` are provided. |
| `jwksUri` | `string` | URL pointing to a JSON Web Key Set. Unnecessary if `issuerBaseURL` is provided. |
| `tokenSigningAlg` | `string` | Algorithm for signing the access tokens. |

> ⚠️ *Note that it's required to provide either only `issuerBaseURL` or `issuer` and `jwksUri` together.*

Example configuration:

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

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

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 Auth0 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 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 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` | **Required.** The client ID found in the app settings of the Auth0 "Applications" page. |
| `REACT_APP_AUTH0_DOMAIN` | **Required.** 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. |
| `REACT_APP_AUTH0_USE_REFRESH_TOKENS` | If `true`, will enable refresh token rotation. |

Example configuration:

```cmd
REACT_APP_AUTH=auth0
REACT_APP_AUTH0_AUDIENCE=https://example.com
REACT_APP_AUTH0_CLIENT_ID=clientId
REACT_APP_AUTH0_DOMAIN=https://example.auth0.com
```

> ℹ️ *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 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|
|----------|------|------------|
| `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. |
| `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:

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

> ℹ️ *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 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](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 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 to 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.*

> ⚠️ *Note that you must set the `"keepAlive"` property of the `"options"` object to `true`. The Admin UI uses the login window to silently refresh the Auth0 access token. If `"keepAlive"` isn't set to `true`, **io.Connect Desktop** will close the window after sign-in and the bearer token used for requests to **io.Manager** will become stale once it reaches its `"exp"` claim, after which each request to **io.Manager** will return an HTTP 401 status code.*

Example configuration:

```json
{
    "ssoAuth": {
        "authController": "sso",
        "options": {
            "url": "http://localhost:3000/gd",
            "keepAlive": true,
            "window": {
                "width": 540,
                "height": 660,
                "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 Auth0 authentication:

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

// Callback that will retrieve a valid Auth0 access token
// and add it to the headers of every request sent to io.Manager.
const getHeaders = async () => {
    // Your custom internal logic for refreshing and retrieving the access token.
    const token = await getAccessToken();

    const extraHeaders = {
        Authorization: `Bearer ${token}`
    };

    // The returned headers will be merged with the existing ones.
    return extraHeaders;
};

const config = {
    licenseKey: "my-license-key",
    manager: {
        // URL pointing to io.Manager.
        url: "https://my-io-manager.com:4242/api",
        // Providing a callback for supplying an Auth0 access token.
        getHeaders,
        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.*