🔐 05. 외부 인증 서버 연동과 토큰 관리: "새로고침 하니까 로그아웃 되는데요?"

🎯 이 섹션을 읽고 나면:

• Zustand persist 미들웨어를 통해 로컬 스토리지나 세션 스토리지와 상태를 자동 동기화할 수 있다.
• JWT (Access Token & Refresh Token) 인증 플로우에서 상태 관리와 보안의 트레이드오프를 이해한다.
• 외부 인증 서버(Next.js BFF/Spring Boot) 연동 시 Zustand에 담아야 할 정보와 담지 말아야 할 정보를 완벽히 통제할 수 있다.

📋 목차

• 🤔 왜 알아야 하는가
• 🏗️ 1. 스토어 영속성 부여: persist 미들웨어
• 🛡️ 2. 영철이의 대참사: JWT 보안의 덫
  • 왜 안 될까요? (웹 보안 기초)
• 💎 3. 토큰 스토리지 분리 전략 (실무 아키텍처)
  • A. 유저 정보 (User Profile) -> Zustand + Persist [안전]
  • B. Access Token -> 순수 Zustand (메모리) [단기 체류]
  • C. Refresh Token -> HttpOnly 쿠키 [JS 접근 차단]
  • 실무 코드: 부분 영속성(Partialize) 통제
• 📍 4. 번외: Next.js 의 Hydration 미스매치 주의
• 🏋️‍♂️ 영철의 테스트 타임 (Q&A)

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 15분 / 핵심 파트: 10분

🗺️ 이 문서의 흐름
순수 스토어의 휘발성 문제 → persist 미들웨어 적용 → JWT 토큰의 보안 저장처 분배 전략 (XSS 방어)

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 🐣 영철 ( 신입 ): "리드 님! Zustand로 유저 로그인 상태를 예쁘게 만들어왔어요. 완전 빠릅니다! 근데... 사용자가 F5(새로고침)를 누르니까 다 날아가면서 다시 로그인 화면으로 튕기네요."
• 🦁 영호 ( 리드 ): "영철 님, JS 메모리는 브라우저 수명 주기에 종속되니까 당연히 다 날아가죠. 로컬 스토리지에 백업을 합시다. 아, 잠깐 영수(PM) 님이 백엔드 보안 쪽에서 하실 말씀이 있나 보네요."
• 👔 영수 ( PM / 백엔드 ): "영철 씨, 토큰 관리를 말씀드리는 건데요. 백엔드에서 발급해드린 Access Token이나 Refresh Token을 절대 로컬 스토리지에 무턱대고 저장하시면 안 됩니다. 해커들한테 뜯기면 책임지실 건가요?"

🤔 왜 알아야 하는가

Zustand 같은 상태 관리 라이브러리는 본질적으로 RAM 머신, 즉 브라우저의 JavaScript Memory Heap에 상주합니다. 따라서 페이지가 리로드되면 모든 상태는 초기 텅 빈 값으로 리셋되며, 이는 '로그인 유지'라는 가장 흔한 웹 앱 기믹에 치명적입니다.

이를 막기 위해 웹 스토리지(LocalStorage / SessionStorage)에 직접 setItem, getItem을 덕지덕지 바르면 코드가 스파게티가 됩니다. Zustand는 이를 위한 내장 persist 미들웨어를 제공하여 클릭 한 번 수준으로 영속성을 부여합니다.

하지만 영수가 경고했듯, 여기서 JWT (JSON Web Token) 아키텍처의 보안 문제가 수면 위로 떠오릅니다. 어떤 건 클라이언트 상태로 스토리지에 저장해도 되고, 어떤 건 절대로 JS가 접근하지 못하는 곳(HttpOnly)으로 숨겨야 할까요? 이를 모르면 편리함을 얻고 앱의 코어 단을 통째로 털리게 됩니다.

🏗️ 1. 스토어 영속성 부여: persist 미들웨어

가장 기본적인 persist 문법부터 살펴보겠습니다.

import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';
 
interface AuthState {
  isLoggedIn: boolean;
  username: string;
  login: (name: string) => void;
  logout: () => void;
}
 
// 🦁 영호: create 괄호 안에 persist 함수로 스토어 정의부를 한 번 더 감쌉니다.
export const useAuthStore = create<AuthState>()(
  persist(
    (set) => ({
      isLoggedIn: false,
      username: '',
      login: (name) => set({ isLoggedIn: true, username: name }),
      logout: () => set({ isLoggedIn: false, username: '' }),
    }),
    {
      name: 'auth-storage', // 스토리지에 저장될 때 사용될 Key 고유 식별자
      storage: createJSONStorage(() => sessionStorage), // 기본값은 localStorage. 여기선 브라우저 종료 시 날리려고 session 사용.
      
      // 💡 부분 저장 기능 (선택적 영속성)
      partialize: (state) => ({ isLoggedIn: state.isLoggedIn, username: state.username }),
    }
  )
);

이 코드를 작성하는 순간, Zustand는 상태의 변경이 일어날 때마다 자동으로 직렬화하여 브라우저 스토리지에 값을 동기화시킵니다. 새로고침해도 다시 그 스토리지에서 역직렬화하여 상태 복원을 알아서 처리해 줍니다.

🛡️ 2. 영철이의 대참사: JWT 보안의 덫

이제 로그인 시 받아오는 토큰을 관리해볼까요?

// ❌ 영철이의 폭탄 코드: 모든 걸 로컬 스토리지 기반 Zustand에 처박음
login: async (credentials) => {
  const { accessToken, refreshToken, user } = await api.post('/login');
  // 👔 영수 극대노: "Refresh Token을 로컬 스토리지에 저장했다고요?!"
  set({ accessToken, refreshToken, user }); 
}

왜 안 될까요? (웹 보안 기초)

• 브라우저의 localStorage나 sessionStorage에 저장된 값은 현재 페이지에서 동작하는 어떠한 자바스크립트 코드라도 접근(getItem)할 수 있습니다.
• 악성 스크립트가 유입되는 해킹 기법인 XSS(Cross-Site Scripting) 가 발동하면 해커가 즉시 그 토큰을 스틸할 수 있습니다.
• Refresh Token이 털리면, 해커는 토큰 만료 전까지 유저 행세를 무한대로 할 수 있습니다.

💎 3. 토큰 스토리지 분리 전략 (실무 아키텍처)

5년 차 시야에서는 성능과 보안 사이의 트레이드오프를 맞춘 하이브리드 전략을 적용합니다.

A. 유저 정보 (User Profile) -> Zustand + Persist [안전]

• 닉네임, 프로필 사진 URL, 테마 설정 등은 탈취되어도 즉각적인 파멸에 이르지 않는 읽기 전용 UI 데이터입니다.
• 이 데이터들은 로컬스토리지에 저장(Zustand Persist)하여 새로고침 직후에도 바로 렌더링되게 둡니다.

B. Access Token -> 순수 Zustand (메모리) [단기 체류]

• API 호출 때 헤더에 실어야 하므로 자바스크립트가 접근하긴 해야 합니다.
• 하지만 XSS 범위에 남지 않도록 로컬스토리지에 저장하지 않습니다 (즉, partialize 설정에서 걸러냅니다).
• 새로고침 시 이 메모리에서 날아가지만, 곧바로 백그라운드 API를 태워 새로 받아오면 그만입니다(Silent Refresh).

C. Refresh Token -> HttpOnly 쿠키 [JS 접근 차단]

• 이건 아예 프론트엔드가 관리하면 안 됩니다.
• 백엔드(영수)가 Set-Cookie: RefreshToken=...; HttpOnly; Secure; 속성을 붙여서 브라우저 쿠키 지갑에 직접 꽂아줍니다.
• 자바스크립트는 구조적으로(HttpOnly) 이 쿠키의 값을 영원히 읽을 수 없으므로 무적의 방어력이 생깁니다. 브라우저가 다음 인증 API 요청을 쏠 때 자동으로 동봉해서 보낼 뿐입니다.

실무 코드: 부분 영속성(Partialize) 통제

export const useAuthStore = create<AuthState>()(
  persist(
    (set) => ({
      user: null,         // 영속화 대상 (UI용)
      accessToken: null,  // 휘발성 메모리용 (API 인증용)
      
      setAuth: (user, token) => set({ user, accessToken: token }),
      clearAuth: () => set({ user: null, accessToken: null })
    }),
    {
      name: 'user-storage',
      // 🔥 핵심: 로컬스토리지에는 순수 유저 정보만 백업하고 토큰은 걸러낸다!
      partialize: (state) => ({ user: state.user }),
    }
  )
);

📍 4. 번외: Next.js 의 Hydration 미스매치 주의

Zustand의 persist는 근본적으로 "서버가 모르는 브라우저만의 데이터"를 초기 상태에 집어넣습니다.

만약 Next.js (SSR/SSG 환경)를 사용하고 있다면:

1. 서버에서 처음에 빈 값(isLoggedIn: false)인 채로 HTML 껍데기를 만들어 클라이언트로 보냄.
2. 클라이언트 React 모듈이 깨어나고(Hydration) Zustand가 로컬스토리지에서 true를 끄집어냄.
3. 리액트 엔진: "어라? 서버가 준 HTML이랑 니가 그릴 HTML이 다르네?!" 👉 Hydration Mismatch Error 폭발

해결책: Hydration이 완전히 종료되기 전까지는 Persist 스토어 렌더링을 늦추는(useEffect 내부에서 값 꺼내오기) 트릭이 필수적으로 동반되어야 합니다. (이 부분은 Next.js 심화 편 가이드에서 더 다루게 됩니다.)

📝 마무리 퀴즈

Q1. Zustand의 persist 미들웨어를 사용할 때 브라우저 로컬 스토리지에 JWT(Access Token 또는 Refresh Token)를 저장하면 발생하는 가장 치명적인 보안 취약점은 무엇인가요?

• A) CSRF (Cross-Site Request Forgery)
• B) SQL Injection
• C) XSS (Cross-Site Scripting)
• D) Clickjacking

✅ 정답: C

💡 상세 해설:

• 원리 설명: 로컬 스토리지 데이터는 브라우저 내에서 실행되는 모든 자바스크립트 코드(window.localStorage.getItem)에 노출됩니다. 게시판 글이나 광고 스크립트 등을 통해 악성 스크립트가 주입되는 XSS 공격 시, 해커가 즉각적으로 토큰을 탈취할 수 있습니다.
• 오답 피드백: "영철 님, CSRF 방어를 위해서는 쿠키(HttpOnly, SameSite)를 쓰거나 헤더 설정을 추가해야 하고, 스토리지 토큰 탈취는 전형적인 XSS 밥입니다."
• 📌 핵심 기억법: 👔 영수: "로컬 스토리지는 유리벽 안의 금고입니다. 자바스크립트라는 열쇠만 있으면 누구나 들여다볼 수 있습니다."

Q2. Zustand 스토어의 persist 미들웨어 사용 시, 보안상 민감한 토큰 데이터만 스토리지 백업에서 제외하고 유저 프로필 등 안전한 정보만 저장하고 싶을 때 사용하는 속성은 무엇인가요?

• A) exclude
• B) partialize
• C) serialize
• D) getStorage

✅ 정답: B

💡 상세 해설:

• 원리 설명: persist 설정 객체 내의 partialize: (state) => ({ user: state.user }) 와 같이 선언하면, 전체 Zustand 상태 중에서 지정된 속성만 골라서 스토리지에 직렬화합니디.
• 오답 피드백: "영철 님, 필요한 것만 걸러내는 거름망 이름이 partialize(부분화)입니다. 꼭 외워두세요!"
• 📌 핵심 기억법: 🦁 영호: "토큰은 휘발시키고, 프로필은 Partialize로 백업하세요."

Q3. 🏋️‍♂️ 영철의 테스트 타임 (Q&A)

영철이가 쇼핑 앱의 '최근 본 상품 ID 목록'을 사용자의 기기에 영구히 기억시킬 목적으로 Zustand persist (localStorage) 에 저장했습니다. 헌데 옆자리 영수 님이 "장바구니 결제 토큰도 거기에 같이 저장하면 안 되냐"고 제안을 하네요. 어떻게 방어해야 할까요?

✅ 정답: 결제 토큰처럼 탈취 시 치명적인 권한 제어 키는 partialize 함수를 이용해 로컬 스토리지 백업 대상에서 반드시 제외시킨다. 혹은 백엔드에서 HttpOnly 쿠키로 설계하도록 역제안한다.

💡 상세 해설:

• 원리 설명: LocalStorage에 기록된 값은 현재 탭에 열려있는 어떠한 서드파티 스크립트(구글 애널리틱스, 외부 광고 배너 등)나 악성 XSS 주입 코드라도 window.localStorage.getItem 명령 하나로 훔쳐갈 수 있습니다. UI 렌더링 최적화를 위한 부가 정보만 Persist에 의존해야 합니다.
• 오답 피드백: "영철 님, PM이 해달라고 다 해주면 안 돼요. 결제 토큰은 메모리(accessToken 속성)에 두고 새로고침 시 날린 다음 Silent Refresh 기법으로 백엔드에서 다시 받아오게 설계해야 사고를 막습니다."
• 📌 핵심 기억법: 👔 영수: "서버가 알면 큰일 나는 데이터는 없지만, 클라이언트(JS) 영역에 남으면 큰일 나는 데이터는 수도 없이 많다."

🐣 영철이의 퇴근 일기

오늘은 영수 PM님한테 뼈를 엄청 세게 맞았다. "내 정보 내가 쓰게 스토리지에 저장하겠다는데 뭐가 문제야!" 라고 속으로 투덜댔었는데, XSS 공격이란 걸 듣고 나니까 그동안 내가 만든 회원가입 로직이 시한폭탄이었다는 걸 깨달았다. Zustand persist 미들웨어에서 partialize 옵션 하나 딱 넣어서 토큰 빼고 저장하니까 보안과 사용자 편의를 둘 다 잡은 기분이다! 후후, 이런 보안 개념까지 아는 주니어가 흔할까? 내일 영호 리드 님한테 은근슬쩍 자랑해봐야지. 달달한 아이스크림 하나 먹고 푹 자야겠다 🍦!

💡 "로컬 스토리지는 모두가 보는 투명한 게시판이다. 인증 키는 숨기고, 껍데기 정보만 기록하자."