[FE] Next.js 로컬 개발환경에서 HTTPS 적용하기 (mkcert, 서브도메인 쿠키 공유)

출처: https://www.descope.com/learn/post/enterprise-sso

1. 문제 상황

로컬 개발 환경에서 SSO(Single Sign-On) 로직을 구현하고 있었습니다.

여러 서비스가 동일한 서브도메인 형태로 분리된 구조고, 인증은 하나의 인증 서버에서 담당합니다.

 

흐름

(A 사이트) 로그인 -> (B 사이트 SSO 담당) 로그인 페이지 -> 로그인 및 쿠키 저장 -> (A 사이트) 쿠키 기반 인증 처리

 

개발 환경

• 프론트엔드: HTTP (로컬)
• 인증 서버: HTTPS
• 인증 쿠키 옵션: 
• Secure=true SameSite=None
• 서브도메인 기반 SSO 구조

 

문제 현상

• 로그인은 성공
• 쿠키는 저장된 것처럼 보임
• 다른 서브도메인에서는 쿠키가 전달되지 않음
• 결과적으로 SSO 실패

문제의 원인은 쿠키의 Secure 옵션입니다.

브라우저 보안 정책상 이 옵션이 설정된 쿠키는 HTTPS에서만 동작하며,

HTTP 사이트가 HTTPS 사이트의 쿠키를 읽거나 공유하는 것을 차단합니다.

 

2.  mkcert로 로컬 HTTPS 환경 구성

mkcert란?

mkcert는 복잡한 설정 없이 로컬 개발용으로 SSL 인증서를 만들어주는 간단한 도구입니다.

• 로컬 CA 생성 및 OS에 등록
• 운영 환경과 거의 동일한 HTTPS 조건 구성 가능

설치하기

# 1. 터미널 명령어 실행 (Mac 기준)
brew install mkcert                                                                                                                                                                                                              
mkcert -install                                                                                                                                                                                                                  

# 2. React/Next 프로젝트 루트에 인증서 생성
cd /Users/hyunki/Desktop/project/my-proj
mkcert "*.example.io"

 

로컬 호스트를 특정한 도메인으로 변경하는 방법 (선택)

서브도메인 기반 쿠키 공유를 하려면, 도메인이 있어야겠죠? 로컬 호스트에서도 가능합니다.

아래와 같이 host를 추가해 주면 내부적으로는 로컬 호스트지만 도메인을 사용할 수 있습니다.

sudo nano /etc/hosts

* 추가
127.0.0.1 auth.example.com

* 종료
!wq

 

package.json 스크립트 수정해서 실행하기

{
  "scripts": {
    // 기존 스크립트 예시
    "dev:auth": "next dev --turbopack --hostname auth.example.com --port 3000",
    
    // HTTPS 실행 스크립트
    "dev:auth:https": "next dev --turbopack --hostname auth.example.com --port 3000 --experimental-https --experimental-https-key ./_wildcard.example.com-key.pem --experimental-https-cert ./_wildcard.example.com.pem"
  }
}

 

스크립트를 추가해서 프로젝트를 실행하면 간편합니다.

 

Next.js 실행 스크립트 속성 설명

속성	설명
--experimental-https	Next.js에게 "이제 HTTP가 아니라 HTTPS 프로토콜로 서버를 열어줘"라고 명령하는 핵심 스위치입니다.
--experimental-https-key	mkcert로 생성한 파일 중 개인키(-key.pem) 파일의 경로를 지정합니다. 서버가 데이터를 암호화할 때 사용합니다.
--experimental-https-cert	mkcert로 생성한 인증서(.pem) 파일의 경로를 지정합니다. 브라우저에게 "이 서버는 신뢰할 수 있어"라고 증명하는 신분증 역할을 합니다.

 

 

3. 결과

HTTPS로 실행된 로컬호스트

로컬 호스트가 HTTPS로 실행 가능하게 되었고,

쿠키의 Secure 옵션 때문에 서브도메인간 쿠키 공유가 되지 않던 이슈도 해결되었습니다. 🥳

 

4. 주의 사항

- mkcert는 로컬 개발용입니다 !

- rootCA-key.pem이 유출되지 않도록 조심하세요 ! 

 

+ 약간의 소개

원래 제가 포스팅하던 형식은 머릿글에 중앙 정렬하고 조금 이쁘장하게 전달하려는 의도가 있었는데,

트러블슈팅이나 오늘처럼 간단한 포스팅은 요런 간결한 velog 스타일로 작성해보려고 합니다 😀

---