¶ API Key Wildcard
¶ Inhaltsverzeichnis
- Systemanforderungen
- Installation
- Nutzung
- Fehlerbehebung
- Technische Details
- Sicherheitsüberlegungen
- Best Practices
- FAQ
¶ Überblick
Das API Key Wildcard Plugin stellt einen separaten API-Endpoint (/api/wildcard/tickets.json) bereit, der es API-Keys mit der IP-Adresse 0.0.0.0 erlaubt, Anfragen von jeder IP-Adresse zu akzeptieren.
Das löst ein häufiges Entwicklungsproblem: osTickets native API erfordert eine spezifische IP-Adresse für jeden API-Key. Das ist sicher für Produktivumgebungen, aber umständlich während der Entwicklung, wenn sich deine IP-Adresse häufig ändert (dynamische IP, Arbeiten von verschiedenen Standorten, CI/CD-Pipelines).
¶ ⚠️ Sicherheitswarnung
WICHTIG: Verwende Wildcard-API-Keys (0.0.0.0) nur in Entwicklungsumgebungen!
In Produktivumgebungen sollten API-Keys aus Sicherheitsgründen immer an spezifische IP-Adressen gebunden sein.
Warum das wichtig ist:
- 🔒 API-Keys mit
0.0.0.0akzeptieren Anfragen von JEDER IP-Adresse weltweit - 🔒 Jeder, der deinen API-Key erhält, könnte von überall Tickets erstellen
- 🔒 Produktivsysteme sollten restriktives IP-Whitelisting verwenden
Sichere Verwendung:
- ✅ Entwicklungsumgebungen (localhost)
- ✅ Interne Netzwerke hinter Firewalls
- ✅ Test-/Staging-Umgebungen
- ❌ Öffentlich zugängliche Produktivserver
¶ Hauptfunktionen
- ✅ Separater Wildcard-Endpoint - Standard-API bleibt unverändert und sicher
- ✅ Keine Core-Modifikationen - Echtes Plugin, kann einfach aktiviert/deaktiviert werden
- ✅ Automatische Installation - Einfach Plugin aktivieren, kein manuelles Kopieren
- ✅ Automatische Updates - Versionserkennung und Auto-Update bei Plugin-Dateiänderungen
- ✅ Apache & NGINX-Unterstützung - Funktioniert mit beiden Webservern
¶ Anwendungsfälle
- Lokale Entwicklung - Deine Home-IP-Adresse ändert sich häufig (dynamische IP)
- API-Integrationstests - Testen von verschiedenen Servern/Standorten ohne IP-Update
- MCP-Server - claude-mcp-osTicket-Integration mit wechselnden IPs
- CI/CD-Pipelines - Automatisierte Tests mit dynamischen IPs (Nicht-Produktion)
- Team-Entwicklung - Entwickler arbeiten von verschiedenen Standorten (Zuhause, Büro, Café)
¶ Systemanforderungen
| Anforderung | Version | Hinweise |
|---|---|---|
| osTicket | 1.18.x | Plugin nutzt osTickets native API-Infrastruktur |
| PHP | 7.4+ | Empfohlen: PHP 8.1+ für beste Performance |
| Webserver | Apache oder NGINX | Apache benötigt mod_rewrite aktiviert |
| Dateiberechtigungen | Schreibzugriff auf /api/ |
Erforderlich für automatische Installation |
¶ Installation
¶ Schritt 1: Plugin-Dateien installieren
¶ Methode 1: ZIP-Download (Empfohlen)
- Lade das neueste Release von Releases herunter
- Entpacke die ZIP-Datei
- Lade den
api-key-wildcard-Ordner nach/include/plugins/auf deinem osTicket-Server hoch
Finaler Pfad: /pfad/zu/osticket/include/plugins/api-key-wildcard/
¶ Methode 2: Git Repository
cd /pfad/zu/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-api-key-wildcard.git
¶ Schritt 2: Plugin in osTicket aktivieren
- Melde dich im osTicket Admin Panel an
- Navigiere zu: Admin Panel → Verwalten → Plugins
- Finde "API Key Wildcard Support" in der Plugin-Liste
- Klicke auf Aktivieren
Was automatisch passiert:
- ✅ Kopiert
wildcard.phpins/api/-Verzeichnis - ✅ Aktualisiert
/api/.htaccessmit erforderlichen Rewrite-Rules - ✅ Setzt korrekte Dateiberechtigungen
- ✅ Schreibt Installationsdetails ins Error-Log
Keine manuelle Konfiguration nötig!
¶ Schritt 3: API-Key mit 0.0.0.0 erstellen
- Gehe zu Admin Panel → Verwalten → API-Schlüssel
- Klicke Neuen API-Schlüssel hinzufügen
- Setze IP-Adresse auf:
0.0.0.0 - Aktiviere Kann Tickets erstellen: ✅ Ja
- Speichern und generierten API-Key kopieren
Wichtig: Der API-Key MUSS die IP 0.0.0.0 haben, um mit dem Wildcard-Endpoint zu funktionieren!
¶ Manuelle Installation (Falls automatische Installation fehlschlägt)
Falls die automatische Installation fehlschlägt (z.B. wegen Dateiberechtigungen):
-
Wildcard-Endpoint kopieren:
cp /pfad/zu/osticket/include/plugins/api-key-wildcard/wildcard.php \ /pfad/zu/osticket/api/wildcard.php chmod 755 /pfad/zu/osticket/api/wildcard.php -
/api/.htaccessaktualisieren - Füge diese Zeilen nachRewriteEngine Onhinzu:# Disable MultiViews for wildcard endpoint (prevents mod_negotiation) Options -MultiViews # Wildcard API endpoint (must come BEFORE the default rule) RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^wildcard/(.*)$ wildcard.php/$1 [L] -
Berechtigungen prüfen:
chmod 755 /pfad/zu/osticket/api/wildcard.php chmod 644 /pfad/zu/osticket/api/.htaccess
¶ NGINX-Konfiguration
Falls du NGINX verwendest, füge dies manuell zu deinem Server-Block hinzu:
# osTicket API Key Wildcard Plugin
location ~ ^/api/wildcard/ {
rewrite ^/api/wildcard/(.*)$ /api/wildcard.php/$1 last;
}
# Pass PHP requests to PHP-FPM
location ~ ^/api/wildcard\.php {
fastcgi_split_path_info ^(/api/wildcard\.php)(/.+)$;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
include fastcgi_params;
fastcgi_pass unix:/var/run/php/php-fpm.sock; # An deinen PHP-FPM-Socket anpassen
}
Nach dem Hinzufügen:
- Konfiguration testen:
sudo nginx -t - NGINX neu laden:
sudo systemctl reload nginx
¶ Nutzung
¶ Endpoint-Vergleich
| Feature | Standard-API | Wildcard-API |
|---|---|---|
| Endpoint | /api/tickets.json |
/api/wildcard/tickets.json |
| IP-Beschränkung | Spezifische IP erforderlich | Jede IP (wenn API-Key 0.0.0.0 ist) |
| Sicherheit | Hoch (produktionsbereit) | Niedrig (nur Entwicklung) |
| Anwendungsfall | Produktion | Entwicklung/Tests |
¶ Beispiel: Ticket mit curl erstellen
curl -X POST \
-H "X-API-Key: DEIN_API_KEY_HIER" \
-H "Content-Type: application/json" \
-d '{
"name": "Test User",
"email": "test@example.com",
"subject": "Test Ticket",
"message": "Das ist eine Testnachricht"
}' \
http://localhost/osTicket/api/wildcard/tickets.json
Wichtig:
- Verwende
/api/wildcard/tickets.json(NICHT/api/tickets.json) - API-Key MUSS auf IP
0.0.0.0gesetzt sein - Standard-API-Endpoint funktioniert weiterhin normal
¶ Unterstützte API-Endpoints
Alle Standard-osTicket-API-Endpoints funktionieren über Wildcard:
| Standard-Endpoint | Wildcard-Endpoint |
|---|---|
/api/tickets.json |
/api/wildcard/tickets.json |
/api/tickets/:id.json |
/api/wildcard/tickets/:id.json |
Hinweis: Funktioniert auch mit erweiterten API-Endpoints von anderen Plugins!
¶ Fehlerbehebung
¶ Problem: Automatische Installation fehlgeschlagen
Symptome: Plugin aktiviert, aber Wildcard-Endpoint funktioniert nicht
Prüfen:
- Datei existiert:
ls /pfad/zu/osticket/api/wildcard.php - Error-Log:
tail -f /var/log/apache2/error.log - Dateiberechtigungen: Datei muss vom Webserver lesbar sein
Lösung: Manuelle Installation verwenden (siehe Installationsabschnitt oben)
¶ Problem: 401 Unauthorized Error
Symptome: Anfrage an Wildcard-Endpoint gibt 401 zurück
Mögliche Ursachen:
-
API-Key nicht auf 0.0.0.0 gesetzt
- Lösung: Admin Panel → API-Schlüssel → Key bearbeiten → IP auf
0.0.0.0setzen
- Lösung: Admin Panel → API-Schlüssel → Key bearbeiten → IP auf
-
Falscher Endpoint verwendet
- Lösung: Verwende
/api/wildcard/tickets.json(NICHT/api/tickets.json)
- Lösung: Verwende
-
API-Key deaktiviert
- Lösung: Admin Panel → API-Schlüssel → Key aktivieren
-
Fehlender X-API-Key-Header
- Lösung: Header hinzufügen:
X-API-Key: DEIN_KEY
- Lösung: Header hinzufügen:
¶ Problem: 404 Not Found Error
Symptome: /api/wildcard/tickets.json gibt 404 zurück
Mögliche Ursachen:
-
wildcard.php nicht ins /api/-Verzeichnis kopiert
ls /pfad/zu/osticket/api/wildcard.phpLösung: Plugin deaktivieren/aktivieren um Installation auszulösen, oder manuell kopieren
-
.htaccess-Rewrite-Rule fehlt
cat /pfad/zu/osticket/api/.htaccess | grep wildcardLösung: Rewrite-Rule manuell hinzufügen (siehe Installationsabschnitt)
-
mod_rewrite nicht aktiviert (Apache)
apache2ctl -M | grep rewriteLösung:
sudo a2enmod rewrite sudo systemctl restart apache2 -
MultiViews verursacht Probleme (Apache)
Lösung: Stelle sicher, dass.htaccessOptions -MultiViewsVOR den Rewrite-Rules enthält
¶ Problem: Plugin-Updates nicht angewendet
Symptome: Plugin-Dateien aktualisiert, aber wildcard.php in /api/ ist noch alte Version
Lösung:
- Plugin-Version in Admin Panel → Plugins prüfen
- PHP-OpCode-Cache leeren:
# Für PHP-FPM sudo systemctl reload php8.1-fpm # Für Apache mod_php sudo systemctl reload apache2 - Update manuell auslösen durch Deaktivieren/Aktivieren des Plugins
- Falls immer noch nicht funktioniert, Dateien manuell kopieren
¶ Technische Details
¶ Architektur
┌─────────────────────────────────────┐
│ Client (beliebige IP) │
├─────────────────────────────────────┤
│ HTTP-Request │
│ POST /api/wildcard/tickets.json │
│ X-API-Key: DEIN_KEY_MIT_0.0.0.0 │
├─────────────────────────────────────┤
│ Apache mod_rewrite / NGINX │
│ .htaccess: ^wildcard/(.*)$ │
│ → wildcard.php/$1 │
├─────────────────────────────────────┤
│ wildcard.php │
│ - Prüft ob API-Key IP 0.0.0.0 hat │
│ - Falls ja: Anfrage erlauben │
│ - Falls nein: Ablehnen (401) │
├─────────────────────────────────────┤
│ osTicket API-Verarbeitung │
│ (Standard-Ticket-Erstellungslogik) │
└─────────────────────────────────────┘
¶ Dateistruktur
api-key-wildcard/
├── plugin.php # Plugin-Registrierung
├── class.ApiKeyWildcard.php # Haupt-Plugin-Klasse
├── wildcard.php # API-Endpoint (wird nach /api/ kopiert)
├── api.wildcard.inc.php # API-Implementierungslogik
└── CHANGELOG.md # Versionshistorie
¶ Automatische Installationslogik
Das Plugin verwendet osTickets enable()-Hook:
- Prüfe ob
/api/wildcard.phpexistiert - Falls nicht, aus Plugin-Verzeichnis kopieren
- Dateiberechtigungen setzen (755)
- Prüfe ob
.htaccessWildcard-Rule enthält - Falls nicht, Rewrite-Rule anhängen
- Erfolg/Fehler ins Error-Log schreiben
¶ Versionsverfolgung
Plugin verfolgt installierte Versionen für automatische Updates:
# In .htaccess:
# API Key Wildcard Plugin v1.0.0
Beim Plugin-Aktivieren:
- Version aus
.htaccess-Kommentar extrahieren - Mit aktueller Plugin-Version vergleichen
- Falls unterschiedlich: Dateien neu kopieren und Version aktualisieren
- Update ins Error-Log schreiben
¶ Sicherheitsmechanismus
Standard-API (/api/tickets.json):
// Prüft IP-Adresse gegen API-Key-Konfiguration
if ($api_key->getIpAddr() !== $_SERVER['REMOTE_ADDR']) {
return 401 Unauthorized;
}
Wildcard-API (/api/wildcard/tickets.json):
// Erlaubt nur API-Keys mit 0.0.0.0
if ($api_key->getIpAddr() !== '0.0.0.0') {
return 401 Unauthorized; // Muss Standard-API verwenden
}
// Überspringe IP-Prüfung für 0.0.0.0-Keys
¶ Sicherheitsüberlegungen
¶ Wann du dieses Plugin NICHT verwenden solltest
NIEMALS Wildcard-API-Keys (0.0.0.0) verwenden in:
- ❌ Öffentlich zugänglichen Produktivservern
- ❌ Servern, die sensible Daten verarbeiten
- ❌ Compliance-regulierten Umgebungen (PCI-DSS, HIPAA, etc.)
- ❌ Shared-Hosting-Umgebungen
¶ Sichere Verwendungsszenarien
Sicher, Wildcard-API-Keys zu verwenden in:
- ✅ Entwicklungsumgebungen (localhost)
- ✅ Internen Netzwerken hinter Firewalls
- ✅ Test-/Staging-Umgebungen (nicht öffentlich)
- ✅ Persönlichen Projekten mit niedrigen Sicherheitsanforderungen
¶ Angriffsszenarien
Was mit Wildcard-Keys schiefgehen könnte:
-
Geleakter API-Key
- Angreifer findet Key im Git-Repository
- Erstellt Spam-Tickets von überall
- Mitigation: Niemals
.env-Dateien committen,.gitignoreverwenden
-
Brute-Force-Angriffe
- Angreifer versucht API-Key zu erraten
- Keine IP-Beschränkung um Versuche zu limitieren
- Mitigation: Starke, zufällig generierte API-Keys verwenden
-
Interne Bedrohung
- Verärgerter Mitarbeiter verwendet Wildcard-Key
- Kann von jedem Standort Tickets erstellen/ändern
- Mitigation: Separate Keys pro Entwickler, Zugriff sofort bei Kündigung widerrufen
¶ Zusätzliche Sicherheitsebenen
Falls du Wildcard-Keys verwendest, füge Schutz hinzu:
- 🔒 Firewall-Regeln, die Zugriff auf osTicket einschränken
- 🔒 Nur VPN-Zugriff
- 🔒 IP-Whitelisting auf Firewall-Ebene
- 🔒 Nur HTTPS (SSL erzwingen)
¶ Best Practices
¶ Separate API-Keys verwenden
Erstelle verschiedene API-Keys für verschiedene Zwecke:
Produktiv-API-Key:
- IP:
203.0.113.42(dein Produktivserver) - Endpoint:
/api/tickets.json - Berechtigungen: Minimal (nur Tickets erstellen)
Entwicklungs-API-Key:
- IP:
0.0.0.0(Wildcard) - Endpoint:
/api/wildcard/tickets.json - Berechtigungen: Voll (für Tests)
¶ Entwicklungs-Workflow
Empfohlener Workflow:
-
Lokale Entwicklung
API_KEY=wildcard-dev-key-12345 ENDPOINT=http://localhost/osTicket/api/wildcard/tickets.json -
Staging-Umgebung
# Wildcard falls hinter Firewall # ODER spezifische IP falls öffentlich zugänglich API_KEY=wildcard-staging-key-67890 ENDPOINT=https://staging.example.com/api/wildcard/tickets.json -
Produktivumgebung
# IMMER spezifische IP für Produktion verwenden API_KEY=production-key-specific-ip ENDPOINT=https://tickets.example.com/api/tickets.json # Standard-Endpoint!
¶ Mehrere Entwickler
Best Practice für Teams:
-
Jeder Entwickler erhält seinen eigenen Wildcard-API-Key
- Einfacher nachzuvollziehen, wer was gemacht hat
- Kann individuellen Zugriff widerrufen
- Besserer Audit-Trail
-
API-Keys aussagekräftig benennen
Dev-John-Wildcard-Key Dev-Jane-Wildcard-Key Dev-Bob-Wildcard-Key -
API-Keys regelmäßig rotieren
# Alle 30-90 Tage 1. Neuen API-Key mit 0.0.0.0 erstellen 2. Anwendungen aktualisieren 3. Alten API-Key löschen
¶ In Produktion deaktivieren
Vor Deployment in Produktion:
# Wildcard-Plugin deaktivieren
Admin Panel → Verwalten → Plugins → API Key Wildcard → Deaktivieren
# Standard-API mit spezifischen IPs verwenden
Admin Panel → Verwalten → API-Schlüssel → IP auf spezifische Adresse aktualisieren
¶ FAQ
¶ Allgemeine Fragen
F: Modifiziert dieses Plugin osTicket Core-Dateien?
A: Nein! Das Plugin erstellt einen separaten Endpoint und modifiziert KEINE osTicket-Core-Dateien. Standard-API bleibt unverändert und sicher.
F: Kann ich beide Endpoints gleichzeitig verwenden?
A: Ja! Standard-API für Produktiv-Integrationen (strikte IP), Wildcard-API für Entwicklung (flexible IP).
F: Funktioniert das mit osTicket 1.17 oder älter?
A: Nicht getestet. Das Plugin ist für osTicket 1.18.x konzipiert. Es funktioniert möglicherweise mit 1.17, aber Kompatibilität ist nicht garantiert.
¶ Kompatibilität
F: Ist es kompatibel mit PHP 8.x?
A: Ja! Das Plugin ist getestet mit PHP 7.4, 8.0, 8.1, 8.2 und 8.3.
F: Funktioniert das mit NGINX?
A: Ja, aber benötigt manuelle Konfiguration (siehe Installationsabschnitt). Apache-Setup ist automatisch.
F: Kann ich das mit dem API Endpoints Plugin nutzen?
A: Ja! Alle erweiterten API-Endpoints funktionieren auch über den Wildcard-Endpoint.
¶ Sicherheit
F: Ist das sicher für Produktion?
A: NEIN! Verwende Wildcard-API-Keys (0.0.0.0) nur in Entwicklungs-/Testumgebungen. Produktion sollte immer spezifische IP-Adressen verwenden.
F: Was passiert, wenn mein Wildcard-API-Key geleakt wird?
A: Jeder mit dem Key kann von überall Tickets erstellen. Sofort:
- API-Key im Admin Panel deaktivieren
- Neuen API-Key erstellen
- Anwendungen aktualisieren
- Logs auf verdächtige Aktivitäten prüfen
F: Kann ich Wildcard-Keys auf spezifische IP-Bereiche beschränken?
A: Aktuell nicht. Das Plugin unterstützt nur 0.0.0.0 (alle IPs). Für IP-Bereiche verwende den Standard-API-Endpoint.
¶ 📄 Lizenz
Dieses Plugin wird unter der GNU General Public License v2 veröffentlicht, kompatibel mit osTicket Core.
Details siehe LICENSE.
¶ 💬 Support
Für Fragen oder Probleme erstelle bitte ein Issue auf GitHub:
Issue Tracker: https://github.com/markus-michalski/osticket-api-key-wildcard/issues
Beim Melden von Problemen bitte angeben:
- osTicket-Version (Admin Panel → Einstellungen → Über)
- PHP-Version (
php -v) - Webserver (Apache/NGINX)
- Fehlermeldungen aus Logs
- Schritte zur Reproduktion
¶ 🤝 Mitwirken
Entwickelt von Markus Michalski
Beiträge willkommen!
- Repository forken
- Feature-Branch erstellen
- Pull Request einreichen
Ideen für Beiträge:
- Unterstützung für IP-Bereiche (z.B.
192.168.1.0/24) - Konfigurations-UI zum Aktivieren/Deaktivieren von Wildcard pro Key
- API-Nutzungsstatistiken/Monitoring
- Rate-Limiting für Wildcard-Keys
¶ Changelog
Siehe CHANGELOG.md für Versionshistorie.