# Authorization

Source: https://docs.interop.io/manager/authorization/index.html

## Overview

Available since io.Manager 4.0

**io.Manager** uses a granular permission-based authorization system. Accessing or acting on a resource on the **io.Manager** Server requires the permission group that protects it, which a user receives through the groups they are assigned.

> ⚠️ *Note that, for backwards compatibility, the following default groups include the `GLUE42_SERVER_ADMIN` group, which grants all granular permissions.*

## Permission Groups

The following granular permission groups are available:

| Permission Group | Description |
| ---- | ----------- |
| `IO_MANAGER:APPS:READ` | Read and list app definitions. |
| `IO_MANAGER:APPS:WRITE` | Create, update, and delete apps, and manage which groups can access them. |
| `IO_MANAGER:AUDITS:READ` | Read and list audit log entries. |
| `IO_MANAGER:AUDITS:WRITE` | Delete audit log entries. |
| `IO_MANAGER:COMMANDS:READ` | Read and list commands. |
| `IO_MANAGER:COMMANDS:WRITE` | Create and delete commands. |
| `IO_MANAGER:CRASHES:READ` | Read and list crash reports. |
| `IO_MANAGER:CRASHES:WRITE` | Update and delete crash reports. |
| `IO_MANAGER:FEEDBACKS:READ` | Read and list feedback entries and attachments. |
| `IO_MANAGER:FEEDBACKS:WRITE` | Update and delete feedback entries. |
| `IO_MANAGER:GROUPS:READ` | Read and list groups. |
| `IO_MANAGER:GROUPS:WRITE` | Create, update, and delete groups. |
| `IO_MANAGER:LAYOUTS:READ` | Read and list Layout definitions. |
| `IO_MANAGER:LAYOUTS:WRITE` | Create, update, and delete Layouts. |
| `IO_MANAGER:MACHINES:READ` | Read and list machines. |
| `IO_MANAGER:PREFS:READ` | Read and list app preferences. |
| `IO_MANAGER:PREFS:WRITE` | Create, update, and delete app preferences. |
| `IO_MANAGER:SCHEMAS:READ` | Validate objects against entity schemas. |
| `IO_MANAGER:SESSIONS:READ` | Read and list sessions. |
| `IO_MANAGER:SESSIONS:WRITE` | Delete and clean sessions. |
| `IO_MANAGER:SYSTEM:READ` | Read system info, logs, and data summary. |
| `IO_MANAGER:SYSTEM_CONFIG:READ` | Read system configuration entries. |
| `IO_MANAGER:SYSTEM_CONFIG:WRITE` | Create, update, and delete system configuration entries. |
| `IO_MANAGER:USERS:READ` | Read and list users, their apps, Layouts, groups, and machines. |
| `IO_MANAGER:USERS:WRITE` | Create, update, and delete users, and manage user apps, Layouts, and groups. |

## Default Groups

The following table describes the default (built-in) groups that come with the **io.Manager** Server:

| Group | Description | Expands To |
| ----- | ----------- | --------------- |
| `GLUE42_SERVER_ADMIN` | Unrestricted access to the Admin UI and to every protected endpoint of the **io.Manager** Server. | Every group in [Permission Groups](#permission_groups) |
| `IO_MANAGER:APPS:READ` | Read and list app definitions. | - |
| `IO_MANAGER:APPS:WRITE` | Create, update, and delete apps, and manage which groups can access them. | `IO_MANAGER:APPS:READ`, `IO_MANAGER:SCHEMAS:READ` |
| `IO_MANAGER:AUDITS:READ` | Read and list audit log entries. | - |
| `IO_MANAGER:AUDITS:WRITE` | Delete audit log entries. | `IO_MANAGER:AUDITS:READ` |
| `IO_MANAGER:COMMANDS:READ` | Read and list commands. | - |
| `IO_MANAGER:COMMANDS:WRITE` | Create and delete commands. | `IO_MANAGER:COMMANDS:READ` |
| `IO_MANAGER:CRASHES:READ` | Read and list crash reports. | - |
| `IO_MANAGER:CRASHES:WRITE` | Update and delete crash reports. | `IO_MANAGER:CRASHES:READ` |
| `IO_MANAGER:FEEDBACKS:READ` | Read and list feedback entries and attachments. | - |
| `IO_MANAGER:FEEDBACKS:WRITE` | Update and delete feedback entries. | `IO_MANAGER:FEEDBACKS:READ` |
| `IO_MANAGER:GROUPS:READ` | Read and list groups. | - |
| `IO_MANAGER:GROUPS:WRITE` | Create, update, and delete groups. | `IO_MANAGER:GROUPS:READ` |
| `IO_MANAGER:LAYOUTS:READ` | Read and list Layout definitions. | - |
| `IO_MANAGER:LAYOUTS:WRITE` | Create, update, and delete Layouts. | `IO_MANAGER:LAYOUTS:READ`, `IO_MANAGER:SCHEMAS:READ` |
| `IO_MANAGER:MACHINES:READ` | Read and list machines. | - |
| `IO_MANAGER:PREFS:READ` | Read and list app preferences. | - |
| `IO_MANAGER:PREFS:WRITE` | Create, update, and delete app preferences. | `IO_MANAGER:PREFS:READ` |
| `IO_MANAGER:SCHEMAS:READ` | Validate objects against entity schemas. | - |
| `IO_MANAGER:SESSIONS:READ` | Read and list sessions. | - |
| `IO_MANAGER:SESSIONS:WRITE` | Delete and clean sessions. | `IO_MANAGER:SESSIONS:READ` |
| `IO_MANAGER:SYSTEM:READ` | Read system info, logs, and data summary. | - |
| `IO_MANAGER:SYSTEM_CONFIG:READ` | Read system configuration entries. | - |
| `IO_MANAGER:SYSTEM_CONFIG:WRITE` | Create, update, and delete system configuration entries. | `IO_MANAGER:SYSTEM_CONFIG:READ` |
| `IO_MANAGER:USERS:READ` | Read and list users, their apps, Layouts, groups, and machines. | - |
| `IO_MANAGER:USERS:WRITE` | Create, update, and delete users, and manage user apps, Layouts, and groups. | `IO_MANAGER:USERS:READ` |

- Each write group automatically includes its corresponding read group - for example, a user assigned to the `IO_MANAGER:APPS:WRITE` group will also have the `IO_MANAGER:APPS:READ` permission.
- `IO_MANAGER:APPS:WRITE` and `IO_MANAGER:LAYOUTS:WRITE` additionally include `IO_MANAGER:SCHEMAS:READ`, granting read access to the entity schemas against which apps and Layouts are validated.

> ⚠️ *Note that the default groups listed above are built-in and take precedence over any custom groups defined in `auth_extra_groups`, which in turn take precedence over the groups stored by the **io.Manager** Server.*

## Additional Groups

You can define additional groups using the `auth_extra_groups` top-level key in the configuration object for initializing the **io.Manager** Server. It accepts an array of [`Group`](https://docs.interop.io/manager/configuration/server/index.md#configuration_object-group) objects.

The following example demonstrates how to define additional groups:

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

const config = {
    auth_extra_groups: [
        {
            name: "apps-manager",
            description: "Can read and write apps.",
            expandsTo: ["IO_MANAGER:APPS:READ", "IO_MANAGER:APPS:WRITE", "IO_MANAGER:SCHEMAS:READ"]
        },
        {
            name: "apps-layouts-manager",
            description: "Can read and write apps and layouts.",
            expandsTo: ["apps-manager", "IO_MANAGER:LAYOUTS:READ", "IO_MANAGER:LAYOUTS:WRITE"]
        },
        {
            name: "read-only",
            description: "Can read all resources.",
            expandsTo: ["IO_MANAGER:APPS:READ", "IO_MANAGER:AUDITS:READ", "IO_MANAGER:COMMANDS:READ", "IO_MANAGER:CRASHES:READ", "IO_MANAGER:FEEDBACKS:READ", "IO_MANAGER:GROUPS:READ", "IO_MANAGER:LAYOUTS:READ", "IO_MANAGER:MACHINES:READ", "IO_MANAGER:PREFS:READ", "IO_MANAGER:SCHEMAS:READ", "IO_MANAGER:SESSIONS:READ", "IO_MANAGER:SYSTEM:READ", "IO_MANAGER:SYSTEM_CONFIG:READ", "IO_MANAGER:USERS:READ"]
        }
    ]
};

const server = await start(config);
```

You can also define additional groups via the `API_AUTH_EXTRA_GROUPS` environment variable, which accepts a JSON-encoded array with the same shape as `auth_extra_groups`:

```cmd
API_AUTH_EXTRA_GROUPS=[{"name": "apps-manager", "description": "Can read and write apps.", "expandsTo": ["IO_MANAGER:APPS:READ", "IO_MANAGER:APPS:WRITE", "IO_MANAGER:SCHEMAS:READ"]}]
```