CORS für TYPO3

Warum Headless-TYPO3-Projekte ohne korrekte CORS-Konfiguration sofort scheitern

Sobald ein TYPO3-System nicht mehr nur HTML rendert, sondern JSON-APIs an JavaScript-Clients auf anderen Domains ausliefert, stößt der Browser an die Same-Origin-Policy. Ohne explizite Cross-Origin-Resource-Sharing-Header (CORS) blockiert er jeden Fetch-Aufruf, der von einer anderen Origin stammt als der API selbst. Für jeden Headless-TYPO3-Ansatz, jede Microservice-Integration und jedes Setup, bei dem ein Frontend auf app.example.com mit einem Backend auf cms.example.com spricht, ist eine saubere CORS-Konfiguration die Grundvoraussetzung. Sie gehört nicht in eine Extension allein, sondern ist ein Zusammenspiel aus TYPO3-Middleware, Webserver-Konfiguration und Reverse-Proxy-Setup.

Typische Einsatzszenarien

Ein Versandhandel mit 40.000 Bestellungen pro Monat betreibt einen Produktkatalog in TYPO3 und ein React-basiertes Storefront auf einer separaten Domain. Das Storefront fragt Produktdaten, Lagerbestand und Preisinformationen über eine JSON-API ab, die als TYPO3-Middleware implementiert ist. Ohne korrekte CORS-Header blockiert der Browser jeden AJAX-Call mit der Fehlermeldung “has been blocked by CORS policy”, und das Storefront bleibt leer. Die Lösung ist eine Middleware, die Access-Control-Allow-Origin präzise auf die bekannten Frontend-Domains setzt und Preflight-OPTIONS-Requests korrekt beantwortet.

Ein zweiter Fall ist ein Unternehmen, das TYPO3 als Content-Hub für mehrere Marken-Websites betreibt. Jede Marke hat eine eigene Domain, rendert aber bestimmte Module wie News-Listings oder Produktbilder clientseitig aus der zentralen TYPO3-Instanz nach. CORS muss hier so konfiguriert sein, dass alle Marken-Domains zulässig sind, fremde Domains aber nicht. Eine dynamische Origin-Prüfung gegen eine Whitelist in der TYPO3-Site-Konfiguration ist der richtige Ansatz, statt eines pauschalen Wildcards.

Der dritte Kontext sind Wissenschafts-Konsortien, die eine Forschungsdatenbank in TYPO3 pflegen und über eine offene API Forschungseinrichtungen weltweit den Zugriff ermöglichen. Hier ist die CORS-Policy bewusst offen, muss aber mit einer Authentifizierungsschicht kombiniert werden, sodass zwar jede Origin die API aufrufen darf, aber nur mit einem gültigen Token Daten zurückkommen.

Technische Architektur: Middleware, PSR-15 und Preflight

In TYPO3 v12 und v13 ist der korrekte Ort für CORS-Header eine PSR-15-Middleware, die in die Request-Pipeline eingehängt wird. Sie prüft den Origin-Header des eingehenden Requests, vergleicht ihn mit einer konfigurierten Whitelist und setzt die passenden Access-Control-Allow-Origin-, Access-Control-Allow-Methods- und Access-Control-Allow-Headers-Header in die Response. Für POST-, PUT- oder DELETE-Requests mit Custom-Headern sendet der Browser zunächst einen OPTIONS-Preflight-Request, den die Middleware ohne Authentifizierung beantworten muss, sonst scheitert die eigentliche Anfrage.

Die Konfiguration lässt sich über die Site-Konfiguration als YAML-Array pflegen, alternativ direkt im ext_localconf.php der eigenen Extension. Wichtig ist, dass Credentials-Handling (Cookies, Authorization-Header) nur funktioniert, wenn Access-Control-Allow-Credentials auf true gesetzt ist und Access-Control-Allow-Origin auf eine konkrete Origin zeigt, nicht auf ein Wildcard. Diese Kombination ist CORS-Standard und häufige Fehlerquelle bei Teams, die zuerst mit Wildcard testen und dann später Credentials nachrüsten wollen.

Häufige Probleme und Lösungen

Das erste Problem ist die doppelte Header-Setzung. Wenn TYPO3 einen Header setzt und Apache oder Nginx zusätzlich denselben Header in der Webserver-Konfiguration setzt, landen zwei Werte beim Browser, der den Request als fehlerhaft ablehnt. Die Lösung ist, CORS an genau einer Stelle zu definieren, entweder in der TYPO3-Middleware oder im Webserver, und die jeweils andere Stelle bewusst leer zu halten. Bei Reverse-Proxies wie Traefik oder Cloudflare kommt noch eine dritte Schicht hinzu, die ebenfalls Header manipulieren kann.

Das zweite Problem sind Preflight-OPTIONS-Requests. Der Browser sendet einen OPTIONS-Request, um vor dem eigentlichen Aufruf zu prüfen, ob die Methode erlaubt ist. TYPO3-Middlewares, die erst eine Authentifizierung durchführen und dann CORS-Header setzen, lehnen den OPTIONS-Request ab, weil er keinen Authorization-Header mitbringt. Die Lösung ist, Preflight-Requests in der Middleware-Kette früh abzufangen und ohne Auth zu beantworten.

Das dritte Thema ist die Kombination aus CORS und Caching. Ein Reverse-Proxy wie Varnish cached eine Response mit bestimmten CORS-Headern, und beim nächsten Aufruf von einer anderen Origin bekommt dieser die alten Header. Die Konsequenz ist, dass legitime Nutzer plötzlich CORS-Fehler sehen, weil sie eine gecachte Antwort für eine andere Origin erhalten. Ein Vary-Header auf Origin löst das Problem, zwingt aber den Cache zu mehreren Varianten pro Ressource.

Migration und Versions-Kompatibilität

TYPO3 v11 bot noch keine saubere Middleware-API für alle Kontexte, sodass CORS-Konfiguration häufig über Hooks oder direkt im Webserver abgewickelt wurde. Ab v12 ist die PSR-15-Middleware der vorgesehene Weg, und der Migrationspfad von älteren Installationen besteht darin, vorhandene Header-Manipulationen aus der Apache- oder Nginx-Config in die TYPO3-Middleware zu verlagern.

Für Headless-Setups in TYPO3 v13 in Kombination mit der EXT:headless von Macopedia ist CORS ein elementarer Baustein und wird in der Extension-Dokumentation explizit behandelt. Gosign hat mehrere solcher Headless-Projekte realisiert und betreut bei Bedarf auch die Abstimmung zwischen Entwicklungsteams, die Frontend und Backend getrennt verantworten, sodass CORS-Regeln eindeutig dokumentiert sind und bei jeder Deployment-Änderung synchronisiert werden. Eine falsche Regel öffnet einen Angriffsvektor, in dem bösartige Websites im Namen des eingeloggten Nutzers Aktionen ausführen können, weshalb eine saubere Whitelist kein Komfort-Thema ist, sondern Sicherheitsanforderung.

Zu beachten ist außerdem, dass CORS kein Ersatz für Authentifizierung ist. Viele Entwickler-Teams konfigurieren großzügige CORS-Regeln in der Annahme, damit sei die API sicher, und vergessen, dass jede Origin, die der Browser erlaubt, denselben Zugriff hat wie ein direkt aufgerufener Client. Authentifizierung muss unabhängig von CORS über Tokens, API-Keys oder Session-Cookies erfolgen, und CORS sorgt lediglich dafür, dass Browser legitime Aufrufe an diese authentifizierten Endpunkte überhaupt zulassen. Wer diese Trennung versteht, konfiguriert CORS-Regeln deutlich restriktiver und schließt viele unbeabsichtigte Lücken.