Solución Definitiva Error CORS Preflight Method Not Allowed y Origin Header en APIs REST

Introducción al Problema de Cors Preflight y Cabeceras Origin

En el ecosistema del desarrollo web moderno, la arquitectura desacoplada donde el frontend (ej. React, Vue, Angular) se comunica con un backend independiente (Node.js, Python, Go) a través de APIs REST o GraphQL es el estándar de la industria. Sin embargo, esta separación física o lógica expone inevitablemente a las aplicaciones a las restricciones impuestas por los navegadores web modernos bajo la política de seguridad conocida como CORS (Cross-Origin Resource Sharing).

Uno de los escenarios más frustrantes para los desarrolladores full-stack ocurre cuando una petición HTTP compleja (como PUT, DELETE, o POST con cabeceras personalizadas como Authorization o Content-Type: application/json) falla silenciosamente o arroja un error en la consola del navegador indicando que el método HTTP no está permitido durante la solicitud preliminar o Preflight Request (método OPTIONS).

Este artículo técnico aborda las causas fundamentales de estos bloqueos por parte del navegador y detalla una metodología exhaustiva de depuración y corrección a nivel de servidor y proxy inverso para garantizar la interoperabilidad segura y fluida de tus servicios web.

Análisis Profundo de las Causas del Error Preflight

Para solucionar eficazmente cualquier fallo relacionado con CORS, es imperativo comprender el ciclo de vida de una petición de origen cruzado. Los navegadores implementan el mecanismo CORS para proteger a los usuarios de ataques de falsificación de peticiones y robos de datos sensibles. Las causas principales que desencadenan errores de Method Not Allowed o rechazos en la cabecera Access-Control-Allow-Origin son:

• Ausencia de manejo para el método OPTIONS: El navegador envía automáticamente una solicitud HTTP OPTIONS antes de la petición real para consultar al servidor si este acepta el origen, los métodos y las cabeceras personalizadas. Si el servidor responde con un código 404 o 405, la cadena se rompe.
• Cabeceras de respuesta faltantes o restrictivas: El servidor omite enviar Access-Control-Allow-Methods o Access-Control-Allow-Headers en la respuesta preflight.
• Credenciales y comodines incompatibles: El uso de Access-Control-Allow-Credentials: true combinando un origen comodín (*) en lugar de especificar el dominio exacto del cliente.
• Intercepción errónea por proxies inversos: Herramientas como Nginx o Apache interceptan las solicitudes OPTIONS y devuelven respuestas estáticas antes de que lleguen a la aplicación backend.

Métodos de Solución Avanzados Paso a Paso

Método 1: Configuración Robusta en Node.js con Express y el Middleware CORS

Si tu API está construida sobre Node.js utilizando Express, la forma más limpia de gestionar las solicitudes preflight y las políticas de origen es configurar explícitamente el paquete cors con opciones granulares.

1. Instala el paquete oficial en la raíz de tu proyecto ejecutando el siguiente comando en tu terminal:

   npm install cors

2. Implementa la configuración avanzada en tu archivo principal de servidor (ej. app.js o server.js):

   const express = require('express');
   const cors = require('cors');
   const app = express();
   
   const whitelist = ['https://tudominiofrontend.com', 'http://localhost:3000'];
   const corsOptions = {
     origin: function (origin, callback) {
       if (whitelist.indexOf(origin) !== -1 || !origin) {
         callback(null, true);
       } else {
         callback(new Error('Bloqueado por la política CORS'));
       }
     },
     methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
     allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
     credentials: true,
     optionsSuccessStatus: 200
   };
   
   app.use(cors(corsOptions));
   // Asegúrate de manejar explícitamente las opciones si es necesario
   app.options('*', cors(corsOptions));
   
   app.get('/api/recurso', (req, res) => {
     res.json({ mensaje: 'Acceso concedido mediante CORS correctamente' });
   });
   
   app.listen(5000, () => {
     console.log('Servidor corriendo en puerto 5000');
   });

Método 2: Configuración a Nivel de Proxy Inverso con Nginx

En arquitecturas de producción donde Nginx actúa como pasarela frente a servicios backend (como Python/Django, Ruby on Rails o microservicios), es fundamental interceptar y responder adecuadamente a las peticiones OPTIONS directamente desde Nginx para evitar sobrecargar el backend.

1. Abre el archivo de configuración de tu servidor virtual en Nginx (habitualmente en /etc/nginx/sites-available/default o tu archivo personalizado).
2. Modifica el bloque de ubicación (location) para interceptar el método OPTIONS y añadir las cabeceras CORS requeridas antes de redirigir o finalizar la respuesta:

   server {
       listen 80;
       server_name api.tudominio.com;
   
       location / {
           if ($request_method = 'OPTIONS') {
               add_header 'Access-Control-Allow-Origin' 'https://tudominiofrontend.com' always;
               add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always;
               add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, Accept, X-Requested-With' always;
               add_header 'Access-Control-Max-Age' 1728000 always;
               add_header 'Content-Type' 'text/plain charset=UTF-8' always;
               add_header 'Content-Length' 0 always;
               return 204;
           }
   
           proxy_pass http://localhost:5000;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection 'upgrade';
           proxy_set_header Host $host;
           proxy_cache_bypass $http_upgrade;
           
           # Propagar cabeceras CORS en respuestas reales
           add_header 'Access-Control-Allow-Origin' 'https://tudominiofrontend.com' always;
           add_header 'Access-Control-Allow-Credentials' 'true' always;
       }
   }

3. Verifica la sintaxis de la configuración ejecutando:

   sudo nginx -t

4. Recarga el servicio para aplicar los cambios:

   sudo systemctl reload nginx

Método 3: Gestión de Cabeceras CORS en APIs Serverless (AWS Lambda / API Gateway)

Cuando despliegas funciones serverless, el error CORS suele manifestarse porque API Gateway no está configurado para retornar las cabeceras HTTP en las respuestas de tipo de integración mock o proxy.

1. Accede a la consola de AWS API Gateway y selecciona tu recurso API.
2. Habilita CORS utilizando la opción nativa provista por la consola seleccionando el recurso y haciendo clic en Enable CORS.
3. Define los métodos permitidos (ej. GET,POST,OPTIONS) y en los orígenes permitidos especifica la URL exacta de tu aplicación cliente (evita usar * si manejas tokens de autorización basados en cookies o cabeceras seguras).
4. Despliega nuevamente la API (Deploy API) hacia tu etapa (Stage) correspondiente para que los cambios surtan efecto inmediato en la infraestructura perimetral de Amazon Web Services.

Buenas Prácticas de Seguridad y Diagnóstico Continuo

Para finalizar, recuerda que el uso de comodines (*) en entornos de producción donde se manejan datos sensibles de usuarios representa un vector de riesgo elevado. Valida siempre que tu código del lado del cliente gestione adecuadamente los interceptores de red (como en Axios o Fetch API) para capturar códigos de error HTTP 4xx y 5xx derivados de configuraciones erróneas de origen cruzado. Utiliza las herramientas de desarrollo de tu navegador (Network Tab) para inspeccionar minuciosamente las cabeceras Access-Control-Request-Method enviadas por el cliente frente a las cabeceras Access-Control-Allow-Methods devueltas por el servidor.