¶ API Key Wildcard Plugin v2.0
¶ Inhaltsverzeichnis
- Überblick
- Hauptfunktionen
- Anwendungsfälle
- Systemanforderungen
- Installation
- Konfiguration
- Nutzung
- Signal Hooks
- Fehlerbehebung
- Technische Details
- FAQ
¶ Überblick
Das API Key Wildcard Plugin stellt einen separaten API-Endpoint (/api/wildcard/tickets.json) bereit, der API-Keys mit der IP-Adresse 0.0.0.0 erlaubt, Anfragen von jeder IP-Adresse zu akzeptieren.
Ohne dieses Plugin: osTickets native API erfordert eine feste IP-Adresse pro API-Key. Bei dynamischen IPs (Home-Office, CI/CD, wechselnde Standorte) muss der Key ständig manuell angepasst werden.
Mit diesem Plugin: Ein separater Wildcard-Endpoint erlaubt API-Keys mit IP
0.0.0.0, Anfragen von beliebigen IPs zu akzeptieren. Der Standard-Endpoint bleibt unverändert und sicher.
Wildcard-API-Keys (
0.0.0.0) sind nur für Entwicklungsumgebungen gedacht! In Produktivumgebungen sollten API-Keys immer an spezifische IP-Adressen gebunden sein.
¶ Hauptfunktionen
- Separater Wildcard-Endpoint - Standard-API bleibt unverändert und sicher
- Keine Core-Modifikationen - Echtes Plugin, kann einfach aktiviert/deaktiviert werden
- Automatische Installation - Plugin aktivieren genügt, kein manuelles Kopieren nötig
- Automatische Updates - Versionserkennung und Auto-Update bei Plugin-Aktualisierung
- Modulare Architektur (v2.0) - Single Responsibility Principle, 4 spezialisierte Klassen
- Konfigurierbares Logging - Wildcard-Zugriffe optional im Debug-Log protokollieren
- XSS-Schutz - Remote-IPs werden vor dem Logging sanitiert
- Apache und NGINX-Unterstützung - Funktioniert mit beiden Webservern
- Sauberes Uninstall - Beim Deaktivieren werden alle Dateien und .htaccess-Änderungen entfernt
¶ 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, unterwegs)
¶ 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 |
Keine externen Abhängigkeiten. Kein Composer nötig.
¶ Installation
- Lade das neueste Release von GitHub 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/
cd /pfad/zu/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-api-key-wildcard.git api-key-wildcard
¶ 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:
wildcard.phpwird ins/api/-Verzeichnis kopiert (chmod 0755)/api/.htaccesserhältOptions -MultiViewsund Wildcard-Rewrite-Rule- Installationsdetails werden ins Error-Log geschrieben
- Installierte Version wird in der Plugin-Konfiguration gespeichert
¶ 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
Der API-Key MUSS die IP
0.0.0.0haben, um mit dem Wildcard-Endpoint zu funktionieren!
¶ Manuelle Installation (Fallback)
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 - Folgende Zeilen nachRewriteEngine Oneinfügen:# 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]
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;
}
sudo nginx -t
sudo systemctl reload nginx
¶ Konfiguration
Das Plugin bietet zwei Einstellungen im Admin Panel (Plugins -> API Key Wildcard -> Konfiguration):
| Einstellung | Beschreibung | Standard | Wann nutzen |
|---|---|---|---|
| Installierte Version | Zeigt die aktuell installierte Plugin-Version (readonly) | Automatisch | Zur Kontrolle, ob Auto-Update funktioniert hat |
| Wildcard-Zugriffe loggen | Protokolliert jeden Wildcard-API-Zugriff im Debug-Log | Aktiviert | Deaktivieren bei hohem API-Volumen um Log-Spam zu vermeiden |
Wenn "Wildcard-Zugriffe loggen" aktiviert ist, wird bei jedem erfolgreichen Wildcard-Zugriff ein Debug-Eintrag mit der Remote-IP ins osTicket System-Log geschrieben. Die IP wird dabei XSS-geschützt (
Format::htmlchars(Format::sanitize())).
¶ 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 IP = 0.0.0.0) |
| 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 via Wildcard",
"message": "Das ist eine Testnachricht über den Wildcard-Endpoint"
}' \
http://localhost/osTicket/api/wildcard/tickets.json
Verwende
/api/wildcard/tickets.json(NICHT/api/tickets.json). Der Standard-Endpoint funktioniert weiterhin normal mit IP-gebundenen Keys.
¶ Unterstützte Formate
| Standard-Endpoint | Wildcard-Endpoint |
|---|---|
/api/tickets.json |
/api/wildcard/tickets.json |
/api/tickets.xml |
/api/wildcard/tickets.xml |
/api/tickets.email |
/api/wildcard/tickets.email |
Funktioniert auch mit erweiterten API-Endpoints von anderen Plugins (z.B. API Endpoints Plugin)!
¶ Signal Hooks
Das Plugin verwendet osTickets Signal-System nicht direkt, sondern überschreibt die API-Controller-Logik:
| Mechanismus | Klasse | Zweck |
|---|---|---|
enable() Hook |
ApiKeyWildcardPlugin |
Installiert Endpoint-Datei und .htaccess-Regeln |
disable() Hook |
ApiKeyWildcardPlugin |
Entfernt Endpoint-Datei und .htaccess-Änderungen |
bootstrap() Hook |
ApiKeyWildcardPlugin |
Prüft auf Version-Mismatch und triggert Auto-Update |
requireApiKey() Override |
WildcardApiController |
Modifizierte API-Key-Validierung mit 0.0.0.0-Support |
¶ Fehlerbehebung
¶ Problem: Automatische Installation fehlgeschlagen
Symptome:
- Plugin aktiviert, aber
/api/wildcard/tickets.jsongibt 404 zurück - Keine
wildcard.phpim/api/-Verzeichnis
Prüfung:
- Datei existiert?
ls /pfad/zu/osticket/api/wildcard.php - Error-Log prüfen:
tail -f /var/log/apache2/error.log - Dateiberechtigungen: Webserver muss Schreibzugriff auf
/api/haben
Lösung: Manuelle Installation verwenden (siehe Installationsabschnitt oben)
¶ Problem: 401 Unauthorized Error
Symptome:
- Anfrage an Wildcard-Endpoint gibt 401 zurück
- Fehlermeldung: "Valid API key required"
Prüfung:
- API-Key IP-Adresse prüfen: Admin Panel -> API-Schlüssel -> IP muss
0.0.0.0sein - Richtigen Endpoint verwenden:
/api/wildcard/tickets.json(nicht/api/tickets.json) - API-Key aktiv? Admin Panel -> API-Schlüssel prüfen
- Header vorhanden?
X-API-Key: DEIN_KEYmuss im Request sein
Lösung:
# Korrekte Anfrage:
curl -X POST \
-H "X-API-Key: DEIN_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Test","email":"test@test.com","subject":"Test","message":"Test"}' \
http://localhost/osTicket/api/wildcard/tickets.json
¶ Problem: 404 Not Found Error
Symptome:
/api/wildcard/tickets.jsongibt 404 zurück- Keine Rewrite-Regel in
.htaccess
Prüfung:
- Endpoint-Datei vorhanden?
ls -la /pfad/zu/osticket/api/wildcard.php - .htaccess-Regel vorhanden?
grep wildcard /pfad/zu/osticket/api/.htaccess - mod_rewrite aktiviert?
apache2ctl -M | grep rewrite - MultiViews deaktiviert?
grep MultiViews /pfad/zu/osticket/api/.htaccess
Lösung: Plugin deaktivieren/aktivieren um Installation neu auszulösen, oder manuell installieren.
¶ Problem: Plugin-Updates nicht angewendet
Symptome:
- Plugin-Dateien aktualisiert, aber
wildcard.phpin/api/ist noch alte Version - Installierte Version in Plugin-Konfiguration stimmt nicht mit plugin.php überein
Lösung:
- PHP-OpCode-Cache leeren:
sudo systemctl reload php8.1-fpm # PHP-FPM sudo systemctl reload apache2 # Apache mod_php - Plugin deaktivieren und wieder aktivieren (triggert
enable()neu) - Version in Plugin-Konfiguration prüfen
Ab v2.0 erkennt das Plugin Version-Mismatches automatisch beim Bootstrap und führt ein Auto-Update durch.
¶ Technische Details
¶ Architektur (v2.0 - Modulare Klassen)
¶ Klassen-Übersicht
¶ Dateistruktur
api-key-wildcard/
├── plugin.php # Plugin-Registrierung (ID, Version, Autor)
├── class.ApiKeyWildcard.php # Haupt-Plugin-Klasse + Config
├── class.PluginConstants.php # Alle Magic-Strings zentralisiert
├── class.PluginInstaller.php # Dateioperationen (install/uninstall)
├── class.HtaccessManager.php # .htaccess-Manipulation
├── api.wildcard.inc.php # WildcardApiController (Kern-Logik)
├── wildcard.php # API-Endpoint (wird nach /api/ kopiert)
├── .htaccess # Referenz-htaccess mit Wildcard-Regeln
├── CHANGELOG.md # Versionshistorie
├── LICENSE # GPL v2
└── README.md # Dokumentation
¶ Sicherheitsmechanismus
Standard-API (/api/tickets.json):
// Prüft IP-Adresse gegen API-Key-Konfiguration
WHERE apikey = ? AND ipaddr = ? -- Client-IP muss exakt matchen
Wildcard-API (/api/wildcard/tickets.json):
// Erweiterte Prüfung: IP-Match ODER Wildcard-IP
WHERE apikey = ? AND (ipaddr = ? OR ipaddr = '0.0.0.0')
Die Remote-IP wird im Access-Log mit
Format::htmlchars(Format::sanitize())gegen XSS-Angriffe geschützt - selbst bei manipulierten X-Forwarded-For-Headern.
¶ Auto-Update-Mechanismus
Ab v2.0 verfolgt das Plugin seine installierte Version über die Plugin-Konfiguration (nicht mehr über .htaccess-Kommentare):
- Bei jedem
bootstrap(): Installierte Version aus Config lesen - Mit aktueller
plugin.php-Version vergleichen - Bei Mismatch:
performUpdate()aufrufen - Update reinstalliert Endpoint-Datei und .htaccess-Regeln
- Neue Version in Config speichern + Log-Eintrag
¶ Sicherheitsüberlegungen
¶ Wann Wildcard-Keys NICHT verwenden
- Öffentlich zugängliche Produktivserver
- Server mit sensiblen Daten
- Compliance-regulierte Umgebungen (PCI-DSS, HIPAA, etc.)
- Shared-Hosting-Umgebungen
¶ Sichere Verwendungsszenarien
- Entwicklungsumgebungen (localhost)
- Interne Netzwerke hinter Firewalls
- Test-/Staging-Umgebungen (nicht öffentlich)
- Persönliche Projekte mit niedrigen Sicherheitsanforderungen
¶ Best Practices
Separate API-Keys verwenden:
| Umgebung | IP | Endpoint | Bemerkung |
|---|---|---|---|
| Produktion | 203.0.113.42 |
/api/tickets.json |
Spezifische IP, Standard-Endpoint |
| Staging | 0.0.0.0 |
/api/wildcard/tickets.json |
Nur wenn hinter Firewall |
| Entwicklung | 0.0.0.0 |
/api/wildcard/tickets.json |
Pro Entwickler eigener Key |
Vor dem Deployment in Produktion: Plugin deaktivieren (Admin Panel -> Plugins -> API Key Wildcard -> Deaktivieren). Alle Wildcard-Dateien und .htaccess-Änderungen werden automatisch entfernt.
¶ FAQ
¶ Allgemein
F: Modifiziert dieses Plugin osTicket-Core-Dateien?
A: Nein. Das Plugin erstellt einen separaten Endpoint und modifiziert keine Core-Dateien. Standard-API bleibt unverändert.
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: Was passiert beim Deaktivieren?
A: Das Plugin entfernt sauber alle installierten Dateien (/api/wildcard.php) und alle .htaccess-Änderungen. Kein manuelles Aufräumen nötig.
¶ Kompatibilität
F: Welche PHP-Versionen werden unterstützt?
A: PHP 7.4, 8.0, 8.1, 8.2 und 8.3 (getestet in CI).
F: Funktioniert das mit NGINX?
A: Ja, aber benötigt manuelle Konfiguration (siehe Installationsabschnitt). Apache-Setup ist automatisch.
F: Kompatibel mit dem API Endpoints Plugin?
A: Ja, alle erweiterten API-Endpoints funktionieren auch über den Wildcard-Endpoint.
¶ Sicherheit
F: Ist das sicher für Produktion?
A: Nein. Wildcard-API-Keys (0.0.0.0) nur in Entwicklungs-/Testumgebungen 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 Key erstellen, Logs auf verdächtige Aktivitäten prüfen.
¶ Lizenz
GNU General Public License v2, kompatibel mit osTicket Core.
Siehe LICENSE.
¶ Support
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
- Installierte Plugin-Version (Plugin-Konfiguration)
¶ Changelog
Siehe CHANGELOG.md für die vollständige Versionshistorie.