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

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
      - RADIUS_SECRET=radpass
      - ConnectionStrings__DefaultConnection=Host=postgres;Port=5432;Database=radius;Username=radius;Password=radpass;
      - ASPNETCORE_ENVIRONMENT=Production
    volumes:
      - /mnt/user/appdata/radiuscontroller/certs:/etc/freeradius/3.0/certs

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

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