Как настроить CORS в FastAPI?

Question

Accepted Answer

**CORS** (Cross-Origin Resource Sharing) — это механизм безопасности браузера, который контролирует, может ли веб-страница с одного **origin** вызывать ваш API на другом origin. FastAPI настраивает это встроенным **`CORSMiddleware`**. Вы столкнетесь с CORS, когда фронтенд на другом домене/порту будет вызывать ваш API.

## Проблема, которую решает CORS

```text
A React app at http://localhost:3000 calling an API at http://localhost:8000 is
CROSS-ORIGIN (different port). The BROWSER blocks the response unless the API
sends CORS headers permitting that origin.
(origin = scheme + host + port)
```

## Настройка CORSMiddleware

```python
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com", "http://localhost:3000"],  # ALLOWLIST of origins
    allow_credentials=True,         # allow cookies/auth (requires specific origins, not "*")
    allow_methods=["*"],             # or ["GET", "POST", ...]
    allow_headers=["*"],
)
```

Промежуточное ПО добавляет необходимые CORS заголовки ответов, сообщая браузеру, какие origin, методы и заголовки разрешены. Браузер применяет эти правила.

## Безопасность: ограничивайте origin (не используйте "*")

```python
# ❌ allowing all origins — convenient but insecure for credentialed/private APIs
allow_origins=["*"]
# ✅ restrict to your known frontend origins (an allowlist)
allow_origins=["https://app.example.com"]
# NOTE: allow_credentials=True is INCOMPATIBLE with allow_origins=["*"]
```

Для production **ограничьте `allow_origins` конкретным списком разрешенных источников** вместо `*`. Кроме того, разрешение учетных данных (cookies/auth) требует конкретных origin — подстановочный знак не допускается с учетными данными.

## Распространенное неправильное понимание

```text
CORS is enforced by the BROWSER, not the server. It does NOT protect your API from
non-browser clients (curl, Postman, other servers) — those ignore CORS entirely.
CORS only governs what browser JavaScript from other origins may do.
```

## Почему это важно

CORS — одна из самых распространенных проблем в веб-разработке — практически каждая настройка фронтенд-к-API встречается с ней (особенно при локальной разработке на разных портах и в production с отдельным доменом фронтенда), поэтому умение настраивать его с помощью `CORSMiddleware` FastAPI — это практическое, часто необходимое знание.

Понимание *почему* это существует (безопасность same-origin браузера), того, как сервер явно разрешает через заголовки ответов, и как его настраивать (разрешенные origin, методы, заголовки, учетные данные) необходимо для подключения фронтендов к API FastAPI без блокировки запросов.

Единственно важно настраивать это **безопасно** — ограничивая `allow_origins` конкретным списком разрешенных источников вместо permissive `*` (и понимая, что учетные данные несовместимы с подстановочным знаком) — и понимая критическое неправильное понимание того, что **CORS является механизмом браузера, а не авторизацией API** (он не защищает от non-browser клиентов).

Умение правильно и безопасно настраивать CORS — это важное повседневное знание для любого FastAPI API, потребляемого веб-фронтендом.