radius/README.md

# RadiusController & FreeRADIUS - UniFi Setup Guide

This project provides a complete **RADIUS Authentication & Accounting Controller** for Wi-Fi networks, integrated with **FreeRADIUS**, **PostgreSQL**, and a **Blazor Web Application** for Guest Portal and Admin management.

---

## 🏗️ System Architecture

```
┌─────────────────┐       UDP 1812/1813 (RADIUS)
│  UniFi AP /     │ ◄────────────────────────────────┐
│  Dream Machine  │                                  │
└─────────────────┘                                  │
                                                     ▼
┌─────────────────┐       HTTP 8080 (Web UI)   ┌────────────────────────────────┐
│ Guests / Admins │ ◄────────────────────────► │ Combined Application Container │
│ (Browser)       │                            │ (FreeRADIUS + Web Controller)  │
└─────────────────┘                            └───────────────┬────────────────┘
                                                               │ PostgreSQL
                                                               ▼
                                                       ┌────────────────┐
                                                       │   PostgreSQL   │
                                                       │  (Database)    │
                                                       └────────────────┘
```

---

## 🚀 Step 1: Deploying with Docker Compose (Unraid / Docker)

1. Ensure your `docker-compose.yml` is configured with persistent volume paths (e.g. for Unraid):

```yaml
version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    container_name: radius_postgres
    restart: always
    environment:
      POSTGRES_DB: radius
      POSTGRES_USER: radius
      POSTGRES_PASSWORD: radpass
    ports:
      - "5432:5432"
    volumes:
      - /mnt/user/appdata/radiuscontroller/pgdata:/var/lib/postgresql/data
      - /mnt/user/appdata/radiuscontroller/sql/init.sql:/docker-entrypoint-initdb.d/init.sql:ro

  radiuscontroller:
    image: cablon.vanolst.tech/tygozwolle/radius:latest
    container_name: radius_web_controller
    restart: always
    depends_on:
      - postgres
    ports:
      - "8080:8080"
      - "1812:1812/udp"
      - "1813:1813/udp"
    environment:
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_USER=radius
      - DB_PASS=radpass
      - DB_NAME=radius
      - ConnectionStrings__DefaultConnection=Host=postgres;Port=5432;Database=radius;Username=radius;Password=radpass;
      - ASPNETCORE_ENVIRONMENT=Production
```

2. Start the stack:
```bash
docker compose up -d
```

---

## 🔑 Step 2: Register UniFi as a NAS (RADIUS Client)

FreeRADIUS requires every Network Access Server (NAS) — such as your UniFi Dream Machine, Security Gateway, or Access Points — to be registered in the `nas` database table with a **shared secret**.

Connect to your PostgreSQL database (e.g. via `psql` or database manager) and insert your UniFi device:

```sql
INSERT INTO nas (nasname, shortname, type, secret, description)
VALUES ('192.168.1.1', 'unifi-gw', 'other', 'YourSharedSecret123', 'UniFi Gateway / Access Point');
```

> 💡 **Tip:** If you have multiple UniFi Access Points or a subnet, you can add each AP's IP or register a CIDR subnet (e.g., `192.168.1.0/24`).

---

## 📶 Step 3: Configure UniFi Network Application

### A. Create a RADIUS Profile in UniFi

1. Open your **UniFi Network Application** (e.g. `https://192.168.1.1`).
2. Go to **Settings** ⚙️ → **Profiles** → **RADIUS**.
3. Click **Create New RADIUS Profile**.
4. Configure the settings:
   - **Profile Name**: `RadiusController`
   - **VLAN Support**: Enable if using dynamic VLAN assignment via RADIUS.
   - **Authentication Servers**:
     - **IP Address**: Server IP running FreeRADIUS (e.g. `192.168.1.50`).
     - **Port**: `1812`
     - **Shared Secret**: Matches the secret in the `nas` table (`YourSharedSecret123`).
   - **Accounting Servers**:
     - **Enable Accounting**: `Checked`
     - **IP Address**: Server IP (`192.168.1.50`).
     - **Port**: `1813`
     - **Shared Secret**: Matches the secret in the `nas` table (`YourSharedSecret123`).
5. Click **Save Changes**.

---

### B. Configure WPA Enterprise Wi-Fi Network

1. Go to **Settings** ⚙️ → **WiFi**.
2. Click **Create New WiFi Network** (or edit an existing one, e.g. `Guest-WiFi`).
3. Set the configuration:
   - **Name (SSID)**: e.g. `Secure Guest WiFi`
   - **Security Protocol**: **WPA2 Enterprise** or **WPA3 Enterprise**.
   - **RADIUS Profile**: Select `RadiusController`.
4. Click **Save**.

---

## 📱 Step 4: User Authentication & Portal Workflow

1. **Guest Registration / Portal**:
   - Guests connect to the Web Portal at `http://<server-ip>:8080/portal` (or via reverse proxy).
   - Enter guest name to receive generated **Username** and **Password** (with session and data limits automatically assigned).

2. **Connecting to Wi-Fi**:
   - On their device (phone/laptop), select the `Secure Guest WiFi` network.
   - Select **EAP Method**: `PEAP` or `TTLS` (Phase 2 Auth: `MSCHAPv2` or `GTC`).
   - CA Certificate: `Do not validate` / `Unvalidated` (or install your custom CA if using custom EAP certs).
   - Enter the **Username** and **Password** generated from the portal.

3. **Admin Management & First-Time Setup**:
   - Access the Admin Dashboard at `http://<server-ip>:8080/admin`.
   - **First-Time Setup**: On initial startup, accessing the admin panel automatically presents the setup screen to create your custom administrator username and password.
   - Monitor active RADIUS sessions, data usage, enforce data limits, or revoke users.

---

## 🛠️ Troubleshooting & Verification

### Test RADIUS Server locally
Run `radtest` from another machine or inside the container to test authentication:
```bash
docker exec -it radius_freeradius radtest <username> <password> 127.0.0.1 0 testing123
```

### View Live FreeRADIUS Logs
```bash
docker logs -f radius_freeradius
```

### Verify Firewall Ports on Host / Unraid
Ensure the following ports are open on your host firewall / router:
- **`1812/UDP`**: RADIUS Authentication
- **`1813/UDP`**: RADIUS Accounting
- **`8080/TCP`**: Web Controller / Portal