# 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"
```