Unifi-Voucher-Tool/Readme.md

UniFi Voucher Management System

Webbasiertes System zur Verwaltung von WLAN-Vouchers für UniFi OS mit Multi-Site-Unterstützung, Benutzerverwaltung und Microsoft 365 Integration.

Features

• Voucher-Erstellung mit QR-Code-Anzeige und E-Mail-Versand
• Multi-Site-Support – mehrere UniFi-Standorte verwalten
• Benutzerverwaltung mit granularer Site-Zugriffskontrolle
• Authentifizierung via lokale Accounts oder Microsoft 365 OAuth
• CSV-Export aller Vouchers pro Site
• Admin-Dashboard mit Live-Statistiken und Sync-Funktion
• Öffentlicher Zugriff – optional ohne Login nutzbar
• CSRF-Schutz, bcrypt-Passwörter, Prepared Statements, Login-Rate-Limiting

Anforderungen

• PHP 7.4+, MySQL 5.7+ / MariaDB 10.2+, Apache/Nginx
• PHP-Extensions: PDO, PDO_MySQL, cURL, mbstring, JSON
• 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. http://ihre-domain.de/install.php öffnen
3. Den 5-Schritte-Assistenten durchlaufen:
   • Schritt 1: Datenbank-Verbindungsdaten
   • Schritt 2: Administrator-Account (Name, E-Mail, Passwort)
   • Schritt 3: Allgemeine Einstellungen (Titel, Logo, öffentlicher Zugriff)
   • Schritt 4: Microsoft 365 Integration (optional)
   • Schritt 5: Installation abschließen
4. install.php nach erfolgreicher Installation löschen

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

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('SESSION_LIFETIME', 3600);
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: User.Read, email, profile, openid
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

# .htaccess – sensible Dateien sperren
<FilesMatch "^(config\.php|database\.sql|.*\.md)$">
    Order Allow,Deny
    Deny from all
</FilesMatch>

-- Dedizierter Datenbank-Benutzer
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

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

Voucher werden nicht erstellt:

• UniFi Controller Logs prüfen
• API-Berechtigungen des Admin-Accounts prüfen
• Site ID korrekt? (zu finden in der UniFi Controller URL)

Microsoft 365 Login funktioniert nicht:

• Redirect URI in Azure AD prüfen
• Client ID, Secret und Tenant ID kontrollieren

API-Dokumentation

Login (UniFi OS):

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
X-CSRF-Token: <token>
Body: {"cmd": "delete-voucher", "_id": "<voucher_id>"}

Roadmap

• Voucher-Templates (vordefinierte Laufzeiten)
• Bulk-Voucher-Erstellung
• Erweiterte Reporting-Funktionen
• Docker-Container
• Mehrsprachigkeit

---

Version: 2.1.0 | Autor: Friederich Loheide | Letztes Update: April 2026