Jak skonfigurować CORS w FastAPI?

Question

Accepted Answer

**CORS** (Cross-Origin Resource Sharing) to mechanizm bezpieczeństwa przeglądarki kontrolujący, czy strona internetowa z jednego **origin** może wywoływać Twoje API na innym origin. FastAPI konfiguruje go za pomocą wbudowanego **`CORSMiddleware`**. Napotkasz CORS za każdym razem, gdy frontend z innej domeny/portu wywoła Twoje API.

## Dlaczego to ważne

```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)
```

## Konfiguracja 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=["*"],
)
```

Middleware dodaje niezbędne nagłówki odpowiedzi CORS, informując przeglądarkę, które origin, metody i nagłówki są dozwolone. Przeglądarka egzekwuje te reguły.

## Bezpieczeństwo: ograniczenie origin (nie używaj "*")

```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=["*"]
```

W środowisku produkcyjnym **ogranicz `allow_origins` do listy dozwolonych** zamiast `*`. Ponadto, zezwolenie na poświadczenia (pliki cookie/auth) wymaga określonych origin — wildcard nie jest dozwolony z poświadczeniami.

## Kluczowe nieporozumienie

```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.
```

## Dlaczego to ważne

CORS jest jedną z najczęstszych przeszkód w tworzeniu aplikacji internetowych — prawie każda konfiguracja frontend-do-API na nią trafia (szczególnie w lokalnym rozwoju z różnymi portami i w produkcji z osobną domeną frontendu), więc wiedza, jak je skonfigurować za pomocą `CORSMiddleware` w FastAPI, to praktyczna, często potrzebna wiedza.

Zrozumienie *dlaczego* istnieje (bezpieczeństwo same-origin przeglądarki), jak serwer się na niego zgadza poprzez nagłówki odpowiedzi i jak go skonfigurować (dozwolone origin, metody, nagłówki, poświadczenia) jest niezbędne do połączenia frontendu z API FastAPI bez blokowania żądań.

Również ważne jest skonfigurowanie go **bezpiecznie** — ograniczenie `allow_origins` do konkretnej listy dozwolonych zamiast permisywnego `*` (i zrozumienie, że poświadczenia są niezgodne z wildcardem) — i uchwycenie kluczowego nieporozumienia, że **CORS to mechanizm przeglądarki, a nie autoryzacja API** (nie chroni przed klientami nie będącymi przeglądarkami).

Wiedza, jak prawidłowo i bezpiecznie skonfigurować CORS, to ważna, codziennie potrzebna wiedza dla każdego API FastAPI konsumowanego przez frontend internetowy.