CORS dla TYPO3

Dlaczego projekty Headless-TYPO3 bez prawidłowej konfiguracji CORS natychmiast zawodzą

Gdy system TYPO3 przestaje renderować tylko HTML i zaczyna dostarczać JSON-API do klientów JavaScript na innych domenach, przeglądarka napotyka Same-Origin-Policy. Bez wyraźnych nagłówków Cross-Origin-Resource-Sharing (CORS) blokuje każde wywołanie fetch, które pochodzi z innej origin niż samo API. Dla każdego podejścia Headless-TYPO3, każdej integracji mikroserwisowej i każdej konfiguracji, w której frontend na app.example.com rozmawia z backendem na cms.example.com, porządna konfiguracja CORS jest podstawowym warunkiem. Nie mieści się w pojedynczym rozszerzeniu, lecz jest współdziałaniem middleware TYPO3, konfiguracji serwera i konfiguracji reverse proxy.

Typowe scenariusze zastosowania

Sprzedaż wysyłkowa z 40 000 zamówień miesięcznie prowadzi katalog produktów w TYPO3 i storefront oparty na React na osobnej domenie. Storefront pobiera dane produktów, stany magazynowe i informacje cenowe przez JSON-API, które jest zaimplementowane jako middleware TYPO3. Bez prawidłowych nagłówków CORS przeglądarka blokuje każde wywołanie AJAX z komunikatem “has been blocked by CORS policy” i storefront pozostaje pusty. Rozwiązaniem jest middleware, która precyzyjnie ustawia Access-Control-Allow-Origin na znane domeny frontendowe i prawidłowo odpowiada na preflight OPTIONS-Requests.

Drugim przypadkiem jest firma, która prowadzi TYPO3 jako hub treści dla wielu stron marek. Każda marka ma własną domenę, ale renderuje pewne moduły jak listy newsów lub obrazy produktów po stronie klienta z centralnej instancji TYPO3. CORS musi być tu skonfigurowane tak, żeby wszystkie domeny marek były dozwolone, ale obce już nie. Dynamiczna weryfikacja origin wobec whitelisty w konfiguracji Site TYPO3 jest właściwym podejściem, zamiast ogólnego wildcardu.

Trzeci kontekst to konsorcja naukowe, które pielęgnują bazę danych badawczą w TYPO3 i udostępniają przez otwarte API dostęp dla instytucji badawczych na całym świecie. Polityka CORS jest tu świadomie otwarta, ale musi być połączona z warstwą uwierzytelniania, dzięki czemu wprawdzie każda origin może wywołać API, ale dane wracają tylko z ważnym tokenem.

Architektura techniczna: middleware, PSR-15 i preflight

W TYPO3 v12 i v13 właściwym miejscem dla nagłówków CORS jest middleware PSR-15, która jest wpięta w pipeline request. Sprawdza nagłówek Origin nadchodzącego requestu, porównuje go z skonfigurowaną whitelistą i ustawia odpowiednie nagłówki Access-Control-Allow-Origin, Access-Control-Allow-Methods i Access-Control-Allow-Headers w response. Dla requestów POST, PUT lub DELETE z niestandardowymi nagłówkami przeglądarka najpierw wysyła preflight OPTIONS-Request, na który middleware musi odpowiedzieć bez uwierzytelniania, inaczej właściwe zapytanie zawodzi.

Konfigurację można pielęgnować przez konfigurację Site jako tablicę YAML, alternatywnie bezpośrednio w ext_localconf.php własnego rozszerzenia. Ważne jest, że obsługa credentials (cookies, nagłówek Authorization) działa tylko wtedy, gdy Access-Control-Allow-Credentials jest ustawione na true, a Access-Control-Allow-Origin wskazuje na konkretną origin, a nie na wildcard. Ta kombinacja jest standardem CORS i częstym źródłem błędów przy zespołach, które najpierw testują z wildcardem, a potem chcą doposażyć credentials.

Częste problemy i rozwiązania

Pierwszy problem to podwójne ustawienie nagłówków. Gdy TYPO3 ustawia nagłówek, a Apache lub Nginx dodatkowo ustawia ten sam nagłówek w konfiguracji serwera, do przeglądarki trafiają dwie wartości, a przeglądarka odrzuca request jako błędny. Rozwiązaniem jest zdefiniowanie CORS dokładnie w jednym miejscu, albo w middleware TYPO3, albo na serwerze, i świadome pozostawienie drugiego miejsca pustym. Przy reverse proxies jak Traefik lub Cloudflare dochodzi jeszcze trzecia warstwa, która również może manipulować nagłówkami.

Drugi problem to preflight OPTIONS-Requests. Przeglądarka wysyła OPTIONS-Request, aby sprawdzić przed właściwym wywołaniem, czy metoda jest dozwolona. Middleware TYPO3, które najpierw wykonują uwierzytelnianie, a potem ustawiają nagłówki CORS, odrzucają OPTIONS-Request, bo nie przynosi on nagłówka Authorization. Rozwiązaniem jest wczesne przechwycenie preflight-requests w łańcuchu middleware i odpowiedzenie bez autoryzacji.

Trzeci temat to kombinacja CORS i cache’owania. Reverse proxy jak Varnish cache’uje response z określonymi nagłówkami CORS, a przy następnym wywołaniu z innej origin ten otrzymuje stare nagłówki. Konsekwencją jest, że legalni użytkownicy nagle widzą błędy CORS, bo otrzymują cache’owaną odpowiedź dla innej origin. Nagłówek Vary na Origin rozwiązuje problem, ale zmusza cache do wielu wariantów per zasób.

Migracja i kompatybilność wersji

TYPO3 v11 nie oferowało jeszcze porządnego middleware-API dla wszystkich kontekstów, dzięki czemu konfiguracja CORS była często załatwiana przez hooki lub bezpośrednio na serwerze. Od v12 middleware PSR-15 jest zaplanowanym sposobem, a ścieżka migracji ze starszych instalacji polega na przeniesieniu istniejących manipulacji nagłówków z konfiguracji Apache lub Nginx do middleware TYPO3.

Dla konfiguracji headless w TYPO3 v13 w połączeniu z EXT:headless od Macopedia CORS jest elementarnym budulcem i jest wyraźnie omówione w dokumentacji rozszerzenia. Gosign zrealizował kilka takich projektów headless i w razie potrzeby opiekuje się też uzgadnianiem między zespołami deweloperskimi, które odpowiadają oddzielnie za frontend i backend, dzięki czemu reguły CORS są jednoznacznie udokumentowane i synchronizowane przy każdej zmianie deploymentu. Zła reguła otwiera wektor ataku, w którym złośliwe strony mogą wykonywać akcje w imieniu zalogowanego użytkownika, dlatego porządna whitelista nie jest kwestią komfortu, lecz wymogiem bezpieczeństwa.

Warto też zauważyć, że CORS nie jest substytutem uwierzytelniania. Wiele zespołów deweloperskich konfiguruje hojne reguły CORS w przekonaniu, że dzięki temu API jest bezpieczne, i zapomina, że każda origin, którą przeglądarka zezwala, ma ten sam dostęp co bezpośrednio wywoływany klient. Uwierzytelnianie musi odbywać się niezależnie od CORS przez tokeny, API-keys lub session-cookies, a CORS tylko dba o to, aby przeglądarki w ogóle dopuszczały legalne wywołania do tych uwierzytelnionych endpointów. Kto rozumie to rozdzielenie, konfiguruje reguły CORS znacznie bardziej restrykcyjnie i zamyka wiele niezamierzonych luk.