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       ┌──────────────────┐
│  UniFi AP /     │ ◄───────────────────────► │    FreeRADIUS    │
│  Dream Machine  │                           │   (Port 1812/13) │
└────────┬────────┘                           └────────┬─────────┘
         │                                             │
         │ Wi-Fi 802.1X /                             │ SQL Queries
         │ Guest Auth                                  ▼
         │                                    ┌──────────────────┐
         │                                    │    PostgreSQL    │
         │                                    │  (Radius DB)     │
         │                                    └────────▲─────────┘
         │                                             │
         │ HTTP/8080                                   │ EF Core
         ▼                                             │
┌─────────────────┐                                    │
│ Guests / Admins │ ───────────────────────────────────┘
│ (Web Portal)    │        RadiusController Web App
└─────────────────┘

---

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

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

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

  freeradius:
    image: freeradius/freeradius-server:latest
    container_name: radius_freeradius
    restart: always
    depends_on:
      - postgres
    ports:
      - "1812:1812/udp"
      - "1813:1813/udp"
    environment:
      - DB_NAME=radius
      - DB_HOST=postgres
      - DB_USER=radius
      - DB_PASS=radpass

  radiuscontroller:
    image: cablon.vanolst.tech/tygozwolle/radius:latest
    container_name: radius_web_controller
    restart: always
    depends_on:
      - postgres
    ports:
      - "8080:8080"
    environment:
      - ConnectionStrings__DefaultConnection=Host=postgres;Port=5432;Database=radius;Username=radius;Password=radpass;
      - ASPNETCORE_ENVIRONMENT=Production

2. Start the stack:

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:

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:

   • Access the Admin Dashboard at http://<server-ip>:8080/admin.
   • Default login: admin / admin123.
   • 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:

docker exec -it radius_freeradius radtest <username> <password> 127.0.0.1 0 testing123

View Live FreeRADIUS Logs

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