---
id: pattern-jwt-authentication
title: "JWT Authentication Pattern"
category: "Pattern_Web"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["JWT", "토큰 인증", "access token", "refresh token", "stateless auth"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.86
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["pattern", "web", "auth", "jwt", "security", "platform-independent"]
raw_sources: ["일반 웹 보안 공학 지식"]
applied_in: []
github_commit: ""
---

# [[JWT Authentication Pattern]]

## 🎯 한 줄 통찰 (One-line insight)
JWT 인증은 "서명된 토큰에 사용자 정보를 담아 *서버 세션 없이* 상태 무관(stateless) 인증" 을 하는 패턴으로, 확장성은 좋지만 *토큰을 즉시 무효화하기 어렵다* 는 본질적 약점이 있다.

## 🧠 핵심 개념 (Core concepts)
1. **access token(짧은 수명) + refresh token(긴 수명):** 짧은 access 로 노출 위험↓, refresh 로 재발급.
2. **서명 검증:** 서버 비밀키로 서명, 변조 시 검증 실패(저장 불필요).
3. **claims:** sub/exp/role 등 페이로드(민감정보 금지 — base64 는 암호화 아님).
4. **저장 위치:** httpOnly 쿠키(XSS 안전) vs localStorage(XSS 취약).
5. **무효화:** 블랙리스트/짧은 만료/회전으로 보완.

## 📖 세부 내용 (Details · 패턴 명세)
- **Problem (언제 쓰나):** 분산/무상태 API, 여러 서비스가 같은 토큰 검증(SSO), 모바일+웹 공용.
- **사용 조건:** 비밀키 안전 보관; HTTPS; 토큰 수명 정책.
- **장점:** 무상태(수평 확장), 서비스 간 공유, DB 조회 없이 검증.
- **단점:** 즉시 무효화 어려움(로그아웃/탈취), 페이로드 노출, 토큰 비대.
- **대안:** 서버 세션(즉시 무효화 쉬움, 상태 필요), OAuth/OIDC(위임), API key(머신).
- **실패 사례:** localStorage 저장→XSS 탈취; refresh 회전 없이 탈취 지속; 민감정보를 claims 에; 만료 너무 길어 탈취 피해 확대; 서명 알고리즘 `none` 허용.

## 💻 코드 패턴 (Code patterns)
```text
login: verify(creds) -> access=sign({sub,exp:15m}), refresh=sign({sub,exp:7d}); setHttpOnlyCookie
request: verifySignature(access) && !expired -> allow ; else 401
refresh: verify(refresh) && !revoked -> rotate(new access+refresh), invalidate old
logout: revoke(refresh)  # 블랙리스트/회전
```

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
"JWT 가 세션보다 낫다" 는 과장 — 즉시 무효화·서버측 제어가 중요하면 세션이 낫다. JWT 는 *무상태 확장* 이 목적일 때.

## 🛠️ 적용 사례 (Applied in summary)
일반 웹/모바일 API 인증. (AstraAI 는 로컬 도구라 직접 사례 없음 — provider API key 는 [[API Client Pattern]] 참조.)

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[패턴 카탈로그 인덱스]]
- **관련 개념:** [[API Client Pattern]], [[웹 개발 가이드]], [[소프트웨어 실패 라이브러리]]
- **참조 맥락:** 작은 모델이 웹/모바일 인증을 구현할 때 참조.

## 📚 출처 (Sources)
- [S1] 일반 웹 보안/JWT 지식(RFC 7519, OWASP)

## 📝 변경 이력 (Change history)
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
