🔑 Spring Boot에서 JWT(Json Web Token) 인증 구현하기

📌 JWT란 무엇인가?

JWT(Json Web Token)는 JSON 형식으로 사용자 정보를 안전하게 전달하기 위한 토큰 기반 인증 방식입니다. 사용자가 로그인하면 서버는 JWT를 발급하고, 이후 요청마다 클라이언트는 이 토큰을 헤더에 담아 보냅니다. 서버는 별도의 세션 저장소 없이도 토큰만으로 사용자를 인증할 수 있습니다.

---

📦 JWT의 구조

JWT는 .으로 구분된 세 부분으로 이루어집니다.

xxxxx.yyyyy.zzzzz

• Header (헤더)
  토큰의 타입(JWT)과 해싱 알고리즘(예: HS256) 정보를 담습니다.

  {
    "alg": "HS256",
    "typ": "JWT"
  }

• Payload (페이로드)
  실제 담고 싶은 사용자 정보(Claims)입니다.
  예: 사용자 이름, 권한, 만료 시간 등.

  {
    "sub": "user123",
    "iat": 1691234567,
    "exp": 1691238167
  }

• Signature (서명)
  Header와 Payload를 비밀 키(Secret Key)로 서명한 값입니다. 토큰 위·변조 여부를 검증할 때 사용됩니다.

---

🛠 코드 소개

이번에 작성한 JwtTokenProvider 클래스는 Spring Security에서 JWT를 생성하고 검증하는 핵심 역할을 담당합니다. 구체적으로는 다음과 같은 역할을 수행합니다.

• 토큰 생성 (generateToken)
• 토큰에서 사용자 이름 추출 (getUsername)
• 토큰 유효성 검증 (validate)

---

📝 코드 전체

package com.example.demo.security;

import io.jsonwebtoken.*;
import io.jsonwebtoken.io.Decoders;
import io.jsonwebtoken.security.Keys;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.stereotype.Component;

import javax.crypto.SecretKey;
import java.util.Date;

@Component
public class JwtTokenProvider {

    // HMAC-SHA 알고리즘을 위한 시크릿 키와 토큰 만료 시간
    private final SecretKey key;
    private final long expirationMs;

    // 생성자: application.yml에서 시크릿 키와 만료 시간 주입
    public JwtTokenProvider(
            @Value("${jwt.secret}") String secret,
            @Value("${jwt.expiration-ms}") long expirationMs
    ) {
        byte[] keyBytes = (secret.matches("^[A-Za-z0-9+/=]+$") ? Decoders.BASE64.decode(secret) : secret.getBytes());
        this.key = Keys.hmacShaKeyFor(keyBytes);
        this.expirationMs = expirationMs;
    }
    // 핵심: 토큰을 만들고 검증하는 데 필요한 시크릿 키와 만료 시간을 application.yml에서 가져와서 준비하는 과정

    // ✅ JWT 토큰 생성
    public String generateToken(UserDetails user) {
        Date now = new Date();
        Date exp = new Date(now.getTime() + expirationMs);

        return Jwts.builder()
                .setSubject(user.getUsername())   // 토큰의 주체(사용자 이름)
                .setIssuedAt(now)                 // 토큰 발행 시간
                .setExpiration(exp)               // 토큰 만료 시간
                .signWith(key, Jwts.SIG.HS256)    // 시크릿 키로 HS256 알고리즘을 사용하여 토큰에 서명
                .compact();                       // 최종적으로 문자열로 압축하여 반환
    }
    // 핵심: 토큰에 사용자 이름, 발행 시간, 만료 시간 등의 정보를 담고, 시크릿 키로 서명하여 안전하게 생성하고 문자열 형태로 변환하는 과정

    // ✅ 토큰에서 사용자 이름 추출
    public String getUsername(String token) {
        return Jwts.parser()
                .verifyWith(key)                 // 토큰의 서명을 시크릿 키로 검증
                .build()
                .parseSignedClaims(token)        // 토큰을 파싱하고 클레임(정보)을 가져옴
                .getPayload()
                .getSubject();                   // 토큰의 주체(사용자 이름) 반환
    }
    // 핵심: 토큰이 유효한지 먼저 확인한 다음, 그 안에 담긴 사용자 이름을 추출하는 과정

    // ✅ 토큰 유효성 검증
    public boolean validate(String token) {
        try {
            // 토큰을 파싱하고 서명을 검증
            Jwts.parser().verifyWith(key).build().parseSignedClaims(token);
            return true;
        } catch (JwtException | IllegalArgumentException e) {
            // 토큰이 잘못되었거나 만료된 경우 예외 발생
            return false;
        }
    }

    // 토큰 만료 시간 반환
    public long getExpirationMs() {
        return expirationMs;
    }
}

---

🔍 세부 설명

1. 생성자

public JwtTokenProvider(@Value("${jwt.secret}") String secret, @Value("${jwt.expiration-ms}") long expirationMs)

application.yml에서 jwt.secret과 jwt.expiration-ms 값을 읽어옵니다. 이 값들로 HMAC-SHA256 알고리즘에 맞는 SecretKey 객체를 생성하여 토큰 서명에 사용합니다.

2. 토큰 생성 (generateToken)

public String generateToken(UserDetails user)

user.getUsername()을 토큰의 Subject로 설정하고, 발행 시간(IssuedAt)과 만료 시간(Expiration)을 지정합니다. signWith(key, Jwts.SIG.HS256)를 통해 시크릿 키 기반으로 서명하여 위변조를 방지합니다. 최종적으로 문자열 형태의 JWT를 반환합니다.

3. 토큰에서 사용자 이름 추출 (getUsername)

public String getUsername(String token)

토큰을 파싱하고 서명을 검증한 뒤, Payload의 Subject(사용자 이름)를 꺼내옵니다.

4. 토큰 유효성 검증 (validate)

public boolean validate(String token)

parseSignedClaims(token) 실행 시 예외가 발생하지 않으면 true를 반환합니다. 만료되었거나 위조된 경우 JwtException이 발생하여 false를 반환합니다.

---

✅ 정리 및 배운 점

• JWT는 세션 저장소 없이 인증 상태를 유지할 수 있는 강력한 방법입니다.
  -JwtTokenProvider는 토큰 발급과 검증 로직을 담당하며 Spring Security와 자연스럽게 연동됩니다.
• 보안을 위해 시크릿 키는 반드시 환경 변수로 관리해야 하며, 외부에 노출되지 않도록 주의해야 합니다.

---

🚀 확장

• Refresh Token 발급 및 재발급 기능 추가: Access Token 만료 시 사용자 경험을 개선할 수 있습니다.
• 권한(Role) 정보를 토큰에 함께 저장하여 Spring Security의 Authentication 객체로 변환할 수 있습니다.
• 예외 처리 강화: 단순히 true/false 대신 "만료됨 / 위조됨 / 형식 오류" 등 구체적인 응답을 제공하여 클라이언트가 문제를 정확히 파악할 수 있도록 돕습니다.