commit 4df2eddc6af3baef93ea03c12bd3d5e532748528 Author: Kevin Feiler Date: Wed Oct 15 22:28:45 2025 +0200 first commit diff --git a/README.md b/README.md new file mode 100644 index 0000000..733231d --- /dev/null +++ b/README.md @@ -0,0 +1,417 @@ +# KeyHelp Manager - WHMCS Provisioning Modul + +Ein professionelles WHMCS-Provisioning-Modul für die automatische Verwaltung von KeyHelp-Webhosting-Accounts. + +**Entwickelt von:** Kevin Feiler / AVVGO +**Website:** https://avvgo.de + +## 📋 Inhaltsverzeichnis + +- [Features](#features) +- [Systemanforderungen](#systemanforderungen) +- [Installation](#installation) +- [Konfiguration](#konfiguration) +- [Verwendung](#verwendung) +- [API-Endpunkte](#api-endpunkte) +- [Fehlerbehebung](#fehlerbehebung) +- [Support](#support) + +## ✨ Features + +- ✅ **Automatische Account-Erstellung** - Erstellt KeyHelp-Accounts direkt nach der Bezahlung +- ✅ **Account-Verwaltung** - Sperren, Entsperren und Löschen von Accounts +- ✅ **Passwort-Management** - Sichere Passwortverwaltung und -änderung +- ✅ **Client-Area-Integration** - Übersichtliche Darstellung von Login-Daten und Statistiken +- ✅ **Single Sign-On** - Ein-Klick-Login für Admins direkt in den Kundenaccount +- ✅ **Live-Statistiken** - Echtzeit-Anzeige von Speicherplatz, Traffic, Domains, etc. +- ✅ **SSL-Unterstützung** - Sichere HTTPS-Verbindungen zur KeyHelp-API +- ✅ **Detailliertes Logging** - Alle API-Calls werden in WHMCS protokolliert +- ✅ **Fehlerbehandlung** - Robuste Error-Handling-Mechanismen + +## 🔧 Systemanforderungen + +### WHMCS-Server +- **WHMCS:** Version 8.13 oder höher +- **PHP:** Version 8.3 oder höher +- **Guzzle HTTP Client:** Wird von WHMCS mitgeliefert +- **MySQL/MariaDB:** Von WHMCS unterstützte Version + +### KeyHelp-Server +- **KeyHelp:** Neueste stabile Version (mit API v2) +- **API-Zugang:** API-Key mit Admin-Rechten +- **SSL-Zertifikat:** Empfohlen für sichere API-Kommunikation + +## 📦 Installation + +### Schritt 1: Dateien hochladen + +1. Laden Sie das komplette `keyhelpmanager`-Verzeichnis in Ihr WHMCS-Installationsverzeichnis hoch: + +``` +/pfad/zu/whmcs/modules/servers/keyhelpmanager/ +``` + +Die Verzeichnisstruktur sollte wie folgt aussehen: + +``` +whmcs/ +└── modules/ + └── servers/ + └── keyhelpmanager/ + ├── keyhelpmanager.php + └── templates/ + └── clientarea.tpl +``` + +### Schritt 2: Dateirechte setzen + +Stellen Sie sicher, dass die Dateien die korrekten Rechte haben: + +```bash +chmod 644 modules/servers/keyhelpmanager/keyhelpmanager.php +chmod 644 modules/servers/keyhelpmanager/templates/clientarea.tpl +chmod 755 modules/servers/keyhelpmanager/ +``` + +### Schritt 3: KeyHelp API-Key generieren + +1. Loggen Sie sich in Ihr KeyHelp-Panel ein +2. Navigieren Sie zu **Einstellungen → API** +3. Erstellen Sie einen neuen API-Key mit **Admin-Rechten** +4. Kopieren Sie den generierten API-Key (wird nur einmal angezeigt!) + +### Schritt 4: Server in WHMCS hinzufügen + +1. Loggen Sie sich in den WHMCS-Admin-Bereich ein +2. Navigieren Sie zu **Setup → Products/Services → Servers** +3. Klicken Sie auf **Add New Server** +4. Füllen Sie die Felder aus: + - **Name:** z.B. "KeyHelp Server 1" + - **Hostname:** IP-Adresse oder FQDN Ihres KeyHelp-Servers (ohne http://) + - **Type:** Wählen Sie **KeyHelp Manager** + - **Username:** Kann leer bleiben + - **Password:** Tragen Sie hier Ihren **API-Key** ein + - **Accesshash:** Kann leer bleiben + - **Secure:** Aktivieren Sie dies, wenn Sie SSL verwenden + +5. Klicken Sie auf **Test Connection** um die Verbindung zu prüfen +6. Speichern Sie die Konfiguration + +### Schritt 5: Produkt/Service erstellen + +1. Navigieren Sie zu **Setup → Products/Services → Products/Services** +2. Erstellen Sie ein neues Produkt oder bearbeiten Sie ein bestehendes +3. Im Tab **Module Settings**: + - **Module Name:** Wählen Sie **KeyHelp Manager** + - **Server:** Wählen Sie Ihren KeyHelp-Server + - Konfigurieren Sie die Modul-Einstellungen (siehe unten) + +4. Speichern Sie das Produkt + +## ⚙️ Konfiguration + +### Server-Konfigurationsoptionen + +Bei der Einrichtung des Servers in WHMCS können Sie folgende Optionen konfigurieren: + +| Option | Typ | Beschreibung | Standard | +|--------|-----|--------------|----------| +| **Hostname (IP or FQDN)** | Text | Hostname oder IP-Adresse des KeyHelp-Servers | - | +| **API Key** | Password | Ihr KeyHelp API-Schlüssel | - | +| **Use SSL** | Yes/No | SSL für API-Verbindungen verwenden | On | +| **Verify SSL Certificate** | Yes/No | SSL-Zertifikat überprüfen | On | + +> **Hinweis:** Bei selbstsignierten SSL-Zertifikaten sollten Sie "Verify SSL Certificate" deaktivieren. + +### Produkt-Konfiguration + +#### Automatische Werte + +Das Modul verwendet automatisch folgende Werte aus WHMCS: + +- **Domain:** Die vom Kunden gewählte Domain +- **Username:** Automatisch generiert aus der Domain (oder manuell festgelegt) +- **Password:** Automatisch generiert (sicheres 16-stelliges Passwort) +- **E-Mail:** Aus den Kundendaten + +#### Konfigurierbare Optionen (Optional) + +Sie können zusätzliche konfigurierbare Optionen für KeyHelp-Pläne erstellen: + +1. Navigieren Sie zu **Setup → Products/Services → Configurable Options** +2. Erstellen Sie eine neue Konfigurationsgruppe +3. Fügen Sie eine Option hinzu: + - **Option Name:** "KeyHelp Plan" + - **Option Type:** Dropdown/Radio + - **Options:** Liste Ihrer KeyHelp-Pläne (z.B. "Basic", "Professional", "Enterprise") + +4. Verknüpfen Sie die Konfigurationsgruppe mit Ihrem Produkt + +### Custom Fields (Automatisch erstellt) + +Das Modul erstellt automatisch folgendes Custom Field: + +- **KeyHelp User ID** - Speichert die interne KeyHelp-User-ID (Admin-only) + +## 🚀 Verwendung + +### Für Kunden (Client Area) + +Nachdem ein Kunde das Produkt bestellt und bezahlt hat: + +1. Der Account wird automatisch in KeyHelp erstellt +2. Im **Services**-Bereich sieht der Kunde: + - KeyHelp Login-URL + - Benutzername und Passwort (mit Copy-Funktion) + - Domain-Name + - Live-Statistiken (Speicherplatz, Traffic, Anzahl Domains/DBs/E-Mails) + - "Jetzt zu KeyHelp einloggen"-Button + +### Für Admins + +Im WHMCS-Admin-Bereich haben Sie folgende Optionen: + +#### Account-Verwaltung + +- **Create** - Erstellt einen neuen KeyHelp-Account +- **Suspend** - Sperrt den Account (bei Zahlungsverzug) +- **Unsuspend** - Entsperrt einen gesperrten Account +- **Terminate** - Löscht den Account unwiderruflich +- **Change Password** - Ändert das Account-Passwort + +#### Single Sign-On + +Klicken Sie auf den "Login zu KeyHelp"-Button neben dem Service, um sich direkt als der jeweilige Kunde in KeyHelp einzuloggen (ohne Passwort). + +## 🔌 API-Endpunkte + +Das Modul verwendet folgende KeyHelp API v2 Endpunkte: + +### Benutzer-Verwaltung + +- `POST /api/v2/users` - Benutzer erstellen +- `GET /api/v2/users/{id}` - Benutzer-Details abrufen +- `PUT /api/v2/users/{id}` - Benutzer aktualisieren (Passwort, Status) +- `DELETE /api/v2/users/{id}` - Benutzer löschen + +### Domain-Verwaltung + +- `POST /api/v2/domains` - Domain hinzufügen +- `GET /api/v2/domains/{id}` - Domain-Details abrufen + +### Statistiken + +- `GET /api/v2/users/{id}/statistics` - Account-Statistiken abrufen + +### Sessions (SSO) + +- `POST /api/v2/sessions` - Login-Session erstellen + +### Server-Informationen + +- `GET /api/v2/server/version` - Server-Version abrufen (für Connection-Test) + +## 🔍 Funktionsweise + +### Account-Erstellung + +``` +Kunde bestellt → WHMCS aktiviert Service → keyhelpmanager_CreateAccount() + ↓ +1. Validiere Parameter (Domain, Username, etc.) +2. Generiere sicheres Passwort falls nicht vorhanden +3. API-Call: POST /users (Benutzer erstellen) +4. API-Call: POST /domains (Domain hinzufügen) +5. Speichere Credentials in WHMCS-Datenbank +6. Return "success" + ↓ +Kunde erhält Zugriff auf Service mit Login-Daten +``` + +### Account-Sperrung + +``` +Admin sperrt Account → keyhelpmanager_SuspendAccount() + ↓ +1. Hole User-ID aus WHMCS-Datenbank +2. API-Call: PUT /users/{id} mit {"is_locked": true} +3. Return "success" + ↓ +Kunde kann sich nicht mehr in KeyHelp einloggen +``` + +### Client Area + +``` +Kunde öffnet Service → keyhelpmanager_ClientArea() + ↓ +1. Lade Account-Details aus WHMCS-Datenbank +2. API-Call: GET /users/{id}/statistics (Live-Daten) +3. Formatiere Daten (Bytes → MB/GB, Prozentangaben) +4. Return Template-Variablen + ↓ +Smarty-Template rendert die Anzeige +``` + +### Single Sign-On + +``` +Admin klickt auf "Login" → keyhelpmanager_LoginLink() + ↓ +1. Hole User-ID aus WHMCS-Datenbank +2. API-Call: POST /sessions mit User-ID +3. Erhalte Session-Token +4. Erstelle Login-URL mit Token +5. Return Redirect-URL + ↓ +Admin wird direkt in KeyHelp eingeloggt +``` + +## 🐛 Fehlerbehebung + +### "KeyHelp-Hostname ist nicht konfiguriert" + +**Lösung:** Stellen Sie sicher, dass Sie den Hostname/IP in der Server-Konfiguration eingetragen haben (ohne `http://` oder `https://`). + +### "KeyHelp API-Schlüssel ist nicht konfiguriert" + +**Lösung:** +1. Generieren Sie einen neuen API-Key in KeyHelp +2. Tragen Sie ihn im **Password**-Feld der Server-Konfiguration ein + +### "Verbindung zum KeyHelp-Server fehlgeschlagen" + +**Mögliche Ursachen:** +- Firewall blockiert Verbindung +- Falscher Hostname/IP +- KeyHelp-Server ist nicht erreichbar +- SSL-Zertifikat-Problem bei selbstsigniertem Zertifikat + +**Lösung:** +1. Prüfen Sie die Firewall-Einstellungen +2. Testen Sie die Verbindung manuell: `curl -k https://ihr-server.de/api/v2/server/version -H "X-API-Key: IHR_KEY"` +3. Bei selbstsigniertem Zertifikat: Deaktivieren Sie "Verify SSL Certificate" + +### "Domain konnte nicht hinzugefügt werden" + +**Mögliche Ursachen:** +- Domain existiert bereits in KeyHelp +- Ungültiges Domain-Format +- DNS-Probleme + +**Lösung:** +1. Prüfen Sie, ob die Domain bereits in KeyHelp existiert +2. Validieren Sie das Domain-Format (keine Leerzeichen, gültige TLD) + +### "Benutzer-ID nicht gefunden" + +**Ursache:** Der Account wurde nicht korrekt erstellt oder die Custom Fields fehlen. + +**Lösung:** +1. Prüfen Sie das WHMCS Module Log: **Utilities → Logs → Module Log** +2. Erstellen Sie den Account manuell neu +3. Stellen Sie sicher, dass das Custom Field "KeyHelp User ID" existiert + +### Logs prüfen + +WHMCS protokolliert alle API-Calls: + +1. Navigieren Sie zu **Utilities → Logs → Module Log** +2. Filtern Sie nach "keyhelpmanager" +3. Prüfen Sie Request und Response für Details + +## 📊 Logging + +Das Modul nutzt die integrierte WHMCS `logModuleCall()`-Funktion: + +- **Modul-Name:** keyhelpmanager +- **Protokolliert:** Alle API-Requests und Responses +- **Maskiert:** API-Keys werden automatisch maskiert +- **Speicherort:** WHMCS → Utilities → Logs → Module Log + +## 🔒 Sicherheit + +### Best Practices + +1. **Verwenden Sie immer SSL** für API-Verbindungen +2. **API-Key-Schutz:** + - Teilen Sie Ihren API-Key niemals mit Dritten + - Speichern Sie ihn nur im WHMCS-Server-Passwort-Feld + - WHMCS verschlüsselt dieses Feld automatisch +3. **Regelmäßige Updates:** Halten Sie WHMCS und KeyHelp auf dem neuesten Stand +4. **Firewall:** Beschränken Sie den API-Zugriff auf die IP Ihres WHMCS-Servers +5. **2FA:** Aktivieren Sie Zwei-Faktor-Authentifizierung für KeyHelp-Admin-Accounts + +### Passwort-Generierung + +Das Modul generiert sichere Passwörter: +- **Länge:** 16 Zeichen +- **Zeichensatz:** a-z, A-Z, 0-9, Sonderzeichen +- **Methode:** `random_int()` (kryptografisch sicher) + +## 🆘 Support + +### Dokumentation + +- **KeyHelp Dokumentation:** https://www.keyhelp.de/dokumentation +- **WHMCS Developer Docs:** https://developers.whmcs.com/ + +### Debugging + +Bei Problemen: + +1. Aktivieren Sie das Debug-Logging in WHMCS +2. Prüfen Sie die Module Logs +3. Testen Sie die API-Verbindung manuell +4. Prüfen Sie die PHP-Error-Logs + +### Community + +- **KeyHelp Forum:** https://forum.keyhelp.de/ +- **WHMCS Community:** https://whmcs.community/ + +## 📝 Changelog + +### Version 1.0.0 (Initial Release) + +- ✅ Basis-Funktionalität: Create, Suspend, Unsuspend, Terminate +- ✅ Client Area mit Login-Details und Statistiken +- ✅ Admin Single Sign-On +- ✅ Passwort-Management +- ✅ SSL-Unterstützung +- ✅ Umfassendes Error-Handling +- ✅ Smarty-Template für Client Area +- ✅ API v2 Unterstützung + +## 👨‍💻 Entwickler + +Dieses Modul wurde entwickelt von: + +- **Name:** Kevin Feiler +- **Firma:** AVVGO +- **Website:** https://avvgo.de +- **E-Mail:** info@avvgo.de + +## 📜 Lizenz + +MIT License - Copyright (c) 2024 Kevin Feiler / AVVGO + +Siehe LICENSE-Datei für vollständige Details. + +## 🔧 Technische Anforderungen + +- **PHP:** 8.3+ +- **WHMCS:** 8.13+ +- **KeyHelp:** Neueste stabile Version mit API v2 + +## 💬 Support & Kontakt + +Bei Fragen, Problemen oder Feature-Wünschen: + +- **E-Mail:** info@avvgo.de +- **Website:** https://avvgo.de +- **GitHub Issues:** Für Bug-Reports und Feature-Requests + +--- + +**Hinweis:** Dieses Modul wurde mit Fokus auf Stabilität, Sicherheit und Benutzerfreundlichkeit entwickelt von Kevin Feiler / AVVGO. \ No newline at end of file