Làm thế nào để cấu hình CORS trong FastAPI?

Question

Accepted Answer

**CORS** (Cross-Origin Resource Sharing) là một cơ chế bảo mật của trình duyệt kiểm soát việc một trang web từ một **origin** có thể gọi API của bạn trên một origin khác hay không. FastAPI cấu hình nó với **`CORSMiddleware`** tích hợp. Bạn sẽ gặp CORS bất cứ khi nào một frontend trên một domain/port khác gọi API của bạn.

## Vấn đề CORS giải quyết

```text
Một app React tại http://localhost:3000 gọi một API tại http://localhost:8000 là
CROSS-ORIGIN (port khác). TRÌNH DUYỆT chặn response trừ khi API
gửi các header CORS cho phép origin đó.
(origin = scheme + host + port)
```

## Cấu hình CORSMiddleware

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

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com", "http://localhost:3000"],  # ALLOWLIST các origin
    allow_credentials=True,         # cho phép cookie/auth (yêu cầu origin cụ thể, không phải "*")
    allow_methods=["*"],             # hoặc ["GET", "POST", ...]
    allow_headers=["*"],
)
```

Middleware thêm các header CORS response cần thiết, báo cho trình duyệt biết những origin, method, và header nào được phép. Trình duyệt thực thi các quy tắc này.

## Bảo mật: hạn chế origin (đừng dùng "*")

```python
# ❌ cho phép tất cả origin — tiện nhưng không an toàn cho API có credential/riêng tư
allow_origins=["*"]
# ✅ hạn chế thành các origin frontend đã biết của bạn (một allowlist)
allow_origins=["https://app.example.com"]
# LƯU Ý: allow_credentials=True KHÔNG TƯƠNG THÍCH với allow_origins=["*"]
```

Cho production, **hạn chế `allow_origins` thành một allowlist** thay vì `*`. Ngoài ra, cho phép credential (cookie/auth) yêu cầu origin cụ thể — wildcard không được phép với credential.

## Một hiểu lầm then chốt

```text
CORS được thực thi bởi TRÌNH DUYỆT, không phải server. Nó KHÔNG bảo vệ API của bạn khỏi
client không phải trình duyệt (curl, Postman, server khác) — những cái đó bỏ qua CORS hoàn toàn.
CORS chỉ điều chỉnh những gì JavaScript trình duyệt từ origin khác được phép làm.
```

## Tại sao điều này quan trọng

CORS là một trong những trở ngại phổ biến nhất trong phát triển web — gần như mọi thiết lập frontend-tới-API đều gặp nó (đặc biệt trong phát triển cục bộ với các port khác nhau, và trong production với một domain frontend riêng), nên biết cách cấu hình nó với `CORSMiddleware` của FastAPI là kiến thức thực tiễn, thường cần.

Hiểu *tại sao* nó tồn tại (bảo mật same-origin của trình duyệt), cách server opt-in qua response header, và cách cấu hình nó (origin được phép, method, header, credential) là cần thiết để kết nối frontend với API FastAPI mà không bị chặn request.

Cũng quan trọng tương đương là cấu hình nó **an toàn** — hạn chế `allow_origins` thành một allowlist cụ thể thay vì `*` dễ dãi (và hiểu rằng credential không tương thích với wildcard) — và nắm hiểu lầm then chốt rằng **CORS là một cơ chế trình duyệt, không phải authorization API** (nó không bảo vệ khỏi client không phải trình duyệt).

Biết cách thiết lập CORS đúng đắn và an toàn là kiến thức hằng ngày quan trọng cho bất kỳ API FastAPI nào được tiêu thụ bởi một web frontend.