트러블슈팅 - HttpOnly Refresh Token이 로컬 개발 환경에서 쿠키에 안 보이는 문제

문제 상황

Spring Boot + JWT 인증 구조에서 로그인 시 refreshToken을 HttpOnly 쿠키에 담아 응답하도록 설정했다.

ResponseCookie refreshTokenCookie = ResponseCookie.from("refreshToken", refreshToken)
    .httpOnly(true)
    .secure(true)
    .path("/api/auth/refresh")
    .maxAge(Duration.ofDays(14))
    .sameSite("None")
    .build();

return ResponseEntity.ok()
    .header(HttpHeaders.SET_COOKIE, refreshTokenCookie.toString())
    .body(...);

그러나 로컬에서 http://localhost로 서버를 실행했을 때, 브라우저에 쿠키가 저장되지 않았다.

원인 분석

쿠키 설정에서 아래 두 옵션이 문제였다.

• secure=true : HTTPS에서만 쿠키 전송을 허용
• sameSite="None" : 크로스 도메인 요청에서 쿠키 전송 허용. 단, secure=true 조건 필수

따라서 로컬에서는 쿠키 자체가 전송되지 않는다. -> 브라우저 개발자 도구에서도 보이지 않음

해결 방법

환경에 따라 쿠키 설정을 분기 처리하도록 수정하였다.

boolean isLocal = true; // 개발/운영 환경에 따라 설정

ResponseCookie refreshTokenCookie = ResponseCookie.from("refreshToken", refreshToken)
    .httpOnly(true)
    .secure(!isLocal)                          // 운영에서는 secure=true
    .path("/api/auth/refresh")
    .sameSite(isLocal ? "Lax" : "None")        // 로컬에서는 Lax로 설정
    .maxAge(Duration.ofDays(14))
    .build();

• 로컬(localhost)
  • secure=false, sameSite=Lax
  • 쿠키 정상 전송됨 (브라우저 Application > Cookies 탭에서 확인 가능)
• 운영(https)
  • secure=true, sameSite=None
  • 크로스 사이트에서도 쿠키 전송 가능 (보안 유지)

보안상 중요한 포인트

• httpOnly=true 덕분에 JS에서는 document.cookie로 접근이 불가하다. -> XSS 방어
• 브라우저 콘솔에서 쿠키가 안 보이는 건 정상 동작이다.