# Authorization

LibreNMS uses a role-based access control (RBAC) system. Permissions are grouped into roles, and roles are
assigned to users to define what they can see and do within the application.

### 1. Introduction to Authorization

Authorization determines what an authenticated user is allowed to do. In LibreNMS, this is handled through
a combination of functional permissions (via Roles) and resource-specific permissions (direct user assignments).

!!! warning
    Functional permissions are assigned to **Roles** and Roles are assigned to **Users**.
    **Individual functional permissions cannot be assigned directly to users.**

### 2. Roles

Roles are collections of permissions that define a user's level of access.

#### Built-in Roles:
*   `admin`: Full access to all features and resources (Global Read/Write).
*   `global-read`: Read-only access to all devices and data (Global Read). This role is assigned all `viewAny` permissions.
*   `user`: Limited access; requires specific resource permissions (devices, ports, bills) to see data.

#### Custom Roles:

Users can create custom roles to define specific sets of functional permissions.
These can be managed via the Web UI under **Settings (cog icon) -> Manage Users -> Roles**.

![Roles Management Screen](../img/webui-roles-management.png)

Custom roles allow for fine-tuned access. Unlike built-in roles, they can be configured with any combination of
functional permissions available in the system. For example, you can create a role that only allows viewing
event logs and nothing else.

### 3. Permissions

Functional permissions control access to specific parts of the application or actions.

#### Global Permissions:
These permissions define what a user can do at a high level. Examples include:
*   `device.create`: Permission to add new devices.
*   `alert.viewAny`: Permission to view the list of alerts.
*   `settings.update`: Permission to modify global settings.

#### Permission Groups:
Permissions are organized into groups such as `device`, `port`, `bill`, `alert`, `user`, and `settings`.

### 4. Resource-Specific Permissions (Granular Access)

LibreNMS provides granular, resource-specific access control for users who lack viewAny functional permissions.

#### The `viewAny` Permission and Fallback

Functional permissions like `device.viewAny`, `port.viewAny`, and `bill.viewAny` determine if a user can see
ALL resources of that type.

*   If a user **has** `device.viewAny`, they see all devices.
*   If a user **lacks** `device.viewAny`, the system uses the **granular
    permissions**. The user then sees only their own devices. These
    devices come from a direct assignment or from a static device group.

Most other items in the system (sensors, services, health data, alerts for a specific device) do not have their
own separate granular permissions. Instead, access to these items **falls back to the device or port permissions**.
If you have access to a device, you generally have access to its sub-resources.

#### Interaction Between Functional and Resource Permissions

A common point of confusion is the interaction between functional permissions, for example `routing.viewAny`,
and resource-specific permissions, for example device access.

Even if a user is granted access to a specific device, they still require the corresponding **functional
permission** to access certain modules or menu items for that device.

**Example: Routing**
The user has access to Router-01. The Routing menu still needs
`routing.viewAny` or `routing.view` in the role of the user.

This pattern applies to several other modules, including:
*   **Switching (VLANs):** Requires `vlan.viewAny`.
*   **Services:** Requires `service.view`.
*   **Health Data (Sensors):** While viewing basic health data typically falls back to device access,
    the management of sensors, for example an edit of a threshold or a label, needs specific functional
    permissions such as `sensor.update` or `wireless-sensor.update`.

#### Device Permissions:
Access to individual devices is granted to users directly. When a user is granted access to a device,
they can see all data related to that device, including its ports, sensors, and services (provided they
also have the required functional permissions for those modules).

#### Port Permissions:

Access can be granted to individual ports. Note that if a user already has access to the parent device,
they also get access to all its ports.

**Port-only Access:**
A user with access only to specific ports does **not** see the parent
device in the main Devices list or in most global views. That user sees
only their own ports in the Ports list
and in specific port-related views. This is useful for providing customers access to only their specific
interfaces without exposing the entire device configuration or other customers' ports.

#### Bill Permissions:
Visibility of billing data is restricted to specific users through bill-level permissions. If a user
lacks `bill.viewAny`, that user sees only their own bills.

#### Device Group Permissions:
Access can be granted to all devices within a specific **Static Device Group**.
!!! note
    Only **static** device groups can be used for permissions. Dynamic device groups do not support
    permission assignment.

### 5. Managing Authorization

#### Quick Reference: UI Paths

| Task | Web UI Path |
|---|---|
| Create/Edit Roles | **Settings (cog icon) -> Manage Users -> Roles (button)** |
| Assign Role to User | **Settings (cog icon) -> Manage Users -> Edit (pencil icon)** |
| Manage Resource Access | **Settings (cog icon) -> Manage Users -> Manage Access (tasks icon)** |

The **Manage Access** screen is the primary location for assigning specific Devices, Ports, Bills, and Static Groups to a user.

![Edit User Permissions](../img/webui-user-edit-permissions.png)

#### Command Line (CLI):
You can use the `./lnms` command-line tool for some user management tasks:
*   `./lnms user:add`: Create a new user and assign a role.

### 6. Common Scenarios & Examples

#### Scenario: NOC Operator
Goal: Allow monitoring of all devices and alerts, but prevent configuration changes.

1.  **Create Role:** Create a noc-operator role and assign the following permissions: `device.viewAny`,
    `port.viewAny`, `alert.viewAny`, `eventlog.viewAny`, and `device-log.viewAny`.
2.  **Assign Role:** Assign the `noc-operator` role to the user.
3.  **Resource Access:** Since they have `device.viewAny`, they automatically see all devices. No additional
    resource assignments are needed.

#### Scenario: Customer with Specific Access
Goal: Allow a customer to see only their devices and specific ports.

1.  **Assign Role:** Assign the built-in `user` role to the customer. (This role has no `viewAny` permissions).
2.  **Assign Devices:** Go to **Manage Access** for that user and add the specific devices they own.
3.  **Assign Ports:** Go to **Manage Access** for that user and add specific ports on other devices, for example their uplink port
    on a shared switch).
4.  **Result:** the customer sees all their own devices. They also see
    only their own ports from
    other devices.

#### Scenario: Billing Manager
Goal: Allow access to billing data and nothing else.

1.  **Create Role:** Create a `billing-manager` role and assign `bill.viewAny` and `bill.update`.
2.  **Assign Role:** Assign the `billing-manager` role to the user.
3.  **Resource Access:** Since they have `bill.viewAny`, they see all bills. If you want them to see only specific bills
    instead, omit `bill.viewAny` and assign `bill.view` to the role, then assign individual bills in **Manage Access**.

---
!!! warning
    The `admin` role bypasses all granular checks and has full access to the entire system. Assign this role only to trusted administrators.
