fix: separate radius module to support separate deployment
This commit is contained in:
UGAIF
@@ -4,17 +4,35 @@ Device Manager is a device registration and access management portal for laborat
|
||||
|
||||
### FreeRADIUS module
|
||||
|
||||
Device Manager includes an `rlm_python` bridge at `device_manager.freeradius`. FreeRADIUS stays responsible for EAP/password authentication; this module evaluates registered device identity, records the RADIUS request, creates an auditable access decision, and returns VLAN or reply attributes for allow, quarantine, or reject outcomes.
|
||||
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.
|
||||
|
||||
Set these environment variables for the FreeRADIUS service:
|
||||
#### 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
|
||||
```
|
||||
|
||||
Example `mods-available/python3` module stanza:
|
||||
|
||||
Configure FreeRADIUS:
|
||||
```text
|
||||
python3 device_manager {
|
||||
module = device_manager.freeradius
|
||||
@@ -24,19 +42,67 @@ python3 device_manager {
|
||||
}
|
||||
```
|
||||
|
||||
Then call the module from the relevant virtual server:
|
||||
**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
|
||||
authorize {
|
||||
device_manager
|
||||
}
|
||||
|
||||
post-auth {
|
||||
device_manager
|
||||
python3 device_manager {
|
||||
module = device_manager.freeradius
|
||||
instantiate = ${.module}
|
||||
authorize = ${.module}
|
||||
post_auth = ${.module}
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
#### 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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user