Merge pull request 'docs: add detailed setup guide for RadiusController and UniFi integration' (#3) from readme into master

Reviewed-on: #3
2026-07-24 11:53:56 +02:00
parent a5d57d3202 21118838c0
commit 91a2aeb3fa
1 changed files with 175 additions and 0 deletions
@@ -0,0 +1,175 @@
 # 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):
 ```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
  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:
 ```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**:
   - 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:
 ```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