kevin/KeyHelp-Manager-for-WHMCS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
KeyHelp-Manager-for-WHMCS/README.md
Kevin Feiler dccf4b1b4e ssl
2025-10-16 03:34:17 +02:00

14 KiB
Raw Permalink Blame History

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
Version: 2.0.0

🆕 NEU in Version 2.0.0

  • 🎯 Zentralisierte Server-Konfiguration - API-Keys nur einmal in WHMCS Server-Einstellungen eintragen
  • 📋 Template/Vorlagen-System - Automatische Synchronisation von KeyHelp-Plänen als Dropdown
  • 🚀 Template-basierte Provisionierung - Domains werden automatisch mit gewählter Vorlage erstellt
  • 🔗 Admin-Panel-Link - Direkter Zugriff zur Domain-Verwaltung im KeyHelp-Panel
  • 📊 Template-Anzeige - Kunden sehen ihr verwendetes Template im Client Area

→ Update-Anleitung von v1.x auf v2.0

📋 Inhaltsverzeichnis

✨ Features

Core 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

Neue Features v2.0

  • 🎯 Zentralisierte API-Konfiguration - API-Keys werden nur einmal in WHMCS Server-Einstellungen eingegeben
  • 📋 Template-Synchronisation - KeyHelp-Pläne/Vorlagen werden automatisch als Dropdown geladen
  • 🔄 Sync Templates Button - Manuelles Aktualisieren der verfügbaren Templates
  • 🏷️ Template-basierte Erstellung - Accounts werden mit gewähltem Template/Plan erstellt
  • 🔗 Admin-Panel-Link - Direkter Link zur Domain-Verwaltung im KeyHelp-Panel
  • 📊 Template-Anzeige - Template-Name wird im Client Area angezeigt
  • ⚡ Template-Cache - Bessere Performance durch 5-Minuten-Cache
  • 🎨 Verbessertes UI - Übersichtlichere Button-Anordnung und Design

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

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
HTTP Prefix Text Optional: "no-verify" für manuelles Deaktivieren der SSL-Verifizierung -

Hinweis zur SSL-Verifizierung:

  • Bei Verwendung einer IP-Adresse wird die SSL-Verifizierung automatisch deaktiviert
  • Bei selbstsignierten SSL-Zertifikaten mit Domain-Namen: Tragen Sie "no-verify" im Feld "HTTP Prefix" ein
  • Für Produktivumgebungen wird immer ein gültiges SSL-Zertifikat empfohlen

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: Tragen Sie "no-verify" im Feld "HTTP Prefix" ein

"cURL error 60: SSL certificate problem"

Ursache: SSL-Zertifikat stimmt nicht mit dem Hostnamen überein (häufig bei IP-Adressen oder selbstsignierten Zertifikaten)

Lösung:

  1. Bei IP-Adresse: Das Modul deaktiviert die SSL-Verifizierung automatisch
  2. Bei selbstsigniertem Zertifikat mit Domain: Tragen Sie "no-verify" im Feld "HTTP Prefix" der Server-Konfiguration ein
  3. Empfohlen für Produktion: Verwenden Sie ein gültiges SSL-Zertifikat von Let's Encrypt oder einem anderen CA

"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

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

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

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

Hinweis: Dieses Modul wurde mit Fokus auf Stabilität, Sicherheit und Benutzerfreundlichkeit entwickelt von Kevin Feiler / AVVGO.

Reference in New Issue View Git Blame Copy Permalink