CORS 에러와 Cookie 문제 해결기 / FastAPI, next.js 연동

 

이번에 새로운 프로젝트를 진행하며 Auth 로그인 기능을 구현했다.
로그인 시 인증을 위해 토큰 값을 쿠키에 저장해야 했는데, 예상치 못한 문제가 발생했다.

 

백엔드 서버를 배포한 뒤 프론트엔드 팀에게 Endpoint를 제공했는데,
프론트엔드의 로컬 개발 URL과 백엔드 서버 주소가 서로 달라서
쿠키에 토큰 값이 제대로 저장되지 않는 현상이 생겼다.

 

이 문제는 CORS(Cross-Origin Resource Sharing)와 관련된 전형적인 이슈였다.
서버 간 출처(Origin)가 다를 경우, 브라우저가 보안을 위해 쿠키를 차단하기 때문이다.

 

처음에는 프록시 서버를 구성하는 방법으로 접근하려 했지만,
로컬 환경에서는 복잡한 설정 없이도 간단히 해결할 수 있었다.
결국 hosts 파일을 수정해 로컬 URL을 맞추는 방법으로 문제를 해결했다.

 

---

개발 환경

• Backend: Python 3.13 / FastAPI
• Frontend: Next.js
• Server: Ubuntu 24.04 LTS
• Local OS: macOS

 

---

1. 로컬 hosts 파일 수정

로컬 환경에서 프론트엔드와 백엔드의 도메인을 통일하기 위해
/etc/hosts 파일에 사용자 정의 도메인을 추가했다.

 

# 1. hosts 진입
sudo nano /etc/hosts

# 2. localhost 수정

##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting.  Do not change this entry.
##
127.0.0.1       my.domain
255.255.255.255 broadcasthost
::1             localhost

 

---

2. Next.js 설정 변경

Next.js 개발 서버가 새로운 도메인을 인식하도록 package.json을 수정한다.

 

# package.js 수정

"scripts": {
    "dev": "next dev -H my.domain"
    }

 

이제 개발 서버를 실행하면
로컬에서도 my.domain을 호스트로 인식하게 된다.

---

3. FastAPI 쿠키 설정 수정

마지막으로, FastAPI에서 쿠키를 설정할 때 도메인을 명시한다.
response.set_cookie() 함수에 domain 값을 지정해야 쿠키가 올바르게 저장된다.

 

...

response.set_cookie(
            key="refresh_token",
            value=refresh_token,
            httponly=True,
            secure=False, 
            max_age=600,
            samesite="lax",
            domain="my.domain"
        )

 

이렇게 설정하면, 브라우저는 동일한 my.domain 내에서 쿠키를 공유할 수 있으며
프론트엔드와 백엔드 간의 CORS 쿠키 차단 문제가 해결된다.