spring-security-5-jwt-jjwt10

name	spring-security-5-jwt-jjwt10
description	Spring Security 5.5.x + jjwt 0.10.7 레거시 JWT 인증 - WebSecurityConfigurerAdapter, OncePerRequestFilter, javax.servlet 환경

Spring Security 5 + jjwt 0.10.x 레거시 JWT 인증

소스: https://docs.spring.io/spring-security/site/docs/5.5.x-SNAPSHOT/reference/html5/ | https://github.com/jwtk/jjwt/tree/0.10.7 | https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-2.5-Release-Notes 검증일: 2026-07-04

주의: 이 스킬은 Spring Boot 2.5.x + Spring Security 5.5.x + jjwt 0.10.7 + Java 11 + javax.* 레거시 환경 전용입니다. 신규 프로젝트는 Spring Security 6 + jjwt 0.12.x (parserBuilder, jakarta.*) 기반 모던 스킬을 사용하세요. WebSecurityConfigurerAdapter는 Spring Security 5.7부터 deprecated되었으며, 5.5.x에서는 아직 표준 패턴입니다.

---

환경 전제

항목	버전
Java	11
Spring Boot	2.5.x (번들 Spring Security 5.5.x)
Spring Security	5.5.x
jjwt	0.10.7
Servlet API	javax.servlet.* (jakarta 아님)

주의: Spring Boot 2.5는 출시 시점 Spring Security 5.5.0-M2 이상을 번들합니다. 2.5.15 기준으로도 5.5.x 라인을 유지합니다. 2.6은 5.6, 2.7은 5.7로 올라갑니다.

---

의존성 설정

Maven

<!-- Spring Security (Spring Boot BOM이 5.5.x 버전 관리) -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

<!-- jjwt 0.10.7: api는 compile, impl/jackson은 runtime -->
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-api</artifactId>
    <version>0.10.7</version>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-impl</artifactId>
    <version>0.10.7</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-jackson</artifactId>
    <version>0.10.7</version>
    <scope>runtime</scope>
</dependency>

Gradle

implementation 'org.springframework.boot:spring-boot-starter-security'

implementation 'io.jsonwebtoken:jjwt-api:0.10.7'
runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.10.7'
runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.10.7'

주의: jjwt-impl과 jjwt-jackson은 반드시 runtime 스코프로 선언합니다. jjwt-api 외부 API의 하위 호환성 보증을 위해 impl 패키지는 런타임에만 노출됩니다.

---

WebSecurityConfigurerAdapter 설정 클래스

레거시 Security 5.5.x의 핵심 패턴은 WebSecurityConfigurerAdapter를 상속하고 세 개의 configure(...) 메서드를 오버라이드하는 것입니다.

package com.example.security.config;

import javax.servlet.http.HttpServletResponse; // javax 네임스페이스

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.builders.WebSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
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.AuthenticationEntryPoint;
import org.springframework.security.web.access.AccessDeniedHandler;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;

import lombok.RequiredArgsConstructor;

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    private final UserDetailsService userDetailsService;
    private final JwtProvider jwtProvider;
    private  AuthenticationEntryPoint jwtAuthenticationEntryPoint;
      AccessDeniedHandler jwtAccessDeniedHandler;

    
    
        Exception {
        auth.userDetailsService(userDetailsService)
            .passwordEncoder(passwordEncoder());
    }

    
    
    
     AuthenticationManager   Exception {
         .authenticationManagerBean();
    }

    
    
       {
        web.ignoring()
           .antMatchers(, ,
                        , );
    }

    
    
        Exception {
        http
            .csrf().disable()                                       
            .httpBasic().disable()
            .formLogin().disable()
            .sessionManagement()
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS) 
            .and()
            .exceptionHandling()
                .authenticationEntryPoint(jwtAuthenticationEntryPoint)  
                .accessDeniedHandler(jwtAccessDeniedHandler)            
            .and()
            .authorizeRequests()
                .antMatchers(, ).permitAll()
                .antMatchers(HttpMethod.GET, ).permitAll()
                .antMatchers().hasRole()
                .anyRequest().hasRole()
            .and()
            
            .addFilterBefore( (jwtProvider),
                             UsernamePasswordAuthenticationFilter.class);
    }

    
     PasswordEncoder  {
          ();
    }
}

핵심 포인트:

• @EnableWebSecurity는 WebSecurityConfigurerAdapter와 함께 있을 때 필수
• authenticationManagerBean()을 @Bean으로 노출해야 다른 컴포넌트에서 AuthenticationManager를 주입받을 수 있음 (예: 로그인 컨트롤러)
• sessionCreationPolicy(STATELESS)로 HTTP 세션을 끄면 SecurityContext가 요청 간 유지되지 않음 → JWT로 매 요청 인증
• hasRole("USER")는 내부적으로 ROLE_USER 권한으로 확장됨. GrantedAuthority 값을 저장할 때 ROLE_ 접두사 포함 여부에 주의

---

JwtAuthenticationFilter (OncePerRequestFilter)

package com.example.security.filter;

import java.io.IOException;

import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.springframework.http.HttpHeaders;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.util.StringUtils;
import org.springframework.web.filter.OncePerRequestFilter;

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;

@Slf4j
@RequiredArgsConstructor
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    public static final String BEARER_PREFIX = "Bearer ";

    private final JwtProvider jwtProvider;

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

        String token = resolveToken(request);

        if (StringUtils.hasText(token) && jwtProvider.validateToken(token)) {
            Authentication authentication  jwtProvider.getAuthentication(token);
            
            SecurityContextHolder.getContext().setAuthentication(authentication);
            log.debug(, authentication.getName(), request.getRequestURI());
        }

        chain.doFilter(request, response);
    }

     String  {
           request.getHeader(HttpHeaders.AUTHORIZATION);
         (StringUtils.hasText(bearerToken) && bearerToken.startsWith(BEARER_PREFIX)) {
             bearerToken.substring(BEARER_PREFIX.length());
        }
         ;
    }
}

핵심 포인트:

• OncePerRequestFilter는 Spring이 요청당 정확히 한 번 실행을 보장. forward/include 시 중복 실행 방지
• 검증 실패 시 예외를 던지지 말고 조용히 체인을 이어간다 → SecurityContextHolder가 비어있으면 이후 인가 단계에서 AuthenticationEntryPoint가 401을 반환
• SecurityContextHolder에 주입하는 Authentication은 UsernamePasswordAuthenticationToken 또는 커스텀 토큰. 반드시 setAuthenticated(true) 또는 권한 인자 생성자 사용

---

JwtProvider 유틸 클래스 (jjwt 0.10.7 API)

package com.example.security.jwt;

import java.security.Key;
import java.util.Arrays;
import java.util.Collection;
import java.util.Date;
import java.util.stream.Collectors;

import javax.annotation.PostConstruct;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.User;
import org.springframework.stereotype.Component;

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.ExpiredJwtException;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.MalformedJwtException;
import io.jsonwebtoken.SignatureAlgorithm;
import io.jsonwebtoken.UnsupportedJwtException;
import io.jsonwebtoken.io.Decoders;
import io.jsonwebtoken.security.Keys;

import lombok.extern.slf4j.Slf4j;

@Slf4j
@Component
public class JwtProvider {

    private static final String AUTHORITIES_KEY = "auth";
    private static final long ACCESS_TOKEN_VALIDITY_MS = 30 *  * ; 

     
     String secretBase64;

     Key key;

    
       {
        [] keyBytes = Decoders.BASE64.decode(secretBase64);
        .key = Keys.hmacShaKeyFor(keyBytes);
        
    }

    
     String  {
           authentication.getAuthorities().stream()
            .map(GrantedAuthority::getAuthority)
            .collect(Collectors.joining());

           System.currentTimeMillis();
            (now + ACCESS_TOKEN_VALIDITY_MS);

         Jwts.builder()
            .setSubject(authentication.getName())
            .claim(AUTHORITIES_KEY, authorities)
            .setIssuedAt( (now))
            .setExpiration(expiry)
            .signWith(key, SignatureAlgorithm.HS256)
            .compact();
    }

    
       {
         {
            
            
            Jwts.parser().setSigningKey(key).parseClaimsJws(token);
             ;
        }  (ExpiredJwtException e) {
            log.debug();
        }  (MalformedJwtException | SecurityException e) {
            log.debug();
        }  (UnsupportedJwtException e) {
            log.debug();
        }  (IllegalArgumentException e) {
            log.debug();
        }
         ;
    }

    
     Authentication  {
           Jwts.parser()
            .setSigningKey(key)
            .parseClaimsJws(token)
            .getBody();

           claims.get(AUTHORITIES_KEY, String.class);
        Collection<?  > authorities = (authoritiesStr ==  || authoritiesStr.isEmpty())
            ? java.util.Collections.emptyList()
            : Arrays.stream(authoritiesStr.split())
                    .map(SimpleGrantedAuthority::)
                    .collect(Collectors.toList());

            (claims.getSubject(), , authorities);
          (principal, token, authorities);
    }

     String  {
         Jwts.parser()
            .setSigningKey(key)
            .parseClaimsJws(token)
            .getBody()
            .getSubject();
    }
}

jjwt 0.10.7 API 요약:

작업	API
빌더 시작	Jwts.builder()
키 생성	Keys.hmacShaKeyFor(byte[]) (최소 256-bit)
알고리즘 지정	signWith(key, SignatureAlgorithm.HS256)
파서 (0.10.x)	Jwts.parser().setSigningKey(key).parseClaimsJws(token)
파서 (0.11+)	Jwts.parserBuilder().setSigningKey(key).build().parseClaimsJws(token) ← 0.10.7은 사용 불가

주의: 0.10.x의 Jwts.parser()는 thread-safe가 보장되지 않습니다. 0.11부터 parserBuilder()로 immutable 파서가 도입되었으며, 가능하면 요청마다 파싱 인스턴스를 지역 변수로 사용하세요.

주의: 시크릿 키는 환경변수·Vault에서 주입하고 프로퍼티 파일에 평문으로 두지 마세요. Base64 디코딩 전 길이가 HS256 기준 256-bit 이상인지 확인합니다.

---

---

상세 레퍼런스 (예제·고급 패턴·흔한 실수) → references/REFERENCE.md