FastAPI'de CORS nasıl yapılandırılır?

Question

Accepted Answer

**CORS** (Cross-Origin Resource Sharing), bir web sayfasının bir **origin** üzerinden API'nize farklı bir origin üzerinde çağrı yapabilmesini kontrol eden bir tarayıcı güvenlik mekanizmasıdır. FastAPI bunu yerleşik **`CORSMiddleware`** ile yapılandırır. Farklı bir domain/port üzerindeki ön uç API'nize çağrı yaptığında CORS ile karşılaşırsınız.

## CORS'un çözdüğü sorun

```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'i Yapılandırma

```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, gerekli CORS yanıt başlıklarını ekleyerek tarayıcıya hangi originlerin, metodların ve başlıkların izin verileceğini söyler. Tarayıcı bu kuralları uygular.

## Güvenlik: origin'leri kısıtlayın ("*" kullanmayın)

```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'da, `allow_origins`'i `*` yerine bir beyaz listeye **kısıtlayın**. Ayrıca, kimlik bilgilerine (cookie/auth) izin vermek belirli origin'ler gerektirir — wildcard kimlik bilgilerine uygun değildir.

## Önemli bir yanlış anlama

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

## Neden önemli

CORS, web geliştirmede en yaygın engel taşlarından biridir — neredeyse her ön uç-API kurulumu bununla karşılaşır (özellikle farklı portlarla yerel geliştirmede ve ayrı bir ön uç domain'ine sahip production'da), bu nedenle FastAPI'nin `CORSMiddleware`'i ile nasıl yapılandırılacağını bilmek pratik, sık ihtiyaç duyulan bilgidir.

Nedenini (tarayıcı same-origin güvenliği), sunucunun yanıt başlıkları aracılığıyla nasıl uyması gerektiğini (allowed origins, methods, headers, credentials) ve nasıl yapılandırılacağını (izin verilen originler, metodlar, başlıklar, kimlik bilgileri) anlamak, ön uçları FastAPI API'lerine bağlamak için istekler engellenmeden gereklidir.

Eşit derecede önemli olan, bunu **güvenli bir şekilde** yapılandırmak — `allow_origins`'i permissive `*` yerine belirli bir beyaz listeye kısıtlamak (ve wildcard ile kimlik bilgilerinin uyumlu olmadığını anlamak) — ve **CORS'un tarayıcı mekanizması olduğunun, API yetkilendirmesi olmadığının** önemli yanlış anlamasını kavramaktır (tarayıcı olmayan istemcilere karşı korunmaz).

CORS'u doğru ve güvenli bir şekilde kurmayı bilmek, bir web ön ucu tarafından tüketilen herhangi bir FastAPI API'si için her gün gerekli olan bilgidir.