IllusionCMS
DE
Handbuch · 15

Konto, Sicherheit und API-Tokens

Benutzer

Unter Einstellungen → Benutzer legst du weitere Konten an. Alle Konten sind Admins mit vollem Zugriff; eine Rechteverwaltung gibt es bewusst nicht.

  • Konto anlegen: Benutzername und Passwort (mindestens 8 Zeichen) – die Zugangsdaten gibst du der Person auf sicherem Weg weiter.
  • Passwort setzen: Für vergessene Passwörter. Das Konto wird dabei auf allen Geräten abgemeldet.
  • Löschen: Meldet das Konto sofort ab; Inhalte bleiben erhalten. Das eigene und das letzte Konto lassen sich nicht löschen.
  • Die Liste zeigt, wann sich jemand zuletzt angemeldet hat.

Darstellung und Sprache

Ganz unten im Hauptmenü – und auf der Anmeldeseite oben rechts:

  • Darstellung (die drei Symbole Sonne, Mond, Bildschirm): Hell, Dunkel oder System (Standard – folgt der Hell/Dunkel-Einstellung des Betriebssystems und wechselt mit ihr), Hell oder Dunkel. Workflow-Editor, Statistik und Weltkarte passen sich an. Die Code-Editoren bleiben in beiden Varianten dunkel, wie man es aus Entwicklungsumgebungen kennt – so bleibt die Syntax-Hervorhebung gut lesbar. Die Vorschau deiner Website bleibt, wie die Website selbst aussieht.
  • Sprache der Oberfläche (Klick auf die Flagge): Browsersprache (Standard) oder fest Englisch, Deutsch, Französisch, Italienisch oder Spanisch. Wird die Browsersprache nicht unterstützt, erscheint Englisch.

Beides gilt für diesen Browser (gespeichert im Browser, nicht im Konto) – auf einem anderen Rechner stellst du es dort ein. Die Sprache der Oberfläche hat nichts mit der Sprache deiner Website-Inhalte zu tun.

Anmeldung

  • Passwort ändern: Einstellungen → Mein Konto.
  • Login-Schutz: Nach 10 Fehlversuchen von derselben IP-Adresse sind Logins für 15 Minuten gesperrt.
  • Sitzungen gelten 14 Tage.

API-Tokens

Für externe Programme (Sync-Skripte, Headless-Frontends, Automatisierungen) legst du unter Einstellungen → API-Tokens einen Token an:

  • Nur lesen – darf Inhalte abrufen.
  • Lesen + schreiben – darf Inhalte anlegen und ändern, aber keine Tokens oder Passwörter verwalten.

Der Token wird nur einmal angezeigt. Verwendung: Header Authorization: Bearer <token>, bei einfachen GET-Abrufen auch als URL-Parameter ?token=<token> (landet dann aber in Verlauf und Server-Logs – am besten einen Nur-Lese-Token nehmen). Widerrufen sperrt ihn sofort. Alle Endpunkte stehen in der API-Dokumentation.

Integrationen und atomare Änderungen

Programme, die IllusionCMS über die API pflegen (z. B. IllusionPublish, n8n oder eigene Skripte), speichern mehrere Änderungen an Seiten, Einträgen, globalen Blöcken, Snippets und Dateien mit POST /batch auf einmal: Entweder klappt alles oder nichts wird geändert – auch dann, wenn jemand zwischendurch eine der betroffenen Seiten bearbeitet hat. Mit einem Idempotenz-Schlüssel lässt sich ein Batch gefahrlos wiederholen, ohne dass etwas doppelt angelegt wird. Schreibt ein Token im Auftrag einer Person (Header X-IC-On-Behalf-Of), steht in der Versionshistorie z. B. Token „Publish“ – im Auftrag von Maria Muster. GET /schema liefert Collections, Bausteine, Sprachen und Websites in einer Antwort. Details stehen in der API-Dokumentation. Von Änderungen erfahren solche Programme über Webhooks.

Webhooks

Webhooks benachrichtigen andere Programme, sobald sich etwas ändert: IllusionCMS schickt dann einen POST mit einer JSON-Beschreibung der Änderung an eine Adresse – etwa an n8n, an einen Dienst, der eine statische Website neu baut, an IllusionPublish oder an einen HTTP-Eingang eines eigenen Workflows.

Webhook einrichten

Unter Einstellungen → Webhooks legst du mit + Webhook einen an: Name (optional), Adresse (http:// oder https://), die gewünschten Ereignisse und Aktiv. Das Feld für das Secret lässt du leer – IllusionCMS erzeugt dann eins und zeigt es genau einmal an. Kopiere es und hinterlege es beim Empfänger. Später kannst du unter Bearbeiten ein Neues Secret erzeugen (das alte gilt sofort nicht mehr) oder ein eigenes eintragen (mindestens 16 Zeichen).

  • Das Secret liegt nur verschlüsselt in der Datenbank – wie das S3-Secret. Ziehst du die Datenbank auf einen anderen Server um, nimm IC_ENCRYPTION_KEY bzw. data/secret.key mit (siehe Medien in S3 speichern).
  • Webhooks gehören zur Instanz, nicht zum Inhalt: Sie stehen nicht im Bundle. Im Remote-Modus bearbeitest du die Webhooks des Servers.
  • Höchstens 20 Webhooks; inaktive bekommen nichts (außer Test senden).

Webhook-Ereignisse

  • content.changed – Seiten, Einträge, globale Blöcke, Dateien, Snippets oder CSS/JS wurden angelegt, geändert, verschoben oder gelöscht, auch durch Import, Bundle, CSV-Import oder einen Batch. Änderungen innerhalb von etwa 2 Sekunden kommen als eine Zustellung – wer zehn Einträge speichert, löst also nicht zehnmal einen Build aus.
  • schema.changed – eine Collection wurde angelegt, geändert oder gelöscht, oder ein Baustein-Schema hat sich geändert. Mit dabei ist die aktuelle schema_version aus GET /schema.
  • batch.applied – ein POST /batch wurde angewendet, mit dessen Ergebnissen.

So sieht eine Zustellung aus:

{ "event": "content.changed", "at": 1791572100,
  "changes": [ { "kind": "page", "action": "updated", "id": 12 },
               { "kind": "item", "action": "created", "id": 31, "collection": "blog" } ] }

Alle Formate stehen in der API-Dokumentation.

Signatur prüfen

Jede Zustellung trägt den Header X-IC-Signature: sha256=… – einen HMAC-SHA256 des Bodys mit deinem Secret. Der Empfänger rechnet ihn nach und verwirft alles, was nicht passt; so kann niemand gefälschte Ereignisse einschleusen. Wichtig: über den unveränderten Body rechnen, nicht über neu erzeugtes JSON. In Node.js: Zusätzlich senden wir X-IC-Timestamp und X-IC-Signature-V2 (HMAC über Zeitstempel.Body); wer will, lehnt Zustellungen mit einem Zeitstempel älter als 5 Minuten ab (Schutz vor Wiedereinspielen). Die Antwort des Empfängers erscheint nicht im Zustellprotokoll, nur der Statuscode.

const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
const ok = expected.length === header.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header))

Ein vollständiges Beispiel in JavaScript und Go steht in der API-Dokumentation. Weitere Header: X-IC-Event (Ereignis) und X-IC-Delivery (eindeutige ID, bei Wiederholungen gleich – damit erkennst du doppelte Zustellungen). Workflows dieser Instanz können die Signatur nicht prüfen (der Function-Node kennt kein HMAC).

Testen und Zustellungen

  • Test senden schickt sofort ein Ereignis ping und zeigt das Ergebnis an – HTTP-Status und Dauer oder den Fehler.
  • Zustellungen zeigt die letzten 50 Zustellungen seit dem Serverstart: Zeit, Ereignis, Status (zugestellt, fehlgeschlagen, läuft, übersprungen), HTTP-Status, Dauer, Versuche und Fehler samt Anfang der Antwort. Nach einem Neustart ist die Liste leer.
  • Antwortet der Empfänger nicht innerhalb von 10 Sekunden, mit 408, 429 oder 5xx, versucht IllusionCMS es bis zu dreimal erneut (nach 2, 10 und 30 Sekunden). Andere Antworten wie 404 werden nicht wiederholt; jede 2xx-Antwort gilt als zugestellt.
  • Schleifenschutz: Ruft ein Webhook einen eigenen Workflow auf, der wieder Inhalte ändert, würde sich das endlos wiederholen. Nach drei Zustellungen hintereinander ist deshalb Schluss – weitere stehen als übersprungen im Protokoll.
  • Zum Ausprobieren ohne externen Dienst: ein Workflow mit öffentlichem HTTP-Eingang (POST), der msg.payload mit store.set(…) im Speicher ablegt, und ein Webhook auf dessen Adresse – so macht es auch der Test-Seed.

Sicherheits-Header

Unter Einstellungen → Sicherheit legst du fest, welche Schutz-Header IllusionCMS mitschickt. Die Einstellungen gelten nur für diese Instanz und sind nicht im Bundle, lokal und live stellst du sie also getrennt ein. Die Tabelle Gesendete Header zeigt das Ergebnis.

Einstellung Vorgabe Wirkung
X-Content-Type-Options: nosniff immer an Browser raten keinen Dateityp, ein hochgeladenes Bild wird z. B. nie als Skript ausgeführt
Referrer Standard Fremde Websites sehen beim Klick auf einen Link nur deine Domain, nicht die genaue Seite
Einbetten (iframe) Nur eigene Seiten Schützt vor Clickjacking: Fremde Seiten können deine nicht unsichtbar einbetten. Bestimmte Domains erlaubt es z. B. einem Partner (https://partner.de, *.partner.de), Überall erlaubt schaltet den Schutz ab
Browser-Funktionen sperren aus Sperrt Kamera, Mikrofon, Standort, Zahlungen, USB/Bluetooth u. a. Aus lassen, wenn eine Seite z. B. „Mein Standort“ in einer Karte nutzt
HSTS aus Browser rufen die Website nur noch über HTTPS auf. Wird nur über HTTPS gesendet, auch hinter einem Proxy, der X-Forwarded-Proto: https setzt. Achtung: Browser merken sich das für die eingestellte Dauer, auch wenn du HSTS wieder abschaltest. Erst einschalten, wenn HTTPS dauerhaft läuft, und zum Ausprobieren mit 5 Minuten anfangen
Content-Security-Policy leer Eigene Regeln, woher Skripte, Bilder, Schriften … geladen werden dürfen. Mit Nur melden blockiert der Browser nichts, sondern meldet Verstöße in der Konsole. So testest du eine Regel, bevor du sie scharf schaltest
Version in /healthz verbergen aus Besucher sehen nur noch {"status":"ok"}. Angemeldete und API-Tokens sehen die Version weiterhin (die Versionsanzeige im Admin funktioniert also)

Einbetten, Browser-Funktionen und die CSP gelten für die Website-Seiten (Seiten, 404, Sitemap, robots.txt), nicht für das Admin, die API, Dateien und CSS/JS. Die Admin-Vorschau ist davon nicht betroffen.

Was du wissen solltest

  • HTML, CSS und JS sind vertrauenswürdig. Wer im Admin arbeitet, kann beliebigen Code auf die Website bringen – vergib Zugänge und Schreib-Tokens entsprechend.
  • Markdown-Felder geben kein eingebettetes HTML aus; Collection-Einträge, die per API von außen kommen, können so keinen Code einschleusen.
  • Hochgeladene SVGs werden mit einer Sicherheitsrichtlinie ausgeliefert, die eingebettete Skripte blockiert. Hochgeladene HTML-, XML- und Dateien mit unbekannter Endung werden ohne Skriptausführung und als Download ausgeliefert (Sandbox-Richtlinie, kein Typ-Raten) – sie lassen sich weiterhin hochladen und verlinken, laufen aber nicht als Seite im Ursprung des Admins.