Tutoriales de VPS
Errores CORS en Nginx: preflight, cabeceras y login con cookies
Identifica OPTIONS o petición real fallida, elige un responsable CORS y origen exacto y verifica errores, credenciales y login en el navegador.

La API devuelve JSON con curl, pero el navegador muestra blocked by CORS policy. Empieza en Network: comprueba si falla OPTIONS o la petición real posterior y revisa las cabeceras. Cambiar de servidor o poner asteriscos no identifica la capa responsable.
El ejemplo separa frontend https://app.example.com y API https://api.example.com. Solo permite un origen explícito; adapta dominios, rutas y puerto del backend.
La guía de MDN explica cómo el navegador controla la lectura de respuestas por scripts de otro origen. Cambiar protocolo, hostname o puerto puede cambiar el origen, incluso entre subdominios.
Una respuesta de curl no demuestra que JavaScript pueda leerla. Un 502, error de certificado o conexión requiere corregir ese fallo además de las cabeceras.
| Síntoma | Primera comprobación | Capa responsable |
|---|---|---|
| OPTIONS con 401/403 | Autenticación o WAF bloquean preflight | Gateway o middleware |
| OPTIONS con 301/302 | HTTPS, barra final o login | URL y reglas de proxy |
| Falta Allow-Origin | La capa que responde no lo añade | Aplicación, Nginx o CDN |
| Varios Allow-Origin | Dos capas duplican cabeceras | Elegir un responsable |
| Falla con Cookie | Origen comodín o credenciales | Frontend y servidor |
| Solo los errores parecen CORS | Respuestas de error sin cabeceras | Gestión de errores |
Registra Request URL, Origin, estado y respuesta. Oculta Cookie y Authorization antes de compartir. Conserva autenticación y defensa CSRF: CORS no impide llamadas directas con curl.
Un POST JSON o Authorization suele activar preflight. El navegador consulta origen, método y cabeceras antes de enviar la petición real; consulta MDN. Simúlalo en tu terminal:
curl -i -X OPTIONS 'https://api.example.com/api/profile' \
-H 'Origin: https://app.example.com' \
-H 'Access-Control-Request-Method: POST' \
-H 'Access-Control-Request-Headers: authorization,content-type'
No necesita token real ni Cookie. Comprueba:
Access-Control-Allow-Origincoincide con el origen completo del frontend.Access-Control-Allow-Methodsincluye POST.Access-Control-Allow-Headersincluye las cabeceras reales.
204 es frecuente, pero debe acompañarse de cabeceras correctas. Aumentar el timeout no soluciona 403 y añadir Allow: OPTIONS no completa la autorización CORS. Comprueba también la respuesta al POST.
Si redirige a HTTP, login u otro dominio, solicita directamente la URL final. Consulta bucles de redirección.
Decide quién gestiona CORS. Si el framework ya tiene middleware, utilízalo y elimina duplicados de Nginx, panel y CDN. La alternativa siguiente asigna /api/ a Nginx, manteniendo la autenticación del backend.
Integra el location en el servidor HTTPS existente de la API. Conserva certificados y otros ajustes. Se supone backend en 127.0.0.1:3000 que necesita la ruta /api/:
location /api/ {
proxy_hide_header Access-Control-Allow-Origin;
proxy_hide_header Access-Control-Allow-Methods;
proxy_hide_header Access-Control-Allow-Headers;
proxy_hide_header Access-Control-Allow-Credentials;
add_header Access-Control-Allow-Origin "https://app.example.com" always;
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
if ($request_method = OPTIONS) {
return 204;
}
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_pass http://127.0.0.1:3000;
}
Límites del ejemplo:
- El origen no incluye ruta ni barra final.
http://localhost:5173de desarrollo es otro origen; consulta origen no coincidente. - Permite solo métodos y cabeceras necesarios. Añade PATCH, DELETE o campos personalizados cuando corresponda. No sustituye la validación del backend.
- Nginx responde OPTIONS y envía peticiones normales al backend. Si OPTIONS tiene otro uso de negocio, la aplicación debe distinguirlo.
proxy_passno tiene barra final y conserva/api/. No cambies el mapeo de rutas al corregir CORS.
La documentación de cabeceras Nginx explica always, para incluirlas también en respuestas de error. De lo contrario, JavaScript puede no leer un 401 o 500 real.
Revisa la herencia de add_header: definir cabeceras en este nivel puede alterar las de seguridad heredadas. Comprueba la salida final. proxy_hide_header elimina las del upstream en esta solución gestionada por Nginx; no copies esa eliminación si CORS pertenece a la aplicación.
Comprueba sintaxis antes de cargar:
sudo nginx -t
sudo systemctl reload nginx
Una CDN, WAF o gateway anterior puede bloquear OPTIONS antes de llegar aquí. Permite preflight válido solo en rutas correspondientes y sigue autenticando peticiones reales.
Para cookies entre orígenes, el frontend suele necesitar modo de credenciales explícito:
fetch("https://api.example.com/api/profile", {
credentials: "include"
});
El servidor necesita origen específico y Access-Control-Allow-Credentials: true. En la solución Nginx, añade junto a add_header dentro del mismo location:
add_header Access-Control-Allow-Credentials "true" always;
No combina con Access-Control-Allow-Origin: *, según la explicación de MDN. No actives credenciales en APIs que no las necesitan.
El envío de cookies también depende de Domain, Path, Secure, SameSite y políticas de terceros. Entre orígenes no siempre significa entre sitios: dos subdominios no exigen automáticamente SameSite=None. Cookies realmente entre sitios implican Secure y restricciones del navegador. Si CORS funciona pero el login no, revisa cookies y sesiones en vez de ampliar orígenes.
mode: "no-cors" no permite leer una API entre orígenes. Produce una respuesta opaque sin acceso normal a estado y JSON; consulta Fetch.
No reflejes cualquier Origin con credenciales. Varios frontends fiables requieren una lista exacta. Al seleccionar el origen dinámicamente, configura Vary: Origin para separar respuestas en caché.
No añadas Allow-Origin en aplicación, Nginx y CDN a la vez. Duplicados o listas separadas por comas no permiten varios orígenes, según MDN. Revisa la respuesta final.
Prueba OPTIONS y petición real del origen permitido y después un origen ajeno. Con este valor fijo, preflight ajeno puede devolver 204, pero Allow-Origin no coincide y el navegador no permite leer. No es una política de rechazo 403 del servidor.
Comprueba respuesta sin login y error controlado para confirmar una sola configuración CORS. Finalmente prueba login y operación reales en el navegador. curl observa cabeceras, sin ejecutar políticas de CORS, cookies o caché.
El artículo original probó ocho combinaciones con Nginx 1.19.6 y backend simulado en loopback. OPTIONS permitido dio 204 y GET/POST 200; respuestas 401 y 500 mantuvieron un Allow-Origin. Orígenes ajenos no coincidían. Con credenciales, OPTIONS y GET incluían true. OPTIONS no llegó al backend. Se verificaron cabeceras HTTP, sin TLS de producción, sesión real ni bloqueo efectivo del navegador.
Para FastAPI, consulta despliegue y CORS. Localiza la petición fallida y una sola capa responsable de las cabeceras antes de modificar reglas.