fix: separate radius module to support separate deployment

2026-06-17 19:04:32 +00:00
parent 289615b3b2
commit b093a80630
50 changed files with 3821 additions and 69 deletions
@@ -0,0 +1,116 @@
+# Device Manager RADIUS Client
+
+Standalone FreeRADIUS module for remote Device Manager integration.
+
+This package provides a minimal RADIUS client that authenticates against a remote Frappe Device Manager instance via API calls. Use this when your FreeRADIUS server is on a separate host from your Frappe installation.
+
+## Installation
+
+### Option 1: Install as Python package
+
+```bash
+pip install -e /path/to/radius_client
+```
+
+Then configure FreeRADIUS to use the module:
+
+```text
+python3 device_manager_radius {
+    module = device_manager_radius
+    instantiate = ${.module}
+    authorize = ${.module}
+    post_auth = ${.module}
+}
+```
+
+### Option 2: Direct file deployment
+
+Copy `device_manager_radius.py` to your FreeRADIUS Python module path (e.g., `/etc/freeradius/3.0/mods-config/python3/`):
+
+```bash
+sudo cp device_manager_radius.py /etc/freeradius/3.0/mods-config/python3/
+```
+
+Then configure FreeRADIUS:
+
+```text
+python3 device_manager_radius {
+    module = device_manager_radius
+    instantiate = ${.module}
+    authorize = ${.module}
+    post_auth = ${.module}
+}
+```
+
+## Configuration
+
+Set these environment variables (in `/etc/default/freeradius` or systemd override):
+
+```bash
+# Required: Frappe server URL and API credentials
+DEVICE_MANAGER_FRAPPE_URL=https://device-manager.example.edu
+DEVICE_MANAGER_API_KEY=your-api-key
+DEVICE_MANAGER_API_SECRET=your-api-secret
+
+# Optional: Cache configuration
+DEVICE_MANAGER_CACHE_PATH=/var/lib/freeradius/device_manager_verifier_cache.sqlite3
+DEVICE_MANAGER_HTTP_TIMEOUT=2.5
+DEVICE_MANAGER_CACHE_MAX_STALE_SECONDS=0
+
+# Optional: Enable post-auth evaluation
+DEVICE_MANAGER_POST_AUTH_EVALUATE=0
+```
+
+### Generating API credentials
+
+On your Frappe server, create an API key/secret pair:
+
+1. Navigate to **API Secret** in Device Manager settings or create a System User
+2. Generate an API Key and API Secret
+3. Grant the user permissions for Device Manager doctypes
+
+## FreeRADIUS configuration
+
+Add to your FreeRADIUS virtual server:
+
+```text
+authorize {
+    # Other modules...
+    device_manager_radius
+}
+
+post-auth {
+    device_manager_radius
+}
+```
+
+## Features
+
+- **Remote authentication**: Makes API calls to Frappe Device Manager for real-time decisions
+- **Offline credential caching**: Caches RADIUS verifiers (SSHA-Password) for long-lived IoT devices
+- **Automatic failover**: Falls back to cached credentials when Frappe is unreachable
+- **VLAN assignment**: Returns VLAN and reply attributes based on device policy
+- **Quarantine support**: Routes unknown devices to quarantine VLAN
+
+## Troubleshooting
+
+Check FreeRADIUS logs:
+
+```bash
+sudo tail -f /var/log/freeradius/radius.log
+```
+
+Test the module directly:
+
+```bash
+sudo freeradius -X
+```
+
+Verify API connectivity:
+
+```bash
+curl -X POST "https://device-manager.example.edu/api/method/device_manager.api.radius_authorize" \
+  -H "Authorization: token your-api-key:your-api-secret" \
+  -d "calling_station_id=00:11:22:33:44:55" \
+  -d "username=testuser"
+```