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 for complete installation and configuration instructions.

Quick setup:

# 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:

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

Configure FreeRADIUS:

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:

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:

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 - Complete FreeRADIUS setup guide
• 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 CLI:

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 and enable it for this repository:

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