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-end | Dirección de la API del back-end | ¿Es cross-origin? |
|---|---|---|
http://localhost:3000 | http://localhost:8000 | Cross-origin (puerto diferente) |
http://example.com | http://api.example.com | Cross-origin (dominio diferente) |
https://example.com | http://example.com | Cross-origin (protocolo diferente) |
http://example.com | http://example.com/api | Mismo 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.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ámetro | Tipo | Descripción | Valor recomendado |
|---|---|---|---|
allow_origins | list[str] | Lista de orígenes permitidos para cross-origin | En el entorno de producción, usar dominios específicos |
allow_methods | list[str] | Métodos HTTP permitidos | ["GET", "POST", "PUT", "DELETE"] |
allow_headers | list[str] | Cabeceras de solicitud permitidas | Configurar según sea necesario |
allow_credentials | bool | Si se permiten cookies e información de autenticación | Establecer en True cuando se requiera autenticaciónTrue |
expose_headers | list[str] | Cabeceras de respuesta accesibles para el front-end | Configurar según sea necesario |
max_age | int | Tiempo 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.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.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ón
allow_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 utilizan
PUT、DELETEmétodos no simples como - Las cabeceras de solicitud contienen campos personalizados (como
Authorization) Content-Typeno esapplication/x-www-form-urlencoded、multipart/form-dataotext/plain
Al establecer
max_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
- Use
CORSMiddlewarepara manejar solicitudes cross-origin - En el entorno de producción, asegúrese de especificar orígenes específicos
allow_origins, no use["*"] allow_credentials=Trueyallow_origins=["*"]incompatible- El middleware CORS maneja automáticamente las solicitudes de verificación previa OPTIONS del navegador