🔑 Spring Security - JWT 인증 필터 구현하기

📌 JWT 인증 과정 개요

Spring Security에서 JWT(JSON Web Token) 인증은 일반적으로 다음 단계를 거칩니다.

1. 클라이언트 로그인 요청 → 서버에서 JWT 발급.
2. 클라이언트 요청 시 헤더에 JWT 포함 (Authorization: Bearer <토큰>).
3. 서버의 필터(JwtAuthenticationFilter)가 요청을 가로채서:
   • 헤더에서 토큰 추출
   • 유효성 검증
   • 사용자 정보 로드
   • SecurityContext에 인증 객체 저장
4. 이후 컨트롤러에서 @AuthenticationPrincipal 등을 통해 인증된 사용자 정보를 활용.

이 필터는 모든 HTTP 요청을 가로채 JWT를 검증하고 인증 여부를 확인하는 핵심적인 역할을 합니다.

---

📝 코드 전체

package com.example.demo.security;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.*;
import lombok.RequiredArgsConstructor;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.userdetails.*;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;

@Component
@RequiredArgsConstructor
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final JwtTokenProvider jwt;
    private final UserDetailsService userDetailsService;

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

        // 1. 요청 헤더에서 Authorization 값 가져오기
        String header = req.getHeader("Authorization");

        // 2. "Bearer "로 시작하는지 확인
        if (header != null && header.startsWith("Bearer ")) {
            String token = header.substring(7);

            // 3. 토큰 유효성 검증
            if (jwt.validate(token)) {
                // 4. 토큰에서 사용자 이름(username) 추출
                String username = jwt.getUsername(token);

                // 5. DB에서 사용자 정보 로드
                UserDetails userDetails = userDetailsService.loadUserByUsername(username);

                // 6. 사용자 정보 기반 인증 객체 생성
                UsernamePasswordAuthenticationToken auth =
                        new UsernamePasswordAuthenticationToken(
                                userDetails, null, userDetails.getAuthorities());

                // 7. SecurityContext에 인증 객체 저장
                SecurityContextHolder.getContext().setAuthentication(auth);
            }
        }

        // 8. 다음 필터/컨트롤러로 요청 전달
        chain.doFilter(req, res);
    }
}

---

🔍 세부 설명

1. 클래스 선언부

@Component
@RequiredArgsConstructor
public class JwtAuthenticationFilter extends OncePerRequestFilter

• @Component: 이 클래스를 Spring Bean으로 등록하여 Spring IoC 컨테이너가 관리하게 합니다.
• OncePerRequestFilter: 한 번의 요청(request)에 대해 단 한 번만 실행되는 필터를 보장합니다.
• @RequiredArgsConstructor: final 필드(jwt, userDetailsService)를 인자로 받는 생성자를 자동으로 생성하여 **의존성 주입(DI)**을 처리합니다.

2. Authorization 헤더 처리

String header = req.getHeader("Authorization");
if (header != null && header.startsWith("Bearer ")) {
    String token = header.substring(7);
}

클라이언트가 전송한 HTTP 요청의 Authorization 헤더에서 JWT를 추출합니다. 일반적으로 JWT는 "Bearer <토큰값>" 형식으로 전달되므로, "Bearer " 접두어를 제거하고 순수 토큰 값만 얻습니다.

3. JWT 검증 및 사용자 이름 추출

if (jwt.validate(token)) {
    String username = jwt.getUsername(token);
}

**JwtTokenProvider**를 사용하여 토큰의 유효성을 검사합니다. 토큰이 유효하다면, 토큰 내에 저장된 **사용자 이름(Subject)**을 추출합니다.

4. 사용자 정보 로드

UserDetails userDetails = userDetailsService.loadUserByUsername(username);

**UserDetailsService**는 Spring Security에서 사용자 정보를 제공하는 핵심 인터페이스입니다. 이를 통해 추출한 사용자 이름으로 데이터베이스나 다른 저장소에서 사용자 계정 정보를 UserDetails 객체로 가져옵니다.

5. 인증 객체 생성 및 SecurityContext 저장

UsernamePasswordAuthenticationToken auth =
        new UsernamePasswordAuthenticationToken(
                userDetails, null, userDetails.getAuthorities());

SecurityContextHolder.getContext().setAuthentication(auth);

**인증 객체(Authentication)**를 생성하고 SecurityContextHolder에 저장합니다.

• 첫 번째 인자: Principal (사용자 정보)
• 두 번째 인자: Credentials (비밀번호) - 토큰 기반 인증이므로 null로 설정 가능.
• 세 번째 인자: Authorities (권한 목록)

이렇게 SecurityContextHolder에 저장된 인증 정보는 이후 컨트롤러나 서비스 계층에서 전역적으로 접근할 수 있습니다.

---

✅ 정리 / 배운 점

• JwtAuthenticationFilter는 모든 요청을 가로채 JWT를 검증하는 핵심 필터입니다.
• 인증에 성공하면 SecurityContext에 인증 객체를 저장하여 Spring Security 전역에서 인증 상태를 유지합니다.
• 이 덕분에 컨트롤러 단에서는 별도의 인증 로직 없이 @AuthenticationPrincipal 등을 활용하여 인증된 사용자 정보에 손쉽게 접근할 수 있습니다.

---

🚀 확장

• 토큰이 유효하지 않을 때 401 Unauthorized 응답을 반환하도록 예외 처리를 추가하여 필터를 개선할 수 있습니다.
• Refresh Token과 Access Token을 함께 사용하는 방식으로 더 안전한 인증 구조를 설계할 수 있습니다.
• 로그아웃 시 토큰을 무효화하는 JWT 블랙리스트 기능을 추가하여 보안을 강화할 수 있습니다.