🎫 UniFi Voucher Management System

Webbasiertes WLAN-Voucher-Management für UniFi OS – mit Multi-Site-Support, Benutzerverwaltung, Microsoft-365-Login und integriertem Auto-Updater.

---

---

✨ Features

• 🎟️ Voucher-Erstellung mit sofortiger QR-Code-Anzeige, Druckvorlage und E-Mail-Versand
• 🏢 Multi-Site-Support – beliebig viele UniFi-Standorte zentral verwalten
• 👥 Benutzerverwaltung mit granularer Site-Zugriffskontrolle
• 🔐 Authentifizierung via lokale Accounts oder Microsoft 365 OAuth
• 🌍 Öffentlicher Modus – optional ohne Login nutzbar (mit CSRF-Schutz & Throttle)
• 📊 Admin-Dashboard mit Live-Statistiken und Sync-Funktion
• 📥 CSV-Export aller Vouchers pro Site
• 🔄 Integrierter Auto-Updater – Updates per Klick aus dem Admin-Bereich
• 🛡️ Security-by-default: CSRF-Schutz, bcrypt-Passwörter, Prepared Statements, Login-Rate-Limiting, OAuth-State-Validierung, Verschlüsselung sensibler Daten

---

📸 Screenshots

Anmeldung & Voucher-Erstellung

Administration & Updater

---

📋 Anforderungen

Komponente	Version
PHP	7.4+ (mit PDO, PDO_MySQL, cURL, mbstring, JSON; empfohlen: OpenSSL/libsodium, Zip)
Datenbank	MySQL 5.7+ / MariaDB 10.2+
Webserver	Apache / Nginx
UniFi	Network Application 7.0+ mit UniFi OS (z. B. UDM, UDR, UniFi OS Server)

---

🚀 Installation

git clone https://github.com/friloo/unifi-voucher-tool.git
cd unifi-voucher-tool

1. Dateien auf den Webserver hochladen
2. https://ihre-domain.de/install.php öffnen
3. Den 5-Schritte-Assistenten durchlaufen:
   1. Datenbank-Verbindungsdaten
   2. Administrator-Account
   3. Allgemeine Einstellungen (Titel, Logo, öffentlicher Zugriff)
   4. Microsoft 365 Integration (optional)
   5. Installation abschließen
4. install.php nach erfolgreicher Installation löschen

🔒 Der Installer erzeugt automatisch einen zufälligen APP_KEY (für die Verschlüsselung der UniFi-Passwörter) und eine .htaccess, die sensible Dateien sperrt. Ein erneuter Aufruf von install.php?reinstall=1 ist nur für angemeldete Administratoren möglich.

Sites konfigurieren

1. Administration → Sites verwalten → Neue Site hinzufügen
2. Felder ausfüllen:
   • Name: Anzeigename (z. B. „Hauptgebäude")
   • Site ID: UniFi Site ID (meist default)
   • Controller URL: https://unifi.example.com:11443
   • Benutzername / Passwort: UniFi Admin-Zugangsdaten
3. Verbindung testen klicken, dann speichern

Voucher erstellen

1. Startseite öffnen (Login je nach Konfiguration optional)
2. Voucher-Name, Anzahl Geräte und Standort wählen
3. Voucher erstellen – Code und QR-Code werden sofort angezeigt
4. Code per E-Mail senden oder ausdrucken

---

🔄 Auto-Updater

Das System bringt einen vollständig integrierten Updater mit, der Quellcode und Datenbank-Migrationen über einen zentralen Update-Proxy nachzieht – ganz ohne SSH oder manuelles git pull.

[diese Instanz]  ←HTTPS→  [Update-Proxy]  ←pull→  [Git-Repo]

Aufruf: Administration → System-Update (/admin/update.php)

• 🔍 „Auf Updates prüfen" zeigt verfügbare Versionen inkl. Changelog
• ⬇️ „Update installieren" spielt das Update ein – mit Wartungsseite, geschützten Pfaden (config.php, Uploads, …), automatischen DB-Migrationen und OPcache-Reset
• 🔀 Channel-Auswahl zwischen stable und development
• 📊 Migrations-Status in einem eigenen Tab

Während eines Updates wird die Anwendung kurz in den Wartungsmodus versetzt:

Der Updater ist vollständig isoliert im Ordner updater/ gekapselt. Details zur Architektur und eine Rückbau-Anleitung stehen in updater/README.md.

---

⚙️ Konfiguration

config.php

Wird automatisch durch den Installer erstellt:

<?php
define('DB_HOST', 'localhost');
define('DB_NAME', 'unifi_voucher');
define('DB_USER', 'username');
define('DB_PASS', 'password');
define('APP_KEY', '...');            // Schlüssel für Verschlüsselung-at-rest
define('SESSION_LIFETIME', 3600);    // Session-Timeout in Sekunden
date_default_timezone_set('Europe/Berlin');

Microsoft 365 OAuth (optional)

1. Im Azure Portal eine App-Registrierung anlegen
2. Umleitungs-URI: https://ihre-domain.de/m365_callback.php
3. API-Berechtigungen: openid, profile, email, User.Read
4. Client ID, Client Secret und Tenant ID in Administration → Einstellungen eintragen

Cron-Job (empfohlen)

Automatische Synchronisation alle 30 Minuten:

*/30 * * * * curl -s "https://ihre-domain.de/cron_sync.php?token=IHR_CRON_TOKEN"

Den Token finden Sie unter Administration → Einstellungen → Cron.

---

🛡️ Sicherheit

Das Tool ist auf einen sicheren Standardbetrieb ausgelegt:

Schutz	Umsetzung
Passwörter	bcrypt (password_hash) für Accounts
UniFi-Passwörter	Verschlüsselt-at-rest (AES-256-GCM / libsodium) über APP_KEY
SQL-Injection	Durchgängig Prepared Statements (PDO)
CSRF	Token für alle schreibenden Aktionen – auch im öffentlichen Modus
OAuth	state-Validierung gegen Login-CSRF
Brute-Force	Login-Rate-Limiting + Throttle der öffentlichen Voucher-Erstellung
Sessions	HttpOnly, SameSite, strict mode + absolutes Timeout
Fehler	display_errors aus, log_errors an (kein Info-Leak)

Empfohlene zusätzliche Härtung am Server:

# .htaccess – sensible Dateien sperren (wird vom Installer erzeugt)
<FilesMatch "^(config\.php|database\.sql|install\.php|test\.php|m365_debug\.php|.*\.md)$">
    Require all denied
</FilesMatch>

-- Dedizierter Datenbank-Benutzer mit minimalen Rechten
CREATE USER 'unifi_voucher'@'localhost' IDENTIFIED BY 'sicheres_passwort';
GRANT SELECT, INSERT, UPDATE, DELETE ON unifi_voucher.* TO 'unifi_voucher'@'localhost';

---

🩺 Problembehandlung

Login funktioniert nicht

• Datenbankverbindung und PHP-Session-Konfiguration prüfen
• Fehler werden ins PHP-Error-Log geschrieben (nicht mehr in den Browser)

UniFi-Verbindung schlägt fehl

• Controller-URL im Browser testen
• Port 11443 für UniFi OS verwenden (nicht 8443)
• Benutzername, Passwort und Site ID prüfen
• cURL-Extension muss aktiviert sein

UniFi OS: HTTP 404 oder 401

• Login-Endpunkt ist /api/auth/login (nicht /api/login)
• API-Pfade benötigen Präfix /proxy/network/api/s/{site}/...
• Älterer UniFi Network Controller (ohne UniFi OS) wird ab Version 2.1.0 nicht mehr unterstützt

Microsoft 365 Login funktioniert nicht

• Redirect URI in Azure AD prüfen
• Client ID, Secret und Tenant ID kontrollieren
• Diagnose unter m365_debug.php (nur als Admin erreichbar)

---

📡 API-Dokumentation (UniFi OS)

# Login
POST /api/auth/login
Body: {"username": "admin", "password": "password"}
Response-Header: X-CSRF-Token: <token>

# Voucher erstellen
POST /proxy/network/api/s/{site_id}/cmd/hotspot
X-CSRF-Token: <token>
Body: {"cmd": "create-voucher", "expire": 480, "n": 1, "note": "Name", "quota": 1}

# Vouchers abrufen
GET /proxy/network/api/s/{site_id}/stat/voucher

# Voucher löschen
POST /proxy/network/api/s/{site_id}/cmd/hotspot
Body: {"cmd": "delete-voucher", "_id": "<voucher_id>"}

---

🗺️ Roadmap

• Voucher-Templates (vordefinierte Laufzeiten)
• Bulk-Voucher-Erstellung
• Erweiterte Reporting-Funktionen
• Docker-Container
• Mehrsprachigkeit
• Auto-Updater mit DB-Migrationen

---

Version 2.1.0 · Autor: Friederich Loheide · Lizenz: MIT