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,223 @@
+# FreeRADIUS Configuration Examples
+
+## Module Configuration
+
+Create or update `/etc/freeradius/3.0/mods-available/python3`:
+
+```text
+python3 device_manager_radius {
+    # Module path - Python will import device_manager_radius.py
+    module = device_manager_radius
+    
+    # Call functions during FreeRADIUS lifecycle
+    instantiate = ${.module}
+    authorize = ${.module}
+    post_auth = ${.module}
+}
+```
+
+Enable the module:
+```bash
+sudo ln -s ../mods-available/python3 /etc/freeradius/3.0/mods-enabled/python3
+```
+
+## Virtual Server Configuration
+
+Add to `/etc/freeradius/3.0/sites-available/default` or your custom virtual server:
+
+```text
+server default {
+    authorize {
+        # Pre-process request
+        preprocess
+        
+        # Check for valid MAC address
+        filter_username
+        
+        # Device Manager authorization
+        device_manager_radius
+        
+        # If credentials are provided, validate them
+        eap {
+            ok = return
+        }
+    }
+    
+    authenticate {
+        # Handle EAP authentication
+        eap
+    }
+    
+    post-auth {
+        # Device Manager post-auth processing
+        device_manager_radius
+        
+        # Update client list
+        update {
+            &reply: += &session-state:
+        }
+        
+        Post-Auth-Type REJECT {
+            attr_filter.access_reject
+        }
+    }
+}
+```
+
+## Environment Variables
+
+### Systemd Service Override
+
+Create `/etc/systemd/system/freeradius.service.d/device-manager.conf`:
+
+```ini
+[Service]
+# Required: Frappe server URL and authentication
+Environment="DEVICE_MANAGER_FRAPPE_URL=https://device-manager.example.edu"
+Environment="DEVICE_MANAGER_API_KEY=your-api-key-here"
+Environment="DEVICE_MANAGER_API_SECRET=your-api-secret-here"
+
+# Optional: Cache configuration
+Environment="DEVICE_MANAGER_CACHE_PATH=/var/lib/freeradius/device_manager_verifier_cache.sqlite3"
+Environment="DEVICE_MANAGER_HTTP_TIMEOUT=2.5"
+Environment="DEVICE_MANAGER_CACHE_MAX_STALE_SECONDS=0"
+
+# Optional: Enable post-auth evaluation
+Environment="DEVICE_MANAGER_POST_AUTH_EVALUATE=0"
+```
+
+Reload systemd:
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart freeradius
+```
+
+### Alternative: /etc/default/freeradius
+
+Add to `/etc/default/freeradius`:
+
+```bash
+DEVICE_MANAGER_FRAPPE_URL=https://device-manager.example.edu
+DEVICE_MANAGER_API_KEY=your-api-key-here
+DEVICE_MANAGER_API_SECRET=your-api-secret-here
+DEVICE_MANAGER_CACHE_PATH=/var/lib/freeradius/device_manager_verifier_cache.sqlite3
+```
+
+## Testing
+
+### Test FreeRADIUS Configuration
+
+```bash
+sudo freeradius -X
+```
+
+Look for log messages like:
+```
+device_manager_radius: initialized remote Device Manager mode: https://device-manager.example.edu/api/method/device_manager.api.radius_authorize
+device_manager_radius: SQLite credential cache enabled for offline fallback
+```
+
+### Test Authentication
+
+Using `radtest`:
+```bash
+radtest testuser testpassword localhost 0 testing123
+```
+
+Using `eapol_test` for WPA-Enterprise:
+```bash
+eapol_test -c test.conf -a 127.0.0.1 -p 1812 -s testing123
+```
+
+Where `test.conf` contains:
+```text
+network={
+    ssid="test"
+    key_mgmt=WPA-EAP
+    eap=PEAP
+    identity="testuser"
+    password="testpassword"
+}
+```
+
+### Test API Connectivity
+
+Test the Frappe API endpoint directly:
+```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" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "calling_station_id=00:11:22:33:44:55" \
+  -d "username=testuser" \
+  -d "nas_identifier=test-ap"
+```
+
+Expected response:
+```json
+{
+  "message": {
+    "event": "AUTH-EVENT-001",
+    "decision": "DEC-001",
+    "device": "DEV-001",
+    "result": "Allow",
+    "reason": "Device approved for network access",
+    "network_segment": "SEG-001",
+    "vlan_id": 100,
+    "radius_reply_attributes": null,
+    "cacheable_credentials": {...}
+  }
+}
+```
+
+## Troubleshooting
+
+### Enable Debug Logging
+
+Run FreeRADIUS in debug mode:
+```bash
+sudo systemctl stop freeradius
+sudo freeradius -X
+```
+
+### Check Cache
+
+Inspect the SQLite cache:
+```bash
+sudo sqlite3 /var/lib/freeradius/device_manager_verifier_cache.sqlite3
+```
+
+```sql
+.schema
+SELECT * FROM radius_verifier_cache;
+```
+
+### Common Issues
+
+1. **Module not found**: Ensure `device_manager_radius.py` is in Python's import path
+2. **API authentication fails**: Verify API key/secret are correct
+3. **Cache permission denied**: Check `/var/lib/freeradius` ownership (should be `freerad:freerad`)
+4. **Timeout errors**: Increase `DEVICE_MANAGER_HTTP_TIMEOUT` or check network connectivity
+5. **SSL errors**: Verify Frappe server certificate is trusted
+
+### Log Messages
+
+Success:
+```
+device_manager_radius: initialized remote Device Manager mode: https://...
+device_manager_radius: using cached credentials for username
+```
+
+Errors:
+```
+device_manager_radius: failed to initialize: Set DEVICE_MANAGER_FRAPPE_URL...
+device_manager_radius: authorization failed: [Errno 111] Connection refused
+device_manager_radius: authorization failed and no cached credentials matched...
+```
+
+## Security Notes
+
+1. **Protect API credentials**: Ensure systemd override files are mode 600
+2. **Use HTTPS**: Always use HTTPS for the Frappe server URL
+3. **Firewall rules**: Restrict RADIUS server to only access Frappe API endpoints
+4. **Cache expiration**: Set appropriate `DEVICE_MANAGER_CACHE_MAX_STALE_SECONDS` for your security policy
+5. **Monitor logs**: Regularly review FreeRADIUS logs for unauthorized access attempts