[Next.js] Next.js로 HttpOnly 쿠키 + BFF(프록시)아키텍처로 인증 보안/성능 잡기 - 클라이언트 사이드 인증의 보안 문제와 HttpOnly 쿠키를 활용한 개선 방법

 

 

Next.js 프로젝트를 리팩토링하는 과정에서 예상치 못한 보안 이슈를 발견하게 되었습니다. 바로 브라우저의 개발자 도구에서 쿠키에 저장된 토큰이 그대로 노출되고 있었다는 점입니다. 토큰은 사용자 인증과 보안을 위해 가장 중요한 값 중 하나인데, 이 값이 그대로 클라이언트 측에서 확인 가능하다면 XSS(교차 사이트 스크립트 공격)나 토큰 탈취 등의 보안 취약점으로 이어질 수 있습니다.

이를 개선하기 위해 기존 코드 구조와 인증 방식을 다시 점검하게 되었고, 특히 토큰을 어디에 저장하고, 어떻게 전달할 것인가라는 주제에 집중했습니다. 프론트엔드와 백엔드 간 통신 구조, 쿠키 옵션 설정(HttpOnly, Secure 등), 프록시 서버의 역할까지 전반적으로 살펴보면서 코드를 수정해 나갔습니다.

이번 글에서는 제가 겪은 문제 상황과, 그것을 어떻게 개선했는지에 대한 과정을 정리해 보려고 합니다. 

 

기존 코드: 클라이언트(JS)에서 토큰을 직접 저장/주입 → HttpOnly 사용 불가, XSS/탈취 위험.
리팩토링: Next.js 서버가 토큰을 HttpOnly 쿠키로만 관리하고, 클라이언트 보호 API는 프록시(BFF)로 호출.

 

 

 

---

 

🐛 기존 코드 문제 짚어보기

1️⃣ XSS 공격에 완전히 노출된 토큰

// 기존 AuthService.ts
class AuthService {
  private static userAccount: string | null = StorageService.get('userAccount');
  private static token: string | null = StorageService.get('token');

  static login(userAccount: string, token: string): void {
    this.userAccount = userAccount;
    this.token = token;
    StorageService.setStorageAdapter('localStorage');
    StorageService.set('userAccount', userAccount);
    StorageService.setStorageAdapter('cookieStorage');
    StorageService.set('token', token, {
      expires: 3,
      path: '',
    });
  }

  static getToken(): string | null {
    return this.token || StorageService.get('token');
  }
}

// LoginPage에서의 사용
const onSubmit = async (data: ILoginRequest) => {
  try {
    const response = await login(data);
    const { token, accountname } = response.user;
    if (token && accountname) {
      AuthService.login(accountname, token); // 클라이언트에서 직접 저장
      goTo('/feed');
    }
  } catch (error) {
    console.error('로그인 에러:', error);
  }
};

• JavaScript로 쿠키를 set/get 하면 HttpOnly를 사용할 수 없어 XSS가 터지면 토큰 탈취가 가능합니다.
• 토큰이 일반 쿠키나 localStorage에 저장되어 JavaScript로 접근이 가능합니다.
• 아래와 같이 XSS 공격자가 단 한 줄의 JavaScript 코드로 사용자의 인증 토큰을 탈취할 수 있습니다. 

// 악성 스크립트가 쉽게 토큰을 탈취할 수 있음
console.log(document.cookie); // 토큰이 그대로 노출
console.log(localStorage.getItem('token')); // 토큰 직접 접근 가능

 

2️⃣ CSRF 공격 방어 부족

// 기존 코드 - SameSite 보호 없음
StorageService.set('token', token, {
  expires: 3,
  path: '', // SameSite, Secure 옵션 없음
});

• 일반 쿠키는 SameSite 설정이 없으면 모든 도메인에서 자동으로 전송됩니다.
• 악성 사이트에서 사용자 모르게 요청을 보내면 브라우저가 자동으로 토큰을 포함해서 전송합니다.

 

3️⃣ 복잡한 저장소 관리 로직

// 저장소 타입을 계속 바꾸는 복잡한 로직
StorageService.setStorageAdapter('localStorage');
StorageService.set('userAccount', userAccount);
StorageService.setStorageAdapter('cookieStorage');
StorageService.set('token', token, { expires: 3, path: '' });

• localStorage와 cookieStorage를 번갈아 사용하는 복잡한 로직으로 인한 버그 가능성이 높습니다.
• 직접적인 보안 위험은 아니지만, 복잡성으로 인해 다른 보안 버그가 발생할 가능성이 높습니다.

 

---

 

 

문제 흐름을 정리해 보면

AuthService.login()이 localStorage + cookieStorage에 토큰을 저장
StorageService는 JS에서 쿠키를 직접 set() (HttpOnly 설정 불가)
Axios 인스턴스/인터셉터는 클라이언트에서 토큰을 헤더에 붙여 전송하는 흐름

 

👉 지금 구조는 구현은 간단하지만, 실서비스 보안 기준(특히 XSS/토큰 보호)에선 취약합니다.

 

---

 

💡 Next.js HttpOnly 쿠키를 활용한 보안 개선하기

1. 개선 목표: 프록시 패턴으로 기존 코드 최대한 보존하며 리팩토링하기

기존 코드의 95%를 그대로 유지하면서 보안만 크게 개선하는 방법 사용하였습니다.

기존: 클라이언트 → 외부 API → 응답 → 클라이언트에서 쿠키 저장
개선: 클라이언트 → Next.js API Route → 외부 API → 서버에서 HttpOnly 쿠키 저장

// 폴더 구조
frontend/
├── app/
│   ├── api/                # ✅ Next.js API Route Handlers (BFF)
│   │   ├── user/
│   │   │   └── login/
│   │   │       └── route.ts    # POST /api/user/login
│   │   └── post/
│   │       └── feed/
│   │           └── route.ts    # GET /api/post/feed
│   ├── (auth)/
│   │   └── login/page.tsx
│   └── feed/page.tsx
│
├── src/
│   ├── api/
│   │   ├── apiRequests/     # ✅ 클라이언트에서 호출하는 함수 모음
│   │   │   ├── auth.ts      # login, signup 등
│   │   │   └── post.ts      # postList 등
│   │   └── index.ts         # axios instance
│   │
│   ├── components/          # 공통 컴포넌트
│   ├── services/            # AuthService, StorageService 등 (클라 전용)
│   └── queries/             # react-query hooks
│
└── .env.local               # BACKEND_BASE_URL 등 환경변수

 

2. 개선 방향: Next BFF(프록시) + HttpOnly 쿠키

• 로그인: Next 서버 라우트가 백엔드 로그인 API를 호출 → 응답받은 토큰을 HttpOnly 쿠키로 서버가 설정.
• 보호 API 호출: 클라이언트는 백엔드로 직접 가지 않고 Next 프록시로 호출 → 프록시가 쿠키에서 토큰을 꺼내 Authorization 헤더를 서버에서만 주입.
• 세션 확인: 서버 라우트에서 쿠키 토큰으로 확인 → 클라에는 “인증됨/아님 + 최소 정보”만 전달.
• 클라이언트는 토큰을 영영 모른다. (이게 포인트!)

 

3. 단계별 리팩토링

클라이언트에서 토큰 다루는 코드 제거 → Next 라우트/프록시에서만 쿠키/토큰 제어

1️⃣ 보안 강화된 로그인 API Route 생성

// app/api/auth/login/route.ts (BFF, Next.js 서버에서만 실행)
import { cookies } from 'next/headers'; // (서버 컴포넌트나 Route Handler(app/api)에서만 호출 가능한 서버 컴포넌트 전용 API)
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const body = await request.json();

  // 1. 기존 외부 API 호출
  const response = await fetch(
    `${process.env.NEXT_PUBLIC_BASE_URL}/user/login`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    },
  );

  const data = await response.json();

  if (response.ok && data.user?.token) {
    // 2. 🛡️ HttpOnly 쿠키로 보안 저장
    cookies().set('token', data.user.token, {
      httpOnly: true, // XSS 공격 방어
      secure: process.env.NODE_ENV === 'production', // HTTPS에서만 전송
      sameSite: 'strict', // CSRF 공격 방어
      maxAge: 60 * 60 * 24 * 3, // 3일
      path: '/',
    });

    // 3. 🔒 클라이언트에는 토큰 없이 안전한 응답
    return NextResponse.json({
      ...data,
      user: {
        ...data.user,
        token: undefined, // 토큰 제거로 클라이언트 노출 방지
      },
    });
  }

  return NextResponse.json(data, { status: response.status });
}

• 로그인 요청 후 토큰을 HttpOnly + Secure 쿠키에 저장
• HttpOnly 쿠키를 읽거나 세팅할 수 있음
• 백엔드 API에 요청을 대리로 보냄

 

2️⃣ Axios 인스턴스 프록시를 기본 baseURL로

// src/api/index.ts
import axios, { AxiosInstance } from 'axios';

import { handleRequest, handleRequestError } from './helper/requestHandlers';
import { handleResponse, handleResponseError } from './helper/responseHandlers';

const instance: AxiosInstance = axios.create({
  baseURL: '/api', // Next.js의 API 라우트 사용 (기존: process.env.NEXT_PUBLIC_BASE_URL)
  withCredentials: true, // 쿠키 자동 전송
});

instance.interceptors.request.use(handleRequest, handleRequestError);
instance.interceptors.response.use(handleResponse, handleResponseError);

export default instance;

 

3️⃣ AuthService/StorageService 정리 및 로그인 페이지

// services/AuthService.ts
import StorageService from './StorageService';

class AuthService {
  private static userAccount: string | null = StorageService.get('userAccount');

  static login(userAccount: string): void {
    this.userAccount = userAccount;
    StorageService.setStorageAdapter('localStorage');
    StorageService.set('userAccount', userAccount);
  }
...
}

export default AuthService;

• 토큰을 저장/조회하는 모든 메서드 삭제

 

4️⃣ 피드 라우트 생성 (헤더에 토큰 주입)

// app/api/post/feed/route.ts
import { cookies } from 'next/headers';
import { NextResponse } from 'next/server';

export async function GET(req: Request) {
  const { searchParams } = new URL(req.url);
  const limit = searchParams.get('limit');
  const skip = searchParams.get('skip');

  const token = cookies().get('token')?.value;

  const res = await fetch(
    `${process.env.BACKEND_BASE_URL}/post/feed/?limit=${limit}&skip=${skip}`,
    {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json',
        ...(token ? { Authorization: `Bearer ${token}` } : {}),
      },
      cache: 'no-store', // 항상 최신 데이터
    },
  );

  const data = await res.json();
  return NextResponse.json(data);
}

 

• 클라이언트 → BFF 요청 시 쿠키 포함 (withCredentials: true)
• BFF → 백엔드 요청 시 쿠키에서 token 추출 → Authorization 헤더로 변환

👉 클라이언트는 단순히 /api/... 만 호출하면 되고, 보안/토큰 관리는 전부 Next.js 서버 (app/api)가 처리합니다.

 

📌 최종 구조 흐름

[클라이언트 컴포넌트]
      │
      ▼
로그인 요청 (email, password)
      │
      ▼
Axios → /api/auth/login
      │
      ▼
[Next.js Route Handler (/api/auth/login)]
  - 백엔드로 로그인 요청 전달
  - 성공 시 JWT 토큰 수신
  - Response 쿠키(token=..., HttpOnly)로 저장
      │
      ▼
브라우저 저장소
  - HttpOnly 쿠키(token) 자동 보관
  - JS에서 직접 접근 불가
      │
      ▼
──────────────────────────────
      이후 API 요청 흐름
──────────────────────────────
      │
      ▼
클라이언트에서 postList(limit, skip) 호출
      │
      ▼
Axios → /api/post/feed
      │
      ▼
[Next.js Route Handler (/api/post/feed)]
  - cookies() 로 HttpOnly 토큰 꺼냄
  - Authorization: Bearer <token> 헤더 붙임
      │
      ▼
[백엔드 API 서버 호출]
  - 토큰 검증
  - 데이터 반환
      │
      ▼
Next.js Route Handler → 클라이언트 응답

 

🛡️ 보안 개선 효과

Before vs After 비교

HttpOnly 쿠키 리팩토링 전/후

보안 요소	기존 방식	개선된 방식
XSS 방어	❌ JavaScript로 토큰 접근 가능	✅ HttpOnly로 JavaScript 접근 차단
CSRF 방어	❌ SameSite 설정 없음	✅ SameSite=strict로 완벽 차단
HTTPS 강제	❌ HTTP에서도 토큰 전송	✅ Secure 속성으로 HTTPS만 허용
토큰 노출	❌ 개발자 도구에서 완전 노출 -> 탈취 가능	✅ 서버에서만 접근 가능 -> 탈취 불가
코드 복잡성	❌ 복잡한 저장소 로직	✅ 간단하고 명확한 구조

 

🛠️ 이후 개선 방향

현재는 각 API 라우트에서 쿠키를 직접 읽고, 요청마다 Authorization 헤더를 붙여주는 방식으로 구현되어 있습니다. 기능적으로는 문제없지만, 토큰이 필요한 API가 많아질수록 중복 코드가 늘어난다는 단점이 있습니다.

그래서 다음 단계에서는 범용 프록시 구조로 리팩터링 할 예정입니다.

 

• 프론트엔드에서는 단순히 /app/api/... 로 요청
• 프록시 레이어가 자동으로 쿠키에서 토큰을 읽어 Authorization 헤더를 붙이고 백엔드에 전달
• API 엔드포인트가 수십, 수백 개로 늘어나더라도 프록시 코드 하나만 유지하면 전체가 동작

👉  중복 코드 제거 + 유지보수성 향상 + 보안 일관성 강화

 

 

 

---

 

 

 

처음에는 “토큰이 보이면 안 되겠다”는 단순한 문제의식에서 출발했지만, HttpOnly 쿠키와 프록시 라우팅을 적용하면서 보안뿐만 아니라 코드 구조가 훨씬 간결해지고, 결과적으로 개발 흐름도 매끄러워졌습니다.

결국 이번 작업으로 단순한 버그 수정이 아니라, 서비스를 더 안전하게 만들고 개발 환경까지 개선할 수 있었습니다.

앞으로도 이런 작은 개선들을 꾸준히 쌓아가면서 더 안정적이고 즐겁게 개발할 수 있는 환경을 만들어가고 싶습니다.

끝으로 이 글이 비슷한 고민을 하고 계신 분들께 작은 도움이 되길 바랍니다!