스프링 보안의 꽃인 스프링 시큐리티를 구현해보자!

---

✅ 인증 흐름 큰그림으로 톺아보기!

1. 사용자가 로그인
2. JWT를 발급해준다
3. 클라이언트가 JWT를 Authorization 헤더에 포함시켜서 나 접근해도 되니? 라고 요청을 보낸다
4. JWT필터가 요청을 가로채서 토큰이 유효한지 검증한다
5. 유효하면? Authorization 객체를 만들어서 SecurityContextHolder에 저장한다
6. filterChain을 통해 다음 필터로 넘어가서 컨트롤러에서 인증된 사용자 정보를 활용할 수 있도록 한다.

👀 왜 그냥 Filter말고 SpringSecurity를 사용하는걸까?

항목	일반 서블릿 필터	Spring Security
인증/인가 분리	직접 구현해야 함	구조화되어 있음 (Filter, Provider, Context 등)
재사용성/유지보수	로직 중복 많음	각 로직이 모듈화되어 재사용 쉬움
예외 처리	try-catch 직접 처리	ExceptionTranslationFilter가 처리
ThreadLocal 인증 정보 저장	직접 구현해야 함	SecurityContextHolder 제공
설정/확장성	하드코딩/복잡함	DSL 방식 (SecurityFilterChain)으로 직관적

즉, 스프링 시큐리티는 보안에 필요한 공통 구조를 잘 분리하고 확장하기 쉽게 만들어준다!!

🚓 스프링 시큐리티 구조

스프링 시큐리티는 Filter 기반 보안 프레임워크!
구조는 아래처럼 계층적으로 구성되어 있다

주요 기능

1. SecurityFilterChain
   HTTP 요청마다 작동하는 보안 필터 체인
   우리가 httpSecurity를 통해 설정하는 곳이 여깁니다.

2. Filter 계층
   시큐리티는 여러 개의 Filter를 체인으로 두고 있으며, 요청이 오면 이 필터들을 통과하면서 인증/인가 등을 처리합니다. 주요 필터는 아래와 같습니다:

3. UsernamePasswordAuthenticationFilter
   유저의 로그인 처리

4. ExceptionTranslationFilter
   예외 처리

5. FilterSecurityInterceptor
   인가(접근 권한) 처리

6. AuthenticationManager
   인증 로직을 처리하는 핵심 객체입니다. 인증 요청을 받아서 실제 인증을 수행합니다.

7. AuthenticationProvider
   특정 방식의 인증을 처리하는 컴포넌트
   (ex. 사용자명/비밀번호, JWT 등)

8. SecurityContext + SecurityContextHolder
   : 인증된 사용자 정보를 저장!

☑️ 기능별 역할 정리

컴포넌트	역할
JwtFilter (JwtAuthenticationFilter)	요청에서 JWT 토큰을 추출하고, 유효성 검증 후 Authentication 객체 생성 및 SecurityContext에 저장
JwtUtil (JwtProvider)	JWT 생성, 파싱, 만료 여부, 시그니처 검증 등 JWT 관련 기능 전담
SecurityFilterChain	어떤 요청에 인증이 필요한지, 어떤 필터를 먼저 실행할지, 어떤 방식으로 로그인/인가를 처리할지 설정

🚦 상황별 흐름 정리

1. 로그인할 때 (Jwt 토큰 필요하지 않음)
→ filter와 security를 거치지 않고, 바로 jwtUtil에서 토큰을 생성해서 발급해준다

[Client] → POST /login {username, password}
            → [AuthController]
              → AuthenticationManager.authenticate()
              → JWT 생성 → Response

2. Jwt토큰(인증/인가)가 필요한 요청일 때
→ jwtFilter가 요청을 가로채서 토큰이 유효한지 검증
→ 유효하다면 securityContext에 저장
→ 요청한 controller의 기능으로 전달 (AuthUser등의 정보)

[Client] → GET /protected-resource
  Authorization: Bearer <JWT>

  → [JwtAuthenticationFilter]
     → 토큰 유효성 검증
     → 사용자 정보 로딩 → Authentication 생성
     → SecurityContext에 저장
     → 다음 필터 또는 컨트롤러로 전달

→ [Controller] 인증된 사용자 정보 사용 가능

---

🎁 JwtUtil 구현하기

JwtUtil은 토큰을 생성, 파싱, 만료 등을 담당한다

🔎 역할

• 만료 시간 설정
• 토큰 발급 (토큰에 담길 정보 설정)
• 토큰 꺼내오기
• 암호화된 토큰의 정보를 꺼내서 유효한지 검증하고 전달해주기(파싱)

전체 코드

@Component
public class JwtUtil {

    private static final String BEARER_PREFIX = "Bearer ";
    private static final long TOKEN_TIME = 60 * 60 * 1000L; // 60분

    @Value("${jwt.secret.key}")
    private String secretKey;
    private Key key;
    private final SignatureAlgorithm signatureAlgorithm = SignatureAlgorithm.HS256;

    @PostConstruct
    public void init() {
        byte[] bytes = Base64.getDecoder().decode(secretKey);
        key = Keys.hmacShaKeyFor(bytes);
    }

    public String createToken(Long userId, String email, UserRole userRole, String nickName) {
        Date date = new Date();

        return BEARER_PREFIX +
                Jwts.builder()
                        .setSubject(String.valueOf(userId))
                        .claim("email", email)
                        .claim("userRole", userRole)
                        .claim("nickName", nickName) //프론트에서 꺼내 쓸 수 있도록 nickName 추가
                        .setExpiration(new Date(date.getTime() + TOKEN_TIME))
                        .setIssuedAt(date) // 발급일
                        .signWith(key, signatureAlgorithm) // 암호화 알고리즘
                        .compact();
    }

    public String substringToken(String tokenValue) {
        if (StringUtils.hasText(tokenValue) && tokenValue.startsWith(BEARER_PREFIX)) {
            return tokenValue.substring(7);
        }
        throw new ServerException("Not Found Token");
    }

    public Claims extractClaims(String token) {
        return Jwts.parserBuilder()
                .setSigningKey(key)
                .build()
                .parseClaimsJws(token)
                .getBody();
    }
}

🔎 하나씩 뜯어보기

1. 만료 시간, 암호화할 jwt secretkey 설정하기

@Component
public class JwtUtil {

    private static final String BEARER_PREFIX = "Bearer ";
    private static final long TOKEN_TIME = 60 * 60 * 1000L; // 60분

    @Value("${jwt.secret.key}")
    private String secretKey;
    private Key key;
    private final SignatureAlgorithm signatureAlgorithm = SignatureAlgorithm.HS256;

• 토큰 발급할 때, 앞에 "Bearer "라고 prefix라고 달아주기
• 만료시간은 60분으로 설정
• 기존에 properties에 등록해둔 jwt secretkey를 사용
  (Base64 인코딩된 문자열)

2. 서명을 위한 key 객체 만들기

@PostConstruct
    public void init() {
        byte[] bytes = Base64.getDecoder().decode(secretKey);
        key = Keys.hmacShaKeyFor(bytes);
    }

우리가 가져온 secretKey는 텍스트이기 때문에, 이걸 바이트 배열로 변환해야 실제 HMAC 키로 쓸 수 있다.
→ Base64 디코딩을 통해 그 바이트 배열을 복원

Keys.hmacShaKeyFor(bytes)
: 디코딩된 바이트 배열을 javax.crypto.SecretKey로 변환
(JWT를 생성할 때 사용될 서명용 Key 객체)

➡️ 이 키는 HS256 같은 대칭 서명 알고리즘(HMAC)에 사용돤다

3. 토큰 발급 메서드

public String createToken(Long userId, String email, UserRole userRole, String nickName) {
    Date date = new Date();

    return BEARER_PREFIX +
            Jwts.builder()
                .setSubject(String.valueOf(userId))
                .claim("email", email)
                .claim("userRole", userRole)
                .claim("nickName", nickName) //프론트에서 꺼내 쓸 수 있도록 nickName 추가
                .setExpiration(new Date(date.getTime() + TOKEN_TIME))
                .setIssuedAt(date) // 발급일
                .signWith(key, signatureAlgorithm) // 암호화 알고리즘
                .compact();
    }

---

🫧 JwtFilter 구현하기

이제 클라이언트가 요청을 보낼 때, 로그인 시 발급받은 토큰을 함께 보낼 것 이다!
이 토큰 값을 검증하고, 인가할 수 있는 JwtFilter를 구현해보자

먼저 Spring Security를 구현할 때는 그냥 Filter를 상속하는게 아니라,OncePerRequestFilter를 상속한다

➡️ 단 한 번만 검증이 이루어지면 되므로, OncePerRequestFilter를 사용하는 것!
(요청당 한 번만 실행되는 JWT 필터)

이 필터는 우리가 요청할 때 헤더에 담긴 "비밀번호 같은 토큰(JWT)"을 검사해서,
“이 사람이 진짜 로그인한 사람인가?” 를 확인해주는 경비원 같은 역할

전체 코드

뜯어보기

🔍 1. 클래스 구성 먼저 보기

@AllArgsConstructor
@Component
@Slf4j
public class JwtAuthFilter extends OncePerRequestFilter {

@Component: 이걸 스프링이 자동으로 만들어서 사용할 수 있게
@AllArgsConstructor: JwtUtil을 생성자에 자동으로 삽입

@Slf4j: 로그를 남기기 (예: 에러 메시지 기록)

🔍 2. 핵심 메서드: doFilterInternal

“요청이 들어오면 토큰이 있는지 확인하고, 있으면 검사해서, 진짜 사용자라면 인증 처리해주고, 아니면 거절해!”

✅ Step 1. Authorization 헤더에서 토큰 꺼내기

String bearerToken = request.getHeader("Authorization");
String url = request.getRequestURI();

누군가 웹 요청을 하면, 그 요청 헤더에 담긴 토큰("Authorization"이라는 이름)을 꺼내기

✅ Step 2. 토큰이 없거나 형식이 이상하면 그냥 통과

if (bearerToken == null || !bearerToken.startsWith("Bearer ")) {
    chain.doFilter(request, response);
    return;
}

토큰이 아예 없거나 "Bearer "로 시작하지 않으면,인증을 받지 않은 것.
👉 그냥 다음 필터로 넘기자
(비회원 페이지 같은 곳은 접근할 수 있게 하기 위함)

✅ Step 3. 토큰에서 실제 내용만 뽑기

String jwt = jwtUtil.substringToken(bearerToken);

"Bearer abc.def.ghi"처럼 되어 있는 토큰에서 "abc.def.ghi"만 잘라내기

✅ Step 4. 토큰에서 정보 뽑아오기

claims = 토큰 안의 정보

Claims claims = jwtUtil.extractClaims(jwt);

토큰을 해석해서 그 안에 들어 있는 사용자 정보(email, userRole 등)를 꺼내기

🚫 Step 5. 잘못된 토큰이면 거절

if (claims == null) {
    response.sendError(HttpServletResponse.SC_BAD_REQUEST, "Invalid JWT");
    return;
}

정보를 claims로 꺼냈을때 아무것도 없으면? 잘못된 토큰이겠져
👉 "이거 잘못된 토큰이야!" 하고 요청을 끊는다

👮‍♂️ Step 6. 관리자 페이지라면 관리자인지 확인!

if (url.startsWith("/admin")) {
    if (!UserRole.ADMIN.equals(userRole)) {
        response.sendError(HttpServletResponse.SC_FORBIDDEN, "관리자 권한이 없습니다.");
        return;
    }
    chain.doFilter(request, response);
    return;
}

요청한 주소가 /admin으로 시작하면 👉 “관리자만 들어올 수 있는 곳!”

그런데 일반 유저가 접근하면 👉 403 Forbidden 오류로 차단

✅ Step 7. 사용자 정보를 꺼내서 담아두기

AuthUser authUser = new AuthUser(
        Long.parseLong(claims.getSubject()),
        (String) claims.get("email"),
        userRole
);

토큰에 담긴 내용으로 AuthUser 객체를 만들어서,
"이 사람은 누구인지" 정보를 갖고 있게!

🛠 Step 8. 사용자 정보 request에 저장

request.setAttribute("userId", ...);

컨트롤러에서 request.getAttribute("userId") 하면
👉 토큰에서 꺼낸 사용자 id, email, role을 다시 꺼낼 수 있게 해줌

🔐 Step 9. 스프링 시큐리티에 등록

Collection<? extends GrantedAuthority> authorities =
    List.of(new SimpleGrantedAuthority(authUser.getUserRole().toString()));

Authentication authToken = new UsernamePasswordAuthenticationToken(authUser,
        null, authorities);

SecurityContextHolder.getContext().setAuthentication(authToken);

스프링 시큐리티에서는 Authentication 객체를 만들어서
👉 "이 사람은 로그인한 사람이고, 권한은 이런 걸 가졌어"라고 알려줘야함

마지막 줄은 시큐리티 세션에 인증 정보 저장하는 부분

✅ Step 10. 통과시키기

chain.doFilter(request, response);

여기까지 성공했다면 드디어 인증된 사용자로서 다음 필터나 컨트롤러로 넘어간다

❗️Step 11. 예외 처리

} catch (ExpiredJwtException e) { ... }

토큰이 만료되었거나, 서명이 이상하거나, 포맷이 틀렸으면
각각의 상황에 맞게 로그 기록 + 에러 코드를 반환

흐름 보기

사용자
 |
 | HTTP 요청 (Authorization: Bearer {JWT})
 v
JwtAuthFilter (OncePerRequestFilter)
 |
 |---> JWT 토큰 추출 및 검증
 |       |
 |       |---> JwtUtil.extractClaims(token)
 |               |
 |               |---> 서명 검증 및 Claims 추출
 |               |
 |               |<--- Claims 반환
 |       |
 |       |---> 사용자 정보 및 권한 확인
 |       |---> Authentication 객체 생성
 |       |---> SecurityContextHolder에 인증 정보 저장
 |
 | HTTP 요청 전달
 v
다음 필터 또는 컨트롤러

Spring Security

@Configuration
@EnableWebSecurity
@AllArgsConstructor
public class SecurityConfig {

    private final JwtAuthFilter jwtAuthFilter;

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
                // CSRF, Form 로그인, HTTP Basic 인증 비활성화
                .csrf(AbstractHttpConfigurer::disable)
                .formLogin(AbstractHttpConfigurer::disable)
                .httpBasic(AbstractHttpConfigurer::disable)
                // JWT 사용을 위해 세션을 STATELESS로 설정 (세션 정보 저장 x)
                .sessionManagement(session -> session
                        .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
                )

                //인증 인가 URL 설정
                .authorizeHttpRequests((auth)-> auth
                .requestMatchers("/", "/auth/signup", "/auth/signin").permitAll() //인증 없이 사용 가능
                .requestMatchers("/admin/**").hasRole("ADMIN") //ADMIN 권한이 있어야만 사용 가능
                .anyRequest().authenticated()) //나머지는 인증만 필요

        .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class);
        return http.build();
    }
}

마지막의

.addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class);

이 부분 덕분에, Spring Security의
UsernamePasswordAuthenticationFilter.class 이부분이 실행되기 전에
아까 설정한 jwtAuthFilter가 실행되면서 필터 체인이 돌아갈 수 있게 되는것!

---

FilterConfig

잊지말고, filterConfig에서도 아까만든 필터 등록하기

@Configuration
@RequiredArgsConstructor
public class FilterConfig {

    private final JwtUtil jwtUtil;

    @Bean
    public FilterRegistrationBean<JwtAuthFilter> jwtFilter() {
        FilterRegistrationBean<JwtAuthFilter> registrationBean = new FilterRegistrationBean<>();
        registrationBean.setFilter(new JwtAuthFilter(jwtUtil));
        registrationBean.addUrlPatterns("/*"); // 필터를 적용할 URL 패턴을 지정합니다.

        return registrationBean;
    }
}