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

pip install -e /path/to/radius_client

Then configure FreeRADIUS to use the module:

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/):

sudo cp device_manager_radius.py /etc/freeradius/3.0/mods-config/python3/

Then configure FreeRADIUS:

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

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

Navigate to API Secret in Device Manager settings or create a System User
Generate an API Key and API Secret
Grant the user permissions for Device Manager doctypes

FreeRADIUS configuration

Add to your FreeRADIUS virtual server:

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:

sudo tail -f /var/log/freeradius/radius.log

Test the module directly:

sudo freeradius -X

Verify API connectivity:

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"

2.9 KiB Raw Permalink Blame History