Spring Security 7.0 + jjwt 0.12.6로 JWT 인증 구현하기

Spring Security 7.0 + jjwt 0.12.6 JWT 인증 Spring Boot 4.0 · Spring Security 7.0 환경에서 jjwt 0.12.x로 JWT 인증을 처음부터 구현하는 전체 과정을 기록한다.

---

들어가며

Spring Boot 4.0.3 기반 프로젝트를 세팅하면서 JWT 인증 구조를 처음부터 잡았다.
예전에 쓰던 jjwt 0.11.x 코드를 그대로 가져왔다가 컴파일 에러를 꽤 만났는데, 0.12.x에서 API가 상당히 정리됐기 때문이다.
Spring Security 7.0도 WebSecurityConfigurerAdapter가 완전히 제거됐고, Jackson 3.0 전환에 따른 변화도 있어서 구버전 예제를 그대로 쓰면 안 되는 부분이 많았다.

이 글은 JWT 인증 전체 흐름을 구현한 과정을 기록한다.

---

JWT 구조 복습

JWT(JSON Web Token)는 RFC 7519로 정의된 토큰 형식이다.
Header.Payload.Signature 세 파트를 점(.)으로 이어 붙인 Base64URL 인코딩 문자열로 구성된다.

eyJhbGciOiJIUzI1NiJ9
.eyJzdWIiOiJ1c2VyQGV4YW1wbGUuY29tIiwicm9sZSI6IlVTRVIiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDAwMzYwMH0
.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

파트	내용
Header	서명 알고리즘 (alg: HS256), 토큰 타입 (typ: JWT)
Payload	클레임(Claims) — sub, iat, exp 등 표준 클레임 + 커스텀 클레임
Signature	HMAC-SHA256(base64url(header) + "." + base64url(payload), secretKey)

Payload는 Base64URL로 인코딩된 것이지 암호화된 게 아니다.
누구나 디코딩해서 내용을 볼 수 있으므로, 비밀번호나 민감한 개인정보는 절대 넣으면 안 된다.
Signature가 하는 역할은 "이 토큰이 우리 서버에서 발급됐고 변조되지 않았다"는 것을 보장하는 것이다.

---

Access Token과 Refresh Token 전략

Access Token만 단독으로 쓰면 만료 시간을 길게 잡을수록 탈취 위험이 커지고, 짧게 잡으면 사용자가 자주 재로그인해야 하는 UX 문제가 생긴다. 그래서 일반적으로 두 종류의 토큰을 함께 운용한다.

구분	Access Token	Refresh Token
용도	API 요청 인증	Access Token 재발급
만료 시간	짧게 (1시간 내외)	길게 (7일 ~ 30일)
저장 위치	메모리 또는 클라이언트	DB 또는 Redis
탈취 시 대응	만료까지 대기	서버에서 즉시 폐기 가능

Refresh Token은 서버 DB에 저장해두고, 재발급 요청이 들어오면 DB에 저장된 값과 비교 검증한다.
여기에 Refresh Token Rotation 전략을 더하면 보안이 강화된다.
재발급할 때마다 기존 Refresh Token을 폐기하고 새 토큰을 발급하는 방식인데,
탈취된 Refresh Token이 사용되는 순간 정상 사용자의 토큰도 무효화되어 이상 징후를 감지할 수 있다.

---

의존성 추가

jjwt는 0.12.x부터 API / 구현체 / JSON 파서를 분리해서 선언해야 한다.
jjwt-impl은 반드시 runtimeOnly로 선언해야 하는데, 내부 구현체에 컴파일 타임 의존성이 생기면 버전 업그레이드 시 호환성 문제가 발생할 수 있기 때문이다.

// build.gradle.kts
dependencies {
    implementation("io.jsonwebtoken:jjwt-api:0.12.6")
    runtimeOnly("io.jsonwebtoken:jjwt-impl:0.12.6")
    runtimeOnly("io.jsonwebtoken:jjwt-jackson:0.12.6")
}

Spring Boot 4.0은 Jackson 3.0을 기본으로 사용하지만, jjwt-jackson은 Jackson 2 기반이다.
이 프로젝트에서는 jjwt-jackson을 그대로 사용하고 Jackson 2 호환 의존성을 유지했다.
Jackson 3만 쓰고 싶다면 jjwt-gson으로 대체하거나 커스텀 JSON 파서를 등록하면 된다.

---

JwtProvider 구현

jjwt 0.12.x에서 달라진 핵심 API를 정리하면 다음과 같다.

0.11.x 버전	0.12.x 버전
Keys.secretKeyFor(SignatureAlgorithm.HS256)	Jwts.SIG.HS256.key().build() 또는 Keys.hmacShaKeyFor(bytes)
.signWith(key, SignatureAlgorithm.HS256)	.signWith(key) (알고리즘 자동 추론)
.parseClaimsJws(token)	.parseSignedClaims(token)
.setSubject(), .setExpiration()	.subject(), .expiration()

// src/main/java/com/example/security/jwt/JwtProvider.java
package com.example.security.jwt;

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

import javax.crypto.SecretKey;
import java.nio.charset.StandardCharsets;
import java.util.Date;

@Component
public class JwtProvider {

    private final SecretKey secretKey;
    private final long accessTokenExpiry;
    private final long refreshTokenExpiry;

    public JwtProvider(
            @Value("${jwt.secret}") String secret,
            @Value("${jwt.access-token-expiry:3600000}") long accessTokenExpiry,
            @Value("${jwt.refresh-token-expiry:604800000}") long refreshTokenExpiry
    ) {
        // HS256 기준 최소 256비트(32바이트) 이상의 키가 필요하다
        this.secretKey = Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8));
        this.accessTokenExpiry = accessTokenExpiry;
        this.refreshTokenExpiry = refreshTokenExpiry;
    }

    public String generateAccessToken(String email, String role) {
        return Jwts.builder()
                .subject(email)
                .claim("role", role)
                .issuedAt(new Date())
                .expiration(new Date(System.currentTimeMillis() + accessTokenExpiry))
                .signWith(secretKey)   // 0.12.x: 알고리즘 자동 추론, 별도 명시 불필요
                .compact();
    }

    public String generateRefreshToken(String email) {
        return Jwts.builder()
                .subject(email)
                .issuedAt(new Date())
                .expiration(new Date(System.currentTimeMillis() + refreshTokenExpiry))
                .signWith(secretKey)
                .compact();
    }

    public Claims parseToken(String token) {
        // 0.12.x: parseClaimsJws() 대신 parseSignedClaims() 사용
        return Jwts.parser()
                .verifyWith(secretKey)
                .build()
                .parseSignedClaims(token)
                .getPayload();
    }

    public String extractEmail(String token) {
        return parseToken(token).getSubject();
    }

    public boolean isTokenValid(String token) {
        try {
            parseToken(token);
            return true;
        } catch (ExpiredJwtException e) {
            // 만료된 토큰 — 재발급 흐름으로 유도
            return false;
        } catch (JwtException | IllegalArgumentException e) {
            // 서명 불일치, 형식 오류 등
            return false;
        }
    }
}

jwt.secret은 application.yml에서 환경 변수로 주입받는다.
운영 환경에서는 절대 소스 코드에 하드코딩하지 않는다.

# application.yml
jwt:
  secret: ${JWT_SECRET}           # 최소 32바이트 이상의 랜덤 문자열
  access-token-expiry: 3600000    # 1시간 (ms)
  refresh-token-expiry: 604800000 # 7일 (ms)

---

JwtAuthenticationFilter 구현

Spring Security 필터 체인에 JWT 검증 로직을 끼워 넣는다.
OncePerRequestFilter를 상속하면 같은 요청에서 필터가 중복 실행되는 것을 막아준다.
Authorization 헤더에서 Bearer 접두사를 제거하고 토큰을 추출한 뒤, 유효하면 SecurityContextHolder에 인증 정보를 설정한다.

// src/main/java/com/example/security/jwt/JwtAuthenticationFilter.java
package com.example.security.jwt;

import com.example.domain.user.UserRepository;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;

@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final JwtProvider jwtProvider;
    private final UserRepository userRepository;

    public JwtAuthenticationFilter(JwtProvider jwtProvider, UserRepository userRepository) {
        this.jwtProvider = jwtProvider;
        this.userRepository = userRepository;
    }

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain
    ) throws ServletException, IOException {

        String token = extractToken(request);

        if (StringUtils.hasText(token) && jwtProvider.isTokenValid(token)) {
            String email = jwtProvider.extractEmail(token);

            userRepository.findByEmail(email).ifPresent(user -> {
                var authToken = new UsernamePasswordAuthenticationToken(
                        user, null, user.getAuthorities()
                );
                authToken.setDetails(
                        new WebAuthenticationDetailsSource().buildDetails(request)
                );
                SecurityContextHolder.getContext().setAuthentication(authToken);
            });
        }

        filterChain.doFilter(request, response);
    }

    private String extractToken(HttpServletRequest request) {
        String bearerToken = request.getHeader("Authorization");
        if (StringUtils.hasText(bearerToken) && bearerToken.startsWith("Bearer ")) {
            return bearerToken.substring(7);
        }
        return null;
    }
}

---

SecurityConfig 설정

Spring Security 7.0에서는 WebSecurityConfigurerAdapter가 완전히 제거됐다.
SecurityFilterChain 빈을 직접 등록하는 방식만 지원하며, JWT 기반 Stateless 인증이므로 세션 생성 정책을 STATELESS로 설정하고 CSRF도 비활성화한다.

// src/main/java/com/example/security/SecurityConfig.java
package com.example.security;

import com.example.security.jwt.JwtAuthenticationFilter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.AuthenticationProvider;
import org.springframework.security.authentication.dao.DaoAuthenticationProvider;
import org.springframework.security.config.annotation.authentication.configuration.AuthenticationConfiguration;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {

    private final JwtAuthenticationFilter jwtAuthenticationFilter;
    private final UserDetailsService userDetailsService;

    public SecurityConfig(
            JwtAuthenticationFilter jwtAuthenticationFilter,
            UserDetailsService userDetailsService
    ) {
        this.jwtAuthenticationFilter = jwtAuthenticationFilter;
        this.userDetailsService = userDetailsService;
    }

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
                .csrf(AbstractHttpConfigurer::disable)
                .sessionManagement(session ->
                        session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/api/auth/**").permitAll()
                        .requestMatchers("/api/admin/**").hasRole("ADMIN")
                        .anyRequest().authenticated()
                )
                .authenticationProvider(authenticationProvider())
                .addFilterBefore(
                        jwtAuthenticationFilter,
                        UsernamePasswordAuthenticationFilter.class
                )
                .build();
    }

    @Bean
    public AuthenticationProvider authenticationProvider() {
        var provider = new DaoAuthenticationProvider();
        provider.setUserDetailsService(userDetailsService);
        provider.setPasswordEncoder(passwordEncoder());
        return provider;
    }

    @Bean
    public AuthenticationManager authenticationManager(
            AuthenticationConfiguration config
    ) throws Exception {
        return config.getAuthenticationManager();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

---

인증 API 구현

로그인 / 재발급 / 로그아웃

DTO는 Java 16+의 Record로 간결하게 정의했다.

public record LoginRequest(String email, String password) {}
public record RefreshRequest(String refreshToken) {}
public record TokenResponse(String accessToken, String refreshToken) {}

// src/main/java/com/example/api/auth/AuthController.java
package com.example.api.auth;

import com.example.security.jwt.JwtProvider;
import org.springframework.http.ResponseEntity;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/auth")
public class AuthController {

    private final AuthenticationManager authenticationManager;
    private final JwtProvider jwtProvider;
    private final RefreshTokenService refreshTokenService;

    public AuthController(
            AuthenticationManager authenticationManager,
            JwtProvider jwtProvider,
            RefreshTokenService refreshTokenService
    ) {
        this.authenticationManager = authenticationManager;
        this.jwtProvider = jwtProvider;
        this.refreshTokenService = refreshTokenService;
    }

    @PostMapping("/login")
    public ResponseEntity<TokenResponse> login(@RequestBody LoginRequest request) {
        Authentication auth = authenticationManager.authenticate(
                new UsernamePasswordAuthenticationToken(
                        request.email(), request.password()
                )
        );

        var user = (com.example.domain.user.User) auth.getPrincipal();
        String accessToken  = jwtProvider.generateAccessToken(user.getEmail(), user.getRole().name());
        String refreshToken = jwtProvider.generateRefreshToken(user.getEmail());

        refreshTokenService.save(user.getEmail(), refreshToken, user.getRole().name());

        return ResponseEntity.ok(new TokenResponse(accessToken, refreshToken));
    }

    @PostMapping("/refresh")
    public ResponseEntity<TokenResponse> refresh(@RequestBody RefreshRequest request) {
        String oldRefreshToken = request.refreshToken();

        if (!jwtProvider.isTokenValid(oldRefreshToken)) {
            return ResponseEntity.status(401).build();
        }

        String email = jwtProvider.extractEmail(oldRefreshToken);

        // DB에 저장된 토큰과 비교 — 불일치 시 예외 발생
        refreshTokenService.validate(email, oldRefreshToken);

        // Rotation: 기존 토큰 폐기 후 새 토큰 발급
        String newRefreshToken = jwtProvider.generateRefreshToken(email);
        String role = refreshTokenService.getRole(email);
        refreshTokenService.rotate(email, newRefreshToken);

        String newAccessToken = jwtProvider.generateAccessToken(email, role);

        return ResponseEntity.ok(new TokenResponse(newAccessToken, newRefreshToken));
    }

    @PostMapping("/logout")
    public ResponseEntity<Void> logout(@RequestBody RefreshRequest request) {
        String email = jwtProvider.extractEmail(request.refreshToken());
        refreshTokenService.delete(email);
        return ResponseEntity.noContent().build();
    }
}

RefreshTokenService

// src/main/java/com/example/api/auth/RefreshTokenService.java
package com.example.api.auth;

import com.example.domain.token.RefreshToken;
import com.example.domain.token.RefreshTokenRepository;
import org.springframework.security.core.AuthenticationException;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class RefreshTokenService {

    private final RefreshTokenRepository repository;

    public RefreshTokenService(RefreshTokenRepository repository) {
        this.repository = repository;
    }

    @Transactional
    public void save(String email, String token, String role) {
        repository.findById(email)
                .ifPresentOrElse(
                        rt -> rt.rotate(token),
                        () -> repository.save(new RefreshToken(email, token, role))
                );
    }

    public void validate(String email, String token) {
        RefreshToken stored = repository.findById(email)
                .orElseThrow(() -> new InvalidTokenException("Refresh token not found"));

        if (!stored.getToken().equals(token)) {
            // 토큰 불일치 — 탈취 가능성, 저장된 토큰 전체 폐기
            repository.deleteById(email);
            throw new InvalidTokenException("Refresh token mismatch. Possible token theft.");
        }
    }

    @Transactional
    public void rotate(String email, String newToken) {
        repository.findById(email).ifPresent(rt -> rt.rotate(newToken));
    }

    public String getRole(String email) {
        return repository.findById(email)
                .map(RefreshToken::getRole)
                .orElseThrow(() -> new InvalidTokenException("Refresh token not found"));
    }

    @Transactional
    public void delete(String email) {
        repository.deleteById(email);
    }
}

---

전체 인증 흐름

구현한 JWT 인증 흐름을 시퀀스로 정리하면 다음과 같다.

클라이언트                           서버
   │                                   │
   │── POST /api/auth/login ──────────>│
   │   { email, password }             │
   │                                   │── AuthenticationManager.authenticate()
   │                                   │── BCrypt 비밀번호 검증
   │                                   │── Access Token 생성 (1h)
   │                                   │── Refresh Token 생성 (7d) → DB 저장
   │<── { accessToken, refreshToken } ──│
   │                                   │
   │── GET /api/resource ─────────────>│
   │   Authorization: Bearer {AT}      │
   │                                   │── JwtAuthenticationFilter
   │                                   │── 서명 검증 + 만료 확인
   │                                   │── SecurityContextHolder 설정
   │<── 200 OK ─────────────────────── │
   │                                   │
   │  (Access Token 만료 후)            │
   │── POST /api/auth/refresh ─────────>│
   │   { refreshToken }                │
   │                                   │── DB 저장 토큰과 비교 검증
   │                                   │── 기존 RT 폐기 + 새 RT 발급 (Rotation)
   │                                   │── 새 Access Token 발급
   │<── { newAccessToken, newRefreshToken } │
   │                                   │
   │── POST /api/auth/logout ──────────>│
   │   { refreshToken }                │
   │                                   │── DB에서 RT 삭제
   │<── 204 No Content ─────────────── │

---

마치며

jjwt 0.12.x로 넘어오면서 API가 꽤 정리됐다.
구버전 예제 코드에서 자주 보이는 parseClaimsJws(), setSubject(), Keys.secretKeyFor(SignatureAlgorithm.HS256) 같은 메서드들이 deprecated되거나 제거됐으니, 예전 코드를 그대로 가져다 쓰면 컴파일 에러가 난다.

Refresh Token Rotation은 구현 비용 대비 보안 효과가 크다.
탈취된 토큰이 사용되는 순간 정상 사용자의 토큰도 무효화되기 때문에, 이상 징후를 빠르게 감지하고 대응할 수 있다.

---

참고 출처

Spring Boot 4.0 Release Notes — https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes
Spring Security 7.0 Migration Guide — https://docs.spring.io/spring-security/reference/migration/index.html
RFC 7519: JSON Web Token (JWT) — https://datatracker.ietf.org/doc/html/rfc7519
jjwt GitHub Repository — https://github.com/jwtk/jjwt