Debugging Detective

가장 가능성 높은 원인은 HTTPS 스테이징에서 세션 쿠키가 설정되지 않거나, 설정돼도 다른 서브도메인으로 전송되지 않는 것입니다. 4.x → 5.x beta 마이그레이션 직후이고 로컬 HTTP에서는 정상이라는 점이 강한 단서입니다.

확인하면 좋은 질문은 세 가지입니다.

1. 로그인 응답의 Set-Cookie 헤더가 실제로 존재하나요?
2. 로그인 페이지, API, 홈의 호스트명이 각각 무엇인가요? 예: app.example.com, api.example.com
3. 스테이징 앞에 ALB/Nginx/Cloudflare 같은 TLS 종료 프록시가 있나요?

가능성 순위는 다음과 같습니다.

1. Secure 쿠키와 프록시의 HTTPS 인식 불일치
   브라우저는 HTTPS 쿠키로 받았지만 NextAuth가 요청을 HTTP로 판단하거나, 반대로 Secure 쿠키를 HTTP 응답에서 설정하려 해 저장하지 못하는 경우입니다.

2. 서브도메인 간 쿠키 Domain 설정 누락
   app.example.com에서 발급한 쿠키가 api.example.com 또는 다른 호스트로 전달되지 않을 수 있습니다. 기본 쿠키는 발급된 호스트에만 귀속됩니다.

3. NextAuth v5 환경 변수/쿠키 이름 변경 문제
   v5에서는 기본 쿠키명이 authjs.session-token, HTTPS에서는 __Secure-authjs.session-token 계열로 바뀔 수 있습니다. 기존 next-auth.session-token만 검사하고 있으면 쿠키가 없는 것처럼 보일 수 있습니다.

4. /api/session 응답 캐시로 인한 304
   304 자체가 인증 실패의 원인은 아니지만, 세션 응답이 캐시되어 로그인 전 상태를 재사용하는지 확인해야 합니다.

5. SameSite 정책으로 인한 교차 사이트 요청 차단
   서브도메인만 다른 경우 일반적으로 같은-site이지만, 프런트엔드와 인증 서버의 실제 registrable domain이 다르거나 iframe/교차 사이트 요청이면 문제가 됩니다.

가장 먼저 다음 순서로 확인하세요.

브라우저 DevTools에서 로그인 요청을 열고:

• Response Headers에 Set-Cookie가 있는지
• Set-Cookie의 이름이 무엇인지
• Secure, HttpOnly, SameSite, Domain, Path 값
• Application → Cookies에 쿠키가 실제 저장됐는지
• 새로고침 후 /api/session 요청의 Request Headers에 해당 쿠키가 포함되는지

특히 다음 패턴을 확인하세요.

Set-Cookie: __Secure-authjs.session-token=...

또는

Set-Cookie: authjs.session-token=...

로그인 응답에는 Set-Cookie가 있는데 Application Cookies에 저장되지 않으면 Secure, Domain, 호스트, 프록시 HTTPS 인식 문제일 가능성이 큽니다. 저장은 됐지만 /api/session 요청에 포함되지 않으면 Domain/SameSite/호스트 불일치입니다.

서버에서는 토큰 자체를 로그로 남기지 말고 다음만 기록하세요.

console.log({
  host: req.headers.get("host"),
  forwardedProto: req.headers.get("x-forwarded-proto"),
  cookieNames: req.headers.get("cookie")?.split(";").map(x => x.trim().split("=")[0]),
});

그리고 NextAuth v5 설정에서 다음 항목을 확인하세요.

export const { handlers, auth } = NextAuth({
  trustHost: true,
  secret: process.env.AUTH_SECRET,
  // 필요할 때만 명시
  cookies: {
    sessionToken: {
      name: "__Secure-authjs.session-token",
      options: {
        httpOnly: true,
        secure: true,
        sameSite: "lax",
        path: "/",
        domain: ".example.com",
      },
    },
  },
});

다만 domain: ".example.com"은 실제로 여러 서브도메인 간 세션을 공유해야 할 때만 사용해야 합니다. 로그인과 /api/session이 같은 호스트에서 처리된다면 Domain을 임의로 추가하지 않는 편이 안전합니다.

프록시를 사용한다면 프록시가 다음 정보를 전달하는지도 확인하세요.

X-Forwarded-Proto: https
X-Forwarded-Host: 실제 외부 호스트

NextAuth v5에서는 스테이징 환경에 보통 다음도 확인해야 합니다.

AUTH_SECRET=동일하고 충분히 긴 값
AUTH_TRUST_HOST=true

AUTH_SECRET이 요청마다 달라지거나 배포 인스턴스별로 다르면 쿠키는 있어도 세션 복호화가 실패합니다.

304는 우선순위가 낮은 단서입니다. /api/session이 인증 상태에 따라 달라지는 응답이라면 캐시되지 않도록 확인하세요. 응답에 Cache-Control: no-store가 없고 CDN이나 프록시가 개입한다면 임시로 캐시를 우회해 재현해 보세요.

근본 원인은 대개 인증 쿠키의 발급 호스트·보안 속성·프록시의 외부 URL 인식이 배포 환경마다 암묵적으로 달라진 것입니다. 로컬에서는 HTTP와 단일 호스트라 이 불일치가 드러나지 않고, HTTPS·서브도메인·TLS 종료 프록시가 있는 스테이징에서만 나타나는 전형적인 배포 설정 문제입니다.