[Spring Boot 3.x] WebSecurityConfigurerAdapter 제거 오류 해결! (SecurityFilterChain 최신 설정)

AI 생성 이미지: [Spring Boot 3.x] WebSecurityConfigurerAdapter 제거 오류 해결! (SecurityFilterChain 최신 설정)

안녕하세요, 개발자 페럿입니다.

프로젝트를 Spring Boot 2.x에서 3.x로 올리다가 마주친 대표적인 문제를 정리합니다. 제목에서 알 수 있듯이, [Spring Boot 3.x] WebSecurityConfigurerAdapter 제거 오류 해결! (SecurityFilterChain 최신 설정) 방법을 중심으로 실제 사례와 권장 패턴을 함께 설명하겠습니다.

요약하자면, 기존에 익숙하게 사용하던 WebSecurityConfigurerAdapter가 더 이상 존재하지 않아 빌드 또는 컴파일 오류가 발생하고, 이를 SecurityFilterChain 기반의 Bean 설정으로 바꿔야 합니다. 아래 내용은 그 이유와 단계별 해결법을 담고 있습니다.

1. 🤯 초보 개발자의 첫 번째 실수와 오류

익숙하게 클래스를 상속해서 보안 설정을 작성했더니 컴파일 단계에서 빨간줄이 나타났습니다. 문제는 단순합니다: 프로젝트가 Spring Security 6(= Spring Boot 3.x)를 타깃으로 하면서 WebSecurityConfigurerAdapter가 제거되었기 때문입니다.

1-1. 옛날 스타일 (Spring Boot 2.x 이하) - 이 코드는 이제 안 돼요!

// ❌ 2.x에서는 됐는데, 3.x에서는 컴파일 오류!
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter { // <--- 여기가 오류!

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        // ... (보안 설정)
    }
}

오류 메시지는 대개 “‘WebSecurityConfigurerAdapter’ 클래스를 찾을 수 없습니다” 또는 Deprecated 후 제거되었다는 형태로 나타납니다. 원인은 Spring Security의 설계 변경입니다.

1-2. WebSecurityConfigurerAdapter가 사라진 이유? (핵심 원인)

Spring Security 팀은 상속 기반 설정이 복잡해질수록 설정의 가독성과 제어가 어려워진다고 판단했습니다. 한 클래스에 기능이 과도하게 모이면서 확장성과 테스트 편의성이 떨어진다는 이유로, 5.7에서 Deprecated 처리 후 6.x에서 완전히 제거했습니다.

• 문제점: 상속으로 얽힌 설정은 어떤 설정이 적용되는지 파악하기 어렵습니다.
• 대안: 설정을 Bean으로 노출해 함수형(람다) 스타일로 구성하도록 변경했습니다.

결과적으로 설정을 분리하고 명시적으로 주입하는 방식으로 전환하여 유지보수성과 조합성을 개선했습니다.

2. ✨ Spring Boot 3.x의 최신 Security 설정 패턴 (Solution)

Spring Boot 3.x에서는 더 이상 WebSecurityConfigurerAdapter를 상속하지 않습니다. 대신 SecurityFilterChain 타입의 Bean을 등록해 HttpSecurity를 구성하는 방식이 권장됩니다. 이 접근이 현재의 표준입니다.

2-1. 최신 스타일: `SecurityFilterChain` Bean 등록 (코드 예시)

// ✅ Spring Boot 3.x (Spring Security 6) 권장 패턴
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    // 1. HttpSecurity 객체를 인자로 받아 설정을 처리합니다.
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        
        http
            // 💡 변경점 1: csrf, cors 설정 등을 람다식으로 처리합니다.
            .csrf(csrf -> csrf.disable()) 
            
            // 💡 변경점 2: 권한 설정은 authorizeHttpRequests()를 사용합니다.
            .authorizeHttpRequests(authorize -> authorize
                .requestMatchers("/", "/public/**").permitAll() // 모두 허용
                .anyRequest().authenticated()                    // 나머지는 인증 필요
            )
            
            // 💡 폼 로그인 설정 (람다식)
            .formLogin(form -> form
                .permitAll()
            );

        // 3. 설정이 완료된 SecurityFilterChain 객체를 반환합니다.
        return http.build();
    }
    
    // 💡 PasswordEncoder는 반드시 Bean으로 등록해야 합니다.
    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

2-2. 주요 변경점 요약 (2.x vs 3.x)

설정 항목	**Spring Boot 2.x (Old)**	**Spring Boot 3.x (New)**
기본 클래스	`WebSecurityConfigurerAdapter` **상속**	**`@Bean SecurityFilterChain`** 등록
인가 설정 메소드	`http.authorizeRequests()`	`http.authorizeHttpRequests()`
메소드 체이닝	`http.csrf().disable()`	`http.csrf(csrf -> csrf.disable())` **(람다식 권장)**

❗ 초보 개발자에게 주는 팁

이제 `http.`로 시작하는 대부분의 설정 메소드는 람다를 인자로 받습니다. 람다식은 더 명확한 컨텍스트와 안전한 구성 방법을 제공합니다. 새로운 프로젝트에서는 [Spring Boot 3.x] WebSecurityConfigurerAdapter 제거 오류 해결! (SecurityFilterChain 최신 설정) 패턴으로 구성해 두면 마이그레이션과 테스트가 수월해집니다.

🚀 이 주제, 우리 서비스에 어떻게 적용할까요?

[Spring Boot 3.x] WebSecurityConfigurerAdapter 제거 오류 해결! (SecurityFilterChain 최신 설정)를 실제 서비스와 조직에 녹여보고 싶다면, 현재 아키텍처와 운영 방식을 한 번 점검해 보는 것부터 시작해 보세요. 팀 위키나 기술 블로그, 사내 스터디 주제로도 아주 좋습니다.

이 글이 도움이 됐다면, 비슷한 엔터프라이즈 사례 글들도 함께 살펴보면서 우리 조직에 맞는 운영 상용구를 정의해 보세요.

AI 생성 이미지: [Spring Boot 3.x] WebSecurityConfigurerAdapter 제거 오류 해결! (SecurityFilterChain 최신 설정)

3. 🚀 결론: 더 깔끔하고 유연하게 진화한 Security 설정

결론적으로 Spring Security의 방향성은 명확합니다. 설정을 Bean으로 분리하고 함수형 스타일을 채택함으로써, 어떤 설정이 적용되는지 추적하기 쉬워졌고 조합성도 좋아졌습니다. WebSecurityConfigurerAdapter에 의존하던 과거 방식에서 벗어나 보세요.

처음에는 불편하지만 적응하면 오히려 설정의 투명성과 유지보수성이 향상됩니다. 다시 한 번 핵심을 정리하면, [Spring Boot 3.x] WebSecurityConfigurerAdapter 제거 오류 해결! (SecurityFilterChain 최신 설정) 방식으로 SecurityFilterChain Bean을 정의하는 것이 표준이고 권장되는 접근입니다.

🧠 개발 환경 최적화: 효율적인 코딩을 위한 필수 아이템

장시간 집중해서 보안 설정을 다루려면 편안한 작업 환경이 도움이 됩니다. 아래는 실무에서 유용하게 쓰이는 도구들로, 생산성과 체력을 지키는 데 도움을 줍니다.

이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.

FAQ

Q: SecurityFilterChain 대신 WebSecurityConfigurerAdapter를 상속받는 다른 방법은 없나요?

A: 공식적으로는 없습니다. Spring Security 6(SB 3.x)부터 WebSecurityConfigurerAdapter는 제거되었고, SecurityFilterChain을 Bean으로 등록하는 방식이 권장됩니다. 구버전을 유지하기보다는 새로운 패턴으로 전환하는 편이 장기적으로 안전합니다.

Q: WebSecurityCustomizer는 무엇인가요?

A: WebSecurityCustomizer는 정적 리소스(CSS, JS, 이미지 등)에 대해 보안 필터를 적용하지 않도록 예외 처리할 때 사용합니다. 필터 체인을 건너뛰게 하여 불필요한 검사를 줄이고 성능을 개선할 수 있습니다.

함께 보면 좋은 엔터프라이즈 사례

• 모노레포 대형서비스 CI 최적화와 캐시전략 및 병렬빌드 분할 실전팁
• 대규모 K8s 멀티클러스터 운영 자동화와 관측 실전 가이드
• 실전에서 AI 기반 로그상관으로 장애원인 자동분석 및 재발방지추천