device_manager/README.md

### Device Manager

Device Manager is a device registration and access management portal for laboratory, research, and institutional networks. It enables users to register and manage devices, supports RADIUS-based authentication workflows, and facilitates secure network access through WPA3-Enterprise authorization policies and credential management.

### FreeRADIUS module

Device Manager includes FreeRADIUS integration via an `rlm_python` bridge. FreeRADIUS stays responsible for EAP/password authentication; the module evaluates registered device identity, records the RADIUS request, creates an auditable access decision, and returns VLAN, reply, and verifier control attributes for allow, quarantine, or reject outcomes.

#### Deployment Options

**Option 1: Standalone RADIUS Client (Recommended for Separate Servers)**

For FreeRADIUS servers on a separate host from your Frappe installation, use the standalone RADIUS client from the `radius_client/` directory. This module only requires Python 3.10+ and makes API calls to your Frappe server - no Frappe installation needed locally.

See [radius_client/README.md](radius_client/README.md) for complete installation and configuration instructions.

Quick setup:
```bash
# Copy standalone module to FreeRADIUS
sudo cp radius_client/device_manager_radius.py /etc/freeradius/3.0/mods-config/python3/

# Configure environment (see radius_client/README.md for details)
# Set DEVICE_MANAGER_FRAPPE_URL, DEVICE_MANAGER_API_KEY, DEVICE_MANAGER_API_SECRET
```

**Option 2: Local Mode (Same Host as Frappe)**

For FreeRADIUS running on the same host as the Frappe bench, use the integrated `device_manager.freeradius` module:

```bash
DEVICE_MANAGER_BENCH_PATH=/home/frappe/frappe-bench
DEVICE_MANAGER_SITE=your-site-name
```

Configure FreeRADIUS:
```text
python3 device_manager {
    module = device_manager.freeradius
    instantiate = ${.module}
    authorize = ${.module}
    post_auth = ${.module}
}
```

**Option 3: Remote Mode (Full App Installed)**

If device_manager is installed on the RADIUS server but Frappe runs elsewhere:

```bash
DEVICE_MANAGER_FRAPPE_URL=https://device-manager.example.edu
DEVICE_MANAGER_API_KEY=api-key
DEVICE_MANAGER_API_SECRET=api-secret
DEVICE_MANAGER_CACHE_PATH=/var/lib/freeradius/device_manager_verifier_cache.sqlite3
DEVICE_MANAGER_HTTP_TIMEOUT=2.5
```

Configure FreeRADIUS:
```text
python3 device_manager {
    module = device_manager.freeradius
    instantiate = ${.module}
    authorize = ${.module}
    post_auth = ${.module}
}
```

#### Credential Caching

All deployment modes support offline credential caching using a local SQLite database. The cache stores FreeRADIUS control attributes such as `SSHA-Password`; it does not store plaintext passwords. Frappe stores only verifier material in `Stored Credential Verifier`, not plaintext device passwords. When Frappe is unreachable, the module can continue authorizing previously cached long-lived IoT credentials.

### Credential provisioning

Approved devices can be owned by a Frappe `User`. A System Manager or the owning user can provision RADIUS credentials in two ways:

- Device credential: a username/password or generated deployment key attached to one `DM Device`. This is the preferred mode for long-lived IoT and lab equipment because the offline FreeRADIUS cache can safely bind the verifier to a specific device decision.
- Owner shared credential: a username/password or generated deployment key attached to the owning Frappe user through `DM Radius Credential`. This can be used across devices owned by that user, while the device MAC still drives authorization, VLAN selection, and audit records.

Provisioning actions hash the submitted password/key immediately using an SSHA verifier for FreeRADIUS. Generated deployment keys are returned once for installation on the device and are never stored in plaintext.

#### FreeRADIUS Integration Details

For detailed FreeRADIUS configuration, see:
- [radius_client/CONFIGURATION.md](radius_client/CONFIGURATION.md) - Complete FreeRADIUS setup guide
- [radius_client/README.md](radius_client/README.md) - Standalone client installation

The module reads common request attributes such as `Calling-Station-Id`, `User-Name`, `NAS-Identifier`, `NAS-IP-Address`, and SSID attributes, then writes `DM Radius Auth Event`, `DM Access Decision`, and `DM Device Audit Event` records when Frappe is reachable.

### UniFi live network views

Device Manager can expose UniFi controller state through read-only Virtual DocTypes:

- `DM UniFi Client`
- `DM UniFi Network Device`
- `DM UniFi Network`

Configure `DM UniFi Settings` with the UniFi OS or self-hosted Network Controller URL, site ID, TLS behavior, and either an API token or a least-privilege local UniFi account. The virtual DocTypes call UniFi live and do not persist controller state in the Frappe database. This is intended for operator visibility and cross-checking Device Manager records against current network state while keeping UniFi as the source of truth for volatile client/AP/network telemetry.

`DM UniFi Settings` also provides operator actions for the core workflows:

- Sync UniFi networks into durable `DM Network Segment` mappings.
- Reconcile registered devices against live UniFi clients and update current IP, SSID, client ID, and network segment.
- Import unmatched UniFi clients as authorized `DM Device` records, because a client already visible in UniFi is an observed network asset rather than a self-service registration request.
- Convert older UniFi-created `DM Device Registration` records into `DM Device` records while preserving the registration as historical approval/audit context.

`DM Device Registration` remains the intake object for self-service requests and proposed device onboarding before a device is accepted into the managed inventory. UniFi telemetry should populate `DM Device` directly; operators can then change lifecycle status, authorization status, or network segment if the imported device needs quarantine or reassignment.

### Installation

You can install this app using the [bench](https://github.com/frappe/bench) CLI:

```bash
cd $PATH_TO_YOUR_BENCH
bench get-app $URL_OF_THIS_REPO --branch version-16
bench install-app device_manager
```

### Contributing

This app uses `pre-commit` for code formatting and linting. Please [install pre-commit](https://pre-commit.com/#installation) and enable it for this repository:

```bash
cd apps/device_manager
pre-commit install
```

Pre-commit is configured to use the following tools for checking and formatting your code:

- ruff
- eslint
- prettier
- pyupgrade

### License

apache-2.0