FastAPI CORS Cross-origin

CORS (Cross-Origin Resource Sharing, intercambio de recursos entre orígenes) es un mecanismo de seguridad que permite o restringe que las páginas web soliciten recursos desde diferentes dominios. Cuando se desarrolla con el front-end y el back-end separados, las páginas del front-end suelen ejecutarse en diferentes dominios o puertos, por lo que es necesario configurar CORS para poder acceder correctamente a la API del back-end.


¿Qué es el problema de cross-origin?

La política del mismo origen del navegador restringe que las páginas web envíen solicitudes a diferentes dominios. Por ejemplo:

Dirección del front-endDirección de la API del back-end¿Es cross-origin?
http://localhost:3000http://localhost:8000Cross-origin (puerto diferente)
http://example.comhttp://api.example.comCross-origin (dominio diferente)
https://example.comhttp://example.comCross-origin (protocolo diferente)
http://example.comhttp://example.com/apiMismo origen (mismo dominio, puerto y protocolo)

Los tres elementos del mismo origen son:Protocolo、Dominio、Puerto, si cualquiera es diferente, es cross-origin.


Configurar CORS

FastAPI usa el CORSMiddleware de StarletteCORSMiddlewarepara manejar el cross-origin:

Ejemplo

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Configurar el middleware CORS
app.add_middleware(
    CORSMiddleware,
    allow_origins=[               # Orígenes permitidos (lista de dominios)
        "http://localhost:3000",   # Servidor de desarrollo del front-end
        "http://localhost:8080",
    ],
    allow_credentials=True,       # Permitir el envío de cookies
    allow_methods=["*"],          # Métodos HTTP permitidos
    allow_headers=["*"],          # Cabeceras de solicitud permitidas
)

@app.get("/")
async def root():
    return {"message": "Hello World"}

Explicación detallada de los parámetros de configuración de CORS

ParámetroTipoDescripciónValor recomendado
allow_originslist[str]Lista de orígenes permitidos para cross-originEn el entorno de producción, usar dominios específicos
allow_methodslist[str]Métodos HTTP permitidos["GET", "POST", "PUT", "DELETE"]
allow_headerslist[str]Cabeceras de solicitud permitidasConfigurar según sea necesario
allow_credentialsboolSi se permiten cookies e información de autenticaciónEstablecer en True cuando se requiera autenticaciónTrue
expose_headerslist[str]Cabeceras de respuesta accesibles para el front-endConfigurar según sea necesario
max_ageintTiempo de caché de las solicitudes de verificación previa (segundos)600

allow_originsUsar["*"]significa permitir todos los orígenes, pero esto es incompatible conallow_credentials=TrueSi necesita enviar cookies, debe especificar orígenes específicos.


Entorno de desarrollo vs Entorno de producción

Entorno de desarrollo

Durante el desarrollo, por conveniencia, se pueden permitir todos los orígenes:

Ejemplo

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Entorno de desarrollo: permitir todos los orígenes (¡solo para desarrollo!)
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],         # Permitir todos los orígenes
    allow_credentials=True,
    allow_methods=["*"],         # Permitir todos los métodos
    allow_headers=["*"],         # Permitir todas las cabeceras de solicitud
)

Entorno de producción

El entorno de producción debe especificar orígenes específicos:

Ejemplo

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Entorno de producción: solo permitir dominios específicos
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "https://example.com",           # Dominio de producción del front-end
        "https://www.example.com",       # Dominio con www
    ],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["Authorization", "Content-Type"],
    max_age=600,                  # Almacenar en caché las solicitudes de verificación previa durante 10 minutos
)

Usar * en el entorno de producciónallow_origins=["*"]es un riesgo de seguridad que puede provocar ataques de falsificación de solicitudes entre sitios (CSRF). Asegúrese de especificar el dominio específico del front-end.


Solicitud de verificación previa de CORS

Antes de enviar ciertas solicitudes cross-origin, el navegador envía primero unaOPTIONSsolicitud de verificación previa (preflight request) para preguntar al servidor si se permite la solicitud real. El middleware CORS maneja automáticamente las solicitudes de verificación previa.

Condiciones para las solicitudes que requieren verificación previa:

  • Se utilizanPUT、DELETEmétodos no simples como
  • Las cabeceras de solicitud contienen campos personalizados (comoAuthorization)
  • Content-Typeno esapplication/x-www-form-urlencoded、multipart/form-dataotext/plain

Al establecermax_age, el navegador almacena en caché el resultado de la verificación previa y no volverá a enviar solicitudes de verificación previa dentro del tiempo especificado, lo que reduce la sobrecarga de red.


Resumen

  • CORS es un mecanismo de seguridad del navegador que debe configurarse al desarrollar con el front-end y el back-end separados
  • UseCORSMiddlewarepara manejar solicitudes cross-origin
  • En el entorno de producción, asegúrese de especificar orígenes específicosallow_origins, no use["*"]
  • allow_credentials=Trueyallow_origins=["*"]incompatible
  • El middleware CORS maneja automáticamente las solicitudes de verificación previa OPTIONS del navegador
Otras extensiones