B컷전문 | 개발과 인생의 이야기

FastAPI에서 CORS(Cross-Origin Resource Sharing) 정책을 설정하고, HTTP 보안 헤더를 적용하는 방법을 설명합니다. 프론트엔드 연동과 API 보안 강화를 위한 실전 설정 예제를 포함합니다.

1. 왜 CORS 설정이 필요한가?

브라우저 기반의 프론트엔드가 외부 API 서버와 통신하려고 할 때,
서버가 CORS 정책을 명시적으로 허용하지 않으면 요청이 차단됩니다.

예를 들어,

• Vue/React 앱이 http://localhost:3000에서 실행되고
• FastAPI 백엔드가 http://localhost:8000에 있다면

다른 도메인 간 요청이므로 반드시 CORS 허용 설정이 필요합니다.

---

2. FastAPI에서 CORS 설정 방법

FastAPI는 Starlette의 미들웨어 구조를 그대로 사용할 수 있습니다.

from fastapi.middleware.cors import CORSMiddleware
from fastapi import FastAPI

app = FastAPI()

origins = [
    "http://localhost:3000",  # React 개발 서버
    "https://myfrontend.com"  # 배포된 프론트엔드 도메인
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,  # 허용할 출처 목록
    allow_credentials=True,
    allow_methods=["*"],  # 모든 HTTP 메서드 허용
    allow_headers=["*"],  # 모든 헤더 허용
)

✅ 주요 옵션 설명

옵션 설명

allow_origins	허용할 도메인 리스트
allow_credentials	쿠키 포함 요청 허용 여부
allow_methods	허용할 HTTP 메서드 (GET, POST 등)
allow_headers	요청 시 허용할 헤더 종류

---

3. 보안 헤더란 무엇인가?

HTTP 응답에 포함되는 보안 관련 메타 정보로,
XSS, 클릭재킹, 콘텐츠 스니핑 등을 방지할 수 있습니다.

🔒 대표 보안 헤더 목록

헤더 설명

X-Content-Type-Options: nosniff	브라우저가 MIME 타입 추측하지 않도록 설정
X-Frame-Options: DENY	클릭재킹 방지 (iframe 차단)
X-XSS-Protection: 1; mode=block	XSS 공격 차단 필터 활성화
Strict-Transport-Security	HTTPS 연결 강제 (HSTS)

---

4. 보안 헤더 적용 미들웨어 구현

FastAPI는 미들웨어 방식으로 보안 헤더를 직접 주입할 수 있습니다.

from starlette.middleware.base import BaseHTTPMiddleware
from starlette.responses import Response

class SecurityHeadersMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request, call_next):
        response: Response = await call_next(request)
        response.headers["X-Content-Type-Options"] = "nosniff"
        response.headers["X-Frame-Options"] = "DENY"
        response.headers["X-XSS-Protection"] = "1; mode=block"
        response.headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains"
        return response

app.add_middleware(SecurityHeadersMiddleware)

• 요청 처리 후 응답 헤더에 보안 메타데이터 삽입
• 서버 차원에서 전 API 공통 적용 가능

---

5. 실무 적용 팁

항목 설명

도메인 와일드카드 제한	allow_origins=["*"]은 개발 중에만 사용, 배포 시 명확히 제한
쿠키 인증 사용 시	allow_credentials=True, 정확한 도메인 지정 필요
OPTIONS 사전 요청	일부 브라우저는 CORS preflight 요청을 먼저 보냄 → 반드시 허용 필요
CDN/Reverse Proxy 연동 시	실제 Origin 헤더를 파악하여 미들웨어 조건 분기 가능

---

6. Swagger UI에서 CORS 오류가 나는 경우

Swagger UI는 프론트엔드 SPA로 간주되기 때문에,
다른 Origin에서 접근 시 CORS 오류가 발생할 수 있습니다.

이를 방지하려면 Swagger UI를 별도 배포하지 않고 백엔드와 함께 배포하거나,
Swagger UI에서도 CORS 허용 헤더가 적용된 상태에서 API 테스트가 이뤄져야 합니다.

---

정리 – API 개발의 기본은 보안 설정부터

기능 설정 방식

CORS 허용	CORSMiddleware로 도메인, 메서드, 헤더 제한 설정
보안 헤더 삽입	BaseHTTPMiddleware로 공통 보안 헤더 주입
실무 보안 확장	HTTPS 적용, 인증 헤더 제한, CSRF 대응 등 병행 필요

CORS 설정은 "테스트할 수 있는 API"를 만드는 첫 걸음이고,
보안 헤더는 "운영 가능한 API"를 위한 필수 조건입니다.