Laravel과 Next.js를 Cookie/Session으로 연동하는 심층 가이드: Breeze/Sanctum 없이 간편하게 구현하기

핵심 기술

이 문서는 Laravel과 Next.js를 API 토큰이나 Sanctum 없이, 순수하게 Cookie와 Session 메커니즘만을 활용하여 연동하는 방법을 상세히 안내합니다. 특히 서로 다른 도메인 환경에서도 안정적으로 세션을 유지하고 인증을 처리하는 데 필요한 CORS 설정, SESSION_SAME_SITE, SESSION_SECURE_COOKIE 설정과 CSRF 토큰 처리 방안을 집중적으로 다룹니다.

기술적 세부사항

• Cookie/Session 기반 연동 방식:
  • 방법 1: Next.js 클라이언트에서 직접 Laravel API로 요청 시, 브라우저가 자동으로 쿠키(세션 ID)를 첨부하는 방식.
  • 방법 2: Next.js 서버에서 API 요청을 프록싱하여 Laravel API로 전달하는 방식.
• Laravel 설정:
  • .env 파일에서 SESSION_SAME_SITE=None 및 SESSION_SECURE_COOKIE=true 설정 (HTTPS 환경 필수).
  • config/cors.php에서 api/* 경로 허용, allowed_origins 설정, supports_credentials=true 활성화.
  • /api/v1/csrf-token 라우트 설정으로 CSRF 토큰 획득.
  • 로그인(POST /api/v1/login) 및 유저 정보 조회(GET /api/v1/user/me), 로그아웃(DELETE /api/v1/logout) API 엔드포인트 구현.
  • 로그인 시 guest 미들웨어 대신 컨트롤러 내에서 로그인 여부 직접 확인 (JSON 응답을 위해).
• Next.js 구현:
  • 방법 1:
    • 로그인 페이지 (app/login/page.tsx)에서 CSRF 토큰을 먼저 가져온 후, 로그인 요청 시 CSRF 토큰과 함께 credentials: 'include' 옵션으로 세션 쿠키 전달.
    • 메인 페이지 (app/page.tsx)에서 /user/me API를 credentials: 'include' 옵션으로 호출하여 로그인된 사용자 정보 표시.
  • 방법 2:
    • Next.js API 라우트 핸들러 (app/api/[...path]/route.ts)를 사용하여 모든 API 요청을 Laravel 서버로 프록싱.
    • .env에 API_URL 설정 (Laravel 서버 주소).
    • 프록싱 시 X-Requested-With, Content-Type, Accept 헤더 추가 및 credentials: 'include' 사용.
    • 응답 헤더(쿠키 포함)를 그대로 전달.
    • Next.js 클라이언트에서는 NEXT_PUBLIC_APP_URL을 사용하여 프록싱된 API 호출.

개발 임팩트

• Breeze, Sanctum 등의 별도 패키지 없이 순수 PHP 세션 및 쿠키 기반으로 Laravel과 Next.js 간의 인증 연동을 구현할 수 있어, 프로젝트 의존성을 줄이고 이해도를 높일 수 있습니다.
• 특히 CORS, SameSite, Secure 쿠키 설정에 대한 깊이 있는 이해를 바탕으로 보다 견고하고 안전한 인증 메커니즘을 구축할 수 있습니다.
• Next.js 서버 프록싱 방식은 CORS 설정을 간결하게 관리하는 데 도움을 줄 수 있으며, 프론트엔드와 백엔드의 분리성을 유지하면서도 seamless한 사용자 경험을 제공합니다.

커뮤니티 반응

• 해당 콘텐츠는 Laravel과 Next.js 연동에 대한 실질적인 구현 예제가 부족한 점을 지적하며, 실제 코드를 포함한 상세한 가이드를 제공하여 개발자 커뮤니티에 기여하고자 하는 목적을 명확히 합니다.
• 특히 Cookie/Session 기반 연동의 까다로움과 CORS, SameSite 등 고려사항이 많다는 점을 강조하며, 이에 대한 해결책을 공유합니다.