CORS para TYPO3

Por qué los proyectos TYPO3 headless fracasan sin una configuración CORS correcta

En cuanto un sistema TYPO3 deja de limitarse a renderizar HTML y entrega APIs JSON a clientes JavaScript en otros dominios, el navegador choca con la Same-Origin Policy. Sin cabeceras Cross-Origin Resource Sharing (CORS) explícitas, bloquea toda llamada fetch que provenga de un origen distinto al de la propia API. Para cualquier planteamiento headless de TYPO3, cualquier integración de microservicios y cualquier montaje en el que un frontend en app.example.com hable con un backend en cms.example.com, una configuración CORS limpia es el requisito básico. No pertenece solo a una extensión, es la interacción entre middleware TYPO3, configuración del servidor web y configuración del proxy inverso.

Escenarios típicos de uso

Un comercio electrónico con 40.000 pedidos al mes opera un catálogo de productos en TYPO3 y un storefront basado en React en un dominio independiente. El storefront consulta datos de producto, stock y precios mediante una API JSON implementada como middleware TYPO3. Sin cabeceras CORS correctas, el navegador bloquea cada llamada AJAX con el mensaje “has been blocked by CORS policy” y el storefront se queda vacío. La solución es una middleware que establece Access-Control-Allow-Origin con precisión para los dominios frontend conocidos y responde correctamente a las peticiones OPTIONS preflight.

Un segundo caso es una empresa que opera TYPO3 como content hub para varias webs de marca. Cada marca tiene un dominio propio, pero renderiza ciertos módulos como listados de noticias o imágenes de producto desde el cliente a partir de la instancia central TYPO3. Aquí CORS debe configurarse de forma que todos los dominios de marca sean admisibles, pero no los dominios ajenos. Una comprobación dinámica del origen frente a una whitelist en la Site Configuration de TYPO3 es el enfoque correcto, en lugar de un wildcard indiscriminado.

El tercer contexto son consorcios científicos que mantienen una base de datos de investigación en TYPO3 y ofrecen a centros de investigación de todo el mundo el acceso a través de una API abierta. Aquí la política CORS es deliberadamente abierta, pero debe combinarse con una capa de autenticación, de modo que cualquier origen pueda llamar a la API, pero solo con un token válido obtenga datos de vuelta.

Arquitectura técnica: middleware, PSR-15 y preflight

En TYPO3 v12 y v13 el lugar correcto para las cabeceras CORS es una middleware PSR-15 que se engancha en el pipeline de petición. Comprueba la cabecera Origin de la petición entrante, la compara con una whitelist configurada y establece las cabeceras Access-Control-Allow-Origin, Access-Control-Allow-Methods y Access-Control-Allow-Headers en la respuesta. Para peticiones POST, PUT o DELETE con cabeceras personalizadas, el navegador envía primero una petición OPTIONS preflight, que la middleware debe responder sin autenticación, o de lo contrario la petición real falla.

La configuración puede mantenerse en la Site Configuration como array YAML, o alternativamente directamente en ext_localconf.php de la extensión propia. Es importante que el manejo de credenciales (cookies, cabeceras Authorization) solo funcione si Access-Control-Allow-Credentials está en true y Access-Control-Allow-Origin apunta a un origen concreto, no a un wildcard. Esa combinación es estándar CORS y fuente frecuente de error en equipos que prueban primero con wildcard y quieren añadir credenciales más tarde.

Problemas frecuentes y soluciones

El primer problema es la doble fijación de cabeceras. Si TYPO3 establece una cabecera y Apache o Nginx, además, fija la misma cabecera en la configuración del servidor web, llegan dos valores al navegador, que rechaza la petición como errónea. La solución es definir CORS en un único lugar, o en la middleware de TYPO3 o en el servidor web, y dejar deliberadamente vacío el otro sitio. En proxies inversos como Traefik o Cloudflare se suma una tercera capa que también puede manipular cabeceras.

El segundo problema son las peticiones OPTIONS preflight. El navegador envía una petición OPTIONS para comprobar, antes de la llamada real, si el método está permitido. Las middlewares TYPO3 que primero realizan una autenticación y luego fijan las cabeceras CORS rechazan la petición OPTIONS porque no lleva cabecera Authorization. La solución es interceptar las peticiones preflight pronto en la cadena de middleware y responder sin autenticación.

El tercer tema es la combinación de CORS y caching. Un proxy inverso como Varnish cachea una respuesta con determinadas cabeceras CORS, y al siguiente acceso desde otro origen, este recibe las antiguas cabeceras. La consecuencia es que usuarios legítimos ven de repente errores CORS porque reciben una respuesta cacheada para otro origen. Una cabecera Vary sobre Origin resuelve el problema, pero obliga al caché a guardar varias variantes por recurso.

Migración y compatibilidad de versiones

TYPO3 v11 todavía no ofrecía una API de middleware limpia para todos los contextos, de modo que la configuración CORS se gestionaba a menudo mediante hooks o directamente en el servidor web. A partir de v12 la middleware PSR-15 es el camino previsto, y la ruta de migración desde instalaciones más antiguas consiste en trasladar las manipulaciones de cabeceras existentes desde la configuración de Apache o Nginx a la middleware de TYPO3.

Para montajes headless en TYPO3 v13 en combinación con EXT:headless de Macopedia, CORS es un componente elemental y se trata explícitamente en la documentación de la extensión. Gosign ha implementado varios de esos proyectos headless y, cuando hace falta, coordina también entre equipos de desarrollo que asumen frontend y backend por separado, de modo que las reglas CORS estén documentadas de forma inequívoca y se sincronicen en cada cambio de despliegue. Una regla errónea abre un vector de ataque en el que webs maliciosas pueden ejecutar acciones en nombre del usuario identificado, por lo que una whitelist limpia no es un asunto de comodidad, sino un requisito de seguridad.

Hay que recordar además que CORS no es un sustituto de la autenticación. Muchos equipos de desarrollo configuran reglas CORS generosas suponiendo que así la API está segura y olvidan que todo origen permitido por el navegador tiene el mismo acceso que un cliente llamado directamente. La autenticación debe realizarse con independencia de CORS mediante tokens, API keys o cookies de sesión, y CORS solo se ocupa de que el navegador permita siquiera llamadas legítimas a esos endpoints autenticados. Quien entiende esa separación configura reglas CORS mucho más restrictivas y cierra muchas grietas no intencionadas.