쿠키 기반 SSO: 서브도메인에서 세션 공유하기

쿠키 기반 세션은 구현이 단순하고(특히 SSR/정적+프록시 환경), 브라우저가 자동으로 쿠키를 붙여주기 때문에 “한 도메인 안에서 SSO”를 만들기 좋습니다.

이 문서는 app.example.com, docs.example.com처럼 서브도메인이 여러 개일 때 세션 쿠키를 공유하는 방법을 정리합니다.

예시는 모두 익명화되어 있으며, example.com을 사용합니다.

관련 용어: Cookie, Session, SameSite, HttpOnly, Secure cookie

1) 목표

• https://app.example.com에서 로그인
• https://docs.example.com에서도 동일한 로그인 상태 유지

2) 쿠키 설정 핵심 5가지

2-1) Domain

서브도메인 공유를 하려면 보통:

• Domain=.example.com (점 포함) 으로 설정합니다.

Host-only 쿠키(= Domain 미지정)는 해당 호스트에서만 유효합니다.

2-2) Path

대부분 /로 둡니다.

• /auth 같은 특정 path로 제한하면 “다른 앱에서 쿠키를 못 읽는” 문제를 만들기 쉽습니다.

2-3) Secure

프로덕션에서는 필수입니다.

• Secure가 없으면 HTTPS 환경에서도 공격면이 커집니다.

2-4) HttpOnly

가능하면 켜세요.

• JS로 쿠키를 못 읽게 막아 XSS 시 피해를 줄입니다.

2-5) SameSite

기본 추천은 Lax입니다.

• Lax: 대부분의 “일반적인 사이트 이동”에선 쿠키가 붙고, CSRF 위험을 줄입니다.
• None: 크로스사이트에서도 쿠키가 붙습니다(반드시 Secure 필요). 정말 필요한 경우에만 사용하세요.

3) 프록시 뒤(nginx)에서 꼭 확인할 것

앱이 nginx 뒤에 있을 때는 “원래 요청이 HTTPS였는지”를 앱이 알아야 합니다.

nginx:

proxy_set_header X-Forwarded-Proto $scheme;

Express:

• app.set('trust proxy', 1) 같은 설정이 필요할 수 있습니다.
• 그렇지 않으면 앱이 “내가 HTTP로 요청받았다”고 오해해 Secure 쿠키를 안 붙이거나, 리다이렉트 URL을 잘못 만들 수 있습니다.

관련 용어: X-Forwarded-Proto, trust proxy

4) 권장 엔드포인트 패턴

• GET /api/auth/session → { authenticated, user }
• 미인증이면 /auth?redirect=<원래 가려던 URL>로 보내기

여기서 redirect 파라미터는 오픈 리다이렉트가 되지 않도록 반드시 검증해야 합니다.

관련 용어: Open Redirect

5) 자주 터지는 문제(체크리스트)

• HTTPS인데 쿠키가 안 붙는다 → Secure/trust proxy/X-Forwarded-Proto 확인
• 어떤 서브도메인에서만 로그인 풀린다 → Domain/Path 확인
• iframe/외부 사이트에서 열면 로그인 풀린다 → SameSite=None 필요 여부 재검토
• 로그아웃이 일부 앱에만 적용된다 → 쿠키 이름/Domain/Path가 서로 다른지 확인

같이 보면 좋은 문서:

• JWT vs Session (언제 무엇을 쓰나?)
• 세션/쿠키 장애 트러블슈팅