[로그인인증] 시리즈 안내 (00)

로그인 기능은 거의 모든 서비스에 들어가지만, 막상 처음부터 직접 만들어 본 개발자는 드뭅니다. 보통은 프레임워크나 인증 서비스가 대신 해 주고, 우리는 "로그인하면 토큰이 온다" 정도만 압니다. 그러다 어느 날 이런 질문을 받습니다.

• 액세스 토큰은 어디에 저장해야 하나요? localStorage 는 왜 안 되죠?
• 리프레시 토큰을 탈취당하면 어떻게 되나요?
• 탭을 두 개 열어 두면 가끔 로그아웃되는 버그는 왜 생기나요?
• 쿠키를 쓰면 CSRF 를 막아야 한다는데, SameSite 만 켜면 되는 거 아닌가요?

이 책은 이 질문들에 직접 만들어 보고 직접 공격해 보는 방식으로 답합니다. 실제로 토큰을 발급하고, 회전시키고, 탈취된 토큰을 탐지하고, 공격 페이지를 만들어 CSRF 를 성공시킨 다음 방어를 한 겹씩 입혀 공격이 실패하는 것을 눈으로 확인합니다.

무엇을 만드는가

auth-lab — 프론트엔드와 백엔드가 분리된 로그인 앱입니다.

완성된 앱은 다음을 합니다.

• 가입·로그인. 비밀번호는 argon2id 로 해싱합니다.
• 로그인하면 액세스 토큰(JWT, 10분) 을 응답 본문으로, 리프레시 토큰(14일) 을 HttpOnly 쿠키로 줍니다.
• 액세스 토큰이 만료되면 FE 가 알아서 리프레시하고, 그때마다 리프레시 토큰을 새것으로 바꿉니다(회전).
• 이미 쓴 리프레시 토큰이 다시 오면 탈취로 보고 그 세션 전체를 끊습니다(재사용 탐지).
• 로그인된 기기 목록을 보고 하나씩 끊거나 전부 끊을 수 있습니다.
• 쿠키를 쓰는 요청은 SameSite · Origin 검사 · CSRF 토큰 세 겹으로 지킵니다.
• 프론트엔드 개발자는 Swagger 문서만 보고 작업합니다. API 타입은 문서에서 자동으로 만들어집니다.

누구를 위한 책인가

• JavaScript/TypeScript 로 웹 앱을 만들어 본 개발자
• HTTP 요청과 응답, 상태 코드, 헤더가 무엇인지 아는 개발자
• NestJS 와 React 는 몰라도 됩니다. 필요한 만큼 그때그때 설명합니다.

쿠키와 CORS 는 몰라도 됩니다. 1장에서 처음부터 다룹니다.

이 책이 다루지 않는 것

• 소셜 로그인(OAuth 2.0 / OpenID Connect). 이 책의 토큰 설계를 이해하면 OAuth 의 토큰 흐름이 훨씬 쉽게 읽힙니다.
• 다중 인증(MFA), 비밀번호 재설정 메일, 이메일 인증
• 모바일 앱 클라이언트. 쿠키가 아닌 저장소를 쓰므로 설계가 달라집니다.

차례

1부. 원리

2부. 백엔드 — 토큰을 발급한다

3부. CSRF — 공격하고 막는다

4부. 프론트엔드 — Swagger 만 보고 붙인다

5부. 마무리

부록

• 부록 A. 쿠키·헤더 레퍼런스
• 부록 B. 문제 해결
• 부록 C. 완성 코드
• 부록 D. 네트워크 탭 확인

한 장의 그림으로 보는 전체 흐름

 브라우저 (localhost:5173)                         API (localhost:4000)                  PostgreSQL
 ─────────────────────────                        ─────────────────────                 ──────────
 ① GET /auth/csrf ─────────────────────────────▶  CSRF 토큰 생성
   ◀──── { csrfToken } + Set-Cookie: csrf_token
   (csrfToken 은 메모리에)

 ② POST /auth/login ───────────────────────────▶  CsrfGuard: Origin 확인, 헤더=쿠키 확인
    X-CSRF-Token: …                                비밀번호 argon2 검증
    { email, password }                            리프레시 토큰 생성 ─────────────────▶ INSERT (해시만)
   ◀──── { accessToken, user }                     액세스 토큰(JWT) 서명
         + Set-Cookie: refresh_token (HttpOnly)
   (accessToken 은 메모리에)

 ③ GET /users/me ──────────────────────────────▶  JwtAuthGuard: 서명·만료·iss·aud 확인
    Authorization: Bearer <accessToken>
   ◀──── { id, email, nickname }

    … 10분 뒤 액세스 토큰 만료 …

 ④ GET /users/me ─────────────────────────────▶   401 ACCESS_TOKEN_INVALID
 ⑤ POST /auth/refresh ────────────────────────▶   CsrfGuard
    Cookie: refresh_token (브라우저가 자동으로)      family 잠금, SELECT … FOR UPDATE ──▶ 옛 토큰 잠금
                                                   새 토큰 INSERT, 옛 토큰 rotated ───▶ 회전
   ◀──── { accessToken } + Set-Cookie: 새 refresh_token
 ⑥ GET /users/me (재시도) ────────────────────▶   200

이 그림의 번호 하나하나가 책의 한 장씩입니다. ①은 9장, ②는 5·6장, ③은 5장, ④~⑥은 7장과 12장에서 만듭니다.

실습 환경

준비물

이 책이 쓴 패키지 버전

2026년 9월에 npm 레지스트리에서 확인한 최신 버전입니다. 버전이 올라가면 API 가 바뀔 수 있으니, 책과 다르게 동작하면 먼저 버전을 확인하고 해당 패키지의 공식 문서를 보세요.

ORM 을 쓰지 않는 이유. 이 책은 SQL 을 pg 로 직접 씁니다. 리프레시 토큰 회전의 핵심은 트랜잭션과 행 잠금(SELECT … FOR UPDATE)인데, ORM 을 쓰면 이 부분이 추상화 뒤로 숨어 버립니다. 인증 로직의 모든 줄이 눈에 보이는 것이 이 책의 목표라 SQL 을 그대로 드러냈습니다. 실무에서 ORM 을 쓴다면 7장의 트랜잭션만 그 ORM 의 방식으로 옮기면 됩니다.

폴더 구조

~/Workspace/auth-lab/
├── curriculum/        ← 지금 읽고 있는 책
├── docker-compose.yml
├── contract/          ← BE 가 내보낸 openapi.json (10장)
├── api/               ← NestJS
├── web/               ← React
└── evil/              ← 공격 페이지 (8장)

각 장의 구성

모든 장은 같은 순서를 따릅니다.

1. 이 장을 마치면 — 장이 끝났을 때 할 수 있어야 하는 일
2. 들어가며 — 왜 이 장이 필요한가, 앞 장과 어떻게 이어지는가
3. 본문 — 이론 → 코드 → 실행 → 결과 확인을 한 묶음으로 반복합니다
4. 확인하기 — 명령과 기대 결과. 여기가 통과해야 다음 장으로 넘어갑니다
5. 자주 하는 실수 — 실제로 막히는 곳과 증상
6. 정리
7. 연습문제 — 해답은 문제 바로 아래 접힌 칸에 있습니다. 먼저 풀고 여세요

표기

• $ 로 시작하는 줄은 터미널 명령, 그 아래는 출력입니다.
• 코드 블록 위의 // api/src/auth/auth.service.ts 같은 주석은 파일 경로입니다.
• 이미 있는 파일을 고칠 때는 바뀌는 부분만 보여 주고 // … 로 나머지를 줄입니다. 전체 모습이 필요하면 부록 C 를 보세요.
• 💡 는 알아 두면 좋은 배경, ⚠️ 는 틀리기 쉬운 곳입니다.

먼저 알아 둘 용어

이 책에서 반복해서 쓰는 말입니다. 1장과 2장에서 자세히 다룹니다.