UGAIF
136 lines
6.5 KiB
Markdown
136 lines
6.5 KiB
Markdown
### 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
|