[ 트러블 슈팅 ] 403 Forbidden 에러와 SecurityContextHolder 문제 해결하기

Spring Security를 이용해서 권한별 URL 접근을 설정하던 중, 403 Forbidden 에러를 마주했다.

---

문제 상황

다음과 같이 /admin/** 와 /users/** 에 대한 권한을 설정한 상태에서 ADMIN 계정으로 접근할 때 403 Forbidden 에러가 발생했다.

.requestMatchers("/admin/**").hasRole("ADMIN")
.requestMatchers("/users/**").hasRole("USER")

---

문제 원인 분석

JwtFilter에서 인증(Authentication)과 인가(Authorization)를 처리하면서 발생했다.
Spring Security가 내부적으로 SecurityContextHolder를 이용해 인증 정보를 관리하는데, JwtFilter에서 SecurityContextHolder에 인증 정보를 저장하지 않아서 권한 처리가 제대로 이루어지지 않았다.
결과적으로 JwtFilter에서 인증을 진행했음에도 Spring Security에서 인증 정보를 찾지 못해 403 Forbidden 에러가 반환된 것이다.

---

해결 방법

SpringContextHolder에 인증 정보 저장하기

JwtFilter에서 JWT 토큰을 파싱하여 사용자 이메일과 권한 정보를 추출한 뒤, 이를 SecurityContextHolder에 저장하도록 수정했다.

String email = jwtUtil.extractEmail(jwt); // JWT에서 이메일 추출
String userRole = jwtUtil.extractRoles(jwt); // JWT에서 사용자 권한 추출
UserRole role = UserRole.of(userRole); // 권한 변환

// 권한 리스트 생성
List<SimpleGrantedAuthority> authorities = List.of(new SimpleGrantedAuthority(role.name()));

// SecurityContextHolder에 인증 정보 저장
SecurityContextHolder.getContext().setAuthentication(
    new UsernamePasswordAuthenticationToken(email, null, authorities)
);

JwtFilter에서 인가 로직 제거

Spring Security에서 권한(Authorization)을 관리하도록 설계했기 때문에 JwtFilter에서 인가를 처리하는 로직을 제거했다.
이를 통해 인증과 인가 로직이 서로 충돌하지 않도록 구조를 단순화했다.

hasRole 대신 hasAuthority 사용

Spring Security에서 권한을 확인할 때는 ROLE_ 접두사가 포함된 값을 이용한다. 예를 들어, "ADMIN" 역할을 확인하려면 "ROLE_ADMIN" 권한이 존재해야 한다.
따라서 hasRole("ADMIN") 대신 hasAuthority("ADMIN")을 사용해야 정상적으로 작동한다.

---

최종 코드

JwtFilter

@Slf4j
@RequiredArgsConstructor
@Component
public class JwtFilter implements Filter {

    private final JwtUtil jwtUtil;

    @Override
    public void init(FilterConfig filterConfig) throws ServletException {
        Filter.super.init(filterConfig);
    }

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        HttpServletResponse httpResponse = (HttpServletResponse) response;

        String url = httpRequest.getRequestURI();

        if (url.startsWith("/auth")) {
            chain.doFilter(request, response);
            return;
        }

        String bearerJwt = httpRequest.getHeader("Authorization");

        if (bearerJwt == null) {
            // 토큰이 없는 경우 400을 반환합니다.
            httpResponse.sendError(HttpServletResponse.SC_BAD_REQUEST, "JWT 토큰이 필요합니다.");
            return;
        }

        String jwt = jwtUtil.substringToken(bearerJwt);

        try {
            // JWT 유효성 검사와 claims 추출
            Claims claims = jwtUtil.extractClaims(jwt);
            if (claims == null) {
                httpResponse.sendError(HttpServletResponse.SC_BAD_REQUEST, "잘못된 JWT 토큰입니다.");
                return;
            }

            // 인가 -> 어떻게 할것인가..? 고민을 해보고
            String email = jwtUtil.extractEmail(jwt);
            String userRole = jwtUtil.extractRoles(jwt);
            UserRole role = UserRole.of(userRole);

            List<SimpleGrantedAuthority> authorities = List.of(new SimpleGrantedAuthority(role.name()));

            SecurityContextHolder.getContext().setAuthentication(new UsernamePasswordAuthenticationToken(email, null, authorities));

            chain.doFilter(request, response);
        } catch (SecurityException | MalformedJwtException e) {
            log.error("Invalid JWT signature, 유효하지 않는 JWT 서명 입니다.", e);
            httpResponse.sendError(HttpServletResponse.SC_UNAUTHORIZED, "유효하지 않는 JWT 서명입니다.");
        } catch (ExpiredJwtException e) {
            log.error("Expired JWT token, 만료된 JWT token 입니다.", e);
            httpResponse.sendError(HttpServletResponse.SC_UNAUTHORIZED, "만료된 JWT 토큰입니다.");
        } catch (UnsupportedJwtException e) {
            log.error("Unsupported JWT token, 지원되지 않는 JWT 토큰 입니다.", e);
            httpResponse.sendError(HttpServletResponse.SC_BAD_REQUEST, "지원되지 않는 JWT 토큰입니다.");
        } catch (Exception e) {
            log.error("Internal server error", e);
            httpResponse.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
        }
    }

    @Override
    public void destroy() {
        Filter.super.destroy();
    }
}

Spring Security

@Configuration
@EnableWebSecurity
@EnableMethodSecurity(securedEnabled = true)
@RequiredArgsConstructor
public class SecurityConfig {

    private final JwtFilter jwtFilter;

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
            .csrf(AbstractHttpConfigurer::disable)
            .httpBasic(AbstractHttpConfigurer::disable)
            .formLogin(AbstractHttpConfigurer::disable)
            .addFilterBefore(jwtFilter, SecurityContextHolderAwareRequestFilter.class)
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/auth/**").permitAll()
                .requestMatchers("/todos/**").permitAll()
                .requestMatchers("/admin/**").hasAuthority("ADMIN")
                .requestMatchers("/users/**").hasAuthority("USER")
                .anyRequest().authenticated()
            )
            .build();
    }
}

---

결론

SecurityContextHolder를 활용하여 Spring Security에 인증 정보를 명시적으로 전달해야 한다.
인증(Authentication)과 인가(Authorization) 역할을 명확히 분리하여 관리한다.

• JwtFilter: 인증 정보 추출 및 저장
• Spring Security: 권한 관리 및 접근 제어

권한 검사 시 hasRole 대신 hasAuthority를 사용하여 해결한다.