[TroubleShooting] 주니어 개발자들을 울게 만드는 CORS 에러

👀 현재 상황 및 배경 설명

🔽 SecurityConfig API 요청 흐름

현재 API 요청은 공개 접근 필터 체인과 인증이 필요한 필터 체인, 어드민 권한 필터 체인을 순차적으로 거치게 되어있다.

1. 공개 접근 필터 체인: 로그인 없이도 접근 가능한 엔드포인트를 처리한다.
2. 인증이 필요한 필터 체인: 로그인이 반드시 요구되는 엔드포인트를 처리한다.
3. 어드민 권한 필터 체인: 어드민만 접근할 수 있는 엔드포인트를 처리한다.

🔽 CORS 설정

Spring Security에서 CORS를 설정하는 방법은 크게 두 가지가 있다.

1. CorsFilter Bean 등록
2. CorsConfigurationSource Bean 등록

현재 프로젝트에서는 CorsConfigurationSource를 사용하여 CORS를 설정했다.

 

▶ 구현 코드

🔽 SecurityConfig 클래스: 필터 체인

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
@RequiredArgsConstructor
public class SecurityConfig {

    ...

    // 공개 접근 필터 체인
    @Bean
    @Order(1)
    public SecurityFilterChain publicFilterChain(HttpSecurity http) throws Exception {
        defaultSecuritySetting(http);
        http
                .securityMatchers(matcher -> matcher
                        .requestMatchers(publicRequestMatchers()))
                .authorizeHttpRequests(authorize -> authorize
                        .requestMatchers(publicRequestMatchers()).permitAll()
                        .anyRequest().authenticated()
                );
        return http.build();
    }

    // 인증 및 권한이 필요한 필터 체인
    @Bean
    @Order(2)
    public SecurityFilterChain authenticatedFilterChain(HttpSecurity http) throws Exception {
        defaultSecuritySetting(http);
        http
                .securityMatchers(matcher -> matcher
                        .requestMatchers(authenticatedRequestMatchers()))
                .authorizeHttpRequests(authorize -> authorize
                        .requestMatchers(authenticatedRequestMatchers())
                        .hasAnyAuthority(RoleType.ROLE_USER.name(), RoleType.ROLE_ADMIN.name())
                        .anyRequest().authenticated())
                .exceptionHandling(exception -> exception
                        .accessDeniedHandler(customAccessDeniedHandler))
                .addFilterBefore(new JwtFilter(jwtService), UsernamePasswordAuthenticationFilter.class);
        return http.build();
    }

    // 어드민 권한이 필요한 필터 체인
    @Bean
    @Order(3)
    public SecurityFilterChain adminFilterChain(HttpSecurity http) throws Exception {
        defaultSecuritySetting(http);
        http
                .securityMatchers(matcher -> matcher
                        .requestMatchers(adminRequestMatchers()))
                .authorizeHttpRequests(authorize -> authorize
                        .requestMatchers(adminRequestMatchers())
                        .hasAuthority(RoleType.ROLE_ADMIN.name())
                        .anyRequest().authenticated())
                .exceptionHandling(exception -> exception
                        .accessDeniedHandler(customAccessDeniedHandler))
                .addFilterBefore(new JwtFilter(jwtService), UsernamePasswordAuthenticationFilter.class);
        return http.build();
    }

    // 공개 접근 endpoint
    private RequestMatcher[] publicRequestMatchers() { ... }

    // 인증 및 권한이 필요한 endpoint
    private RequestMatcher[] authenticatedRequestMatchers() { ... }

    // 어드민 권한이 필요한 endpoint
    private RequestMatcher[] adminRequestMatchers() { ... }

🔽 SecurityConfig 클래스: CORS 설정

    // Spring Security 기본 설정 메서드
    private void defaultSecuritySetting(HttpSecurity http) throws Exception {
        http
                // CORS 설정
                .cors(cors -> cors.configurationSource(corsConfigurationSource()))
				...
    }

    // CORS 설정
    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        CorsConfiguration configuration = new CorsConfiguration();

        configuration.setAllowedOrigins(Arrays.asList("*"));
        configuration.setAllowedMethods( ... );
        configuration.setAllowedHeaders( ... );
        configuration.setAllowCredentials(true);

        source.registerCorsConfiguration("/**", configuration);

        return source;
    }
}

 

 

🚨 문제 상황

▶ 1. Allow Origin에 와일드카드(*) 사용 관련 에러

CORS 설정에서 허용 출처(Allow Origin)에 와일드카드(*)를 사용했더니, 모든 요청에서 CORS 에러가 발생했다. 서버 로그를 확인한 결과, 다음과 같은 에러 메시지를 확인할 수 있었다.

 

▶ 2. Preflight 요청 에러

CORS를 설정한 이후, 브라우저에서 Preflight 요청(OPTIONS 메서드) 에러가 발생했다.

 

▶ 3. Preflight 설정 이후에도 여전히 발생하는 Preflight 요청 에러

Preflight 요청 처리를 설정한 이후에도, 계속해서 Prefiglht 요청 에러가 발생했다.

이를 확인하기 위해 JwtFilter에서 OPTIONS 메서드가 도달할 경우 로그를 남기도록 설정했으나, 해당 로그가 출력되지 않았다. 이를 통해 Preflight 요청이 애초에 Spring Security 필터 체인에 도달하지 않았다는 것을 확인할 수 있었다.

정상적인 경우에는 아래와 같은 로그가 출력되어야 한다.

 

 

✏️ 원인 분석

▶ 1. Allow Origin에 와일드카드(*)를 사용하지 못하는 이유?

CORS 설정에서 Access-Control-Allow-Origin 헤더에 와일드카드(*)를 사용하면, 모든 도메인에서의 요청을 허용할 수 있다. 그러나 Access-Control-Allow-Credentials: true가 설정된 요청에서는 와일드카드를 사용할 수 없다. 와일드카드는 모든 도메인에서 요청을 허용하기 때문에, 민감한 데이터를 처리하는 API의 경우 보안 취약점으로 이어질 수 있기 때문이다. 즉, 인증 정보가 포함된 요청에서는 명시적으로 허용된 Origin을 지정해야 한다.

 

▶ 2. Preflight 요청 에러가 발생한 이유

Preflight
브라우저가 CORS 정책을 적용할 때 보안상의 이유로 실제 요청 전에 서버에 확인 요청을 보내는 메커니즘으로, HTTP OPTIONS 메서드를 사용한다.

🔽 Preflight 요청 에러가 발생한 이유

Spring 공식 문서에 따르면, CORS는 Spring Security보다 먼저 처리되어야 한다고 명시되어 있다. 그 이유는 Preflight 요청이 쿠키(JESESSIONID)나 인증 정보를 포함하지 않기 때문이다. Preflight 요청은 브라우저가 서버의 CORS 정책을 확인하기 위해 보내는 특수한 요청으로, 비즈니스 로직이나 인증/권한 검사를 위한 요청이 아니다.

만약 Spring Security가 먼저 설정될 경우, Spring Security가 Preflight 요청도 일반 비즈니스 요청으로 간주해 필터 체인을 통과하지 못한다. 이는 Preflight 요청이 어떠한 필터 체인의 엔드포인트와도 매칭되지 않기 때문이다.

결론적으로, Preflight 요청은 단순히 브라우저가 CORS 정책을 확인하기 위해 보내는 요청이므로, 비즈니스 로직이나 인증/권한 검사 대상이 되어서는 안 되기 때문에 CORS 처리는 Spring Security보다 우선적으로 이루어져야 한다.

🔽 Spring Security에서 Preflight 요청 설정 방법: 잘못된 방법

아래는 Preflight 요청을 처리하기 위한 설정 방법이다.

public class SecurityConfig {

    ...
    
    // Spring Security 기본 설정 메서드
    private void defaultSecuritySetting(HttpSecurity http) throws Exception {
        http
                // CORS 설정
                .cors(cors -> cors.configurationSource(corsConfigurationSource()))
                // Preflight 설정 (틀린 설정이니 참고 X)
                .authorizeHttpRequests(authorize -> authorize
                        .requestMatchers(CorsUtils::isPreFlightRequest).permitAll())
    }
}

그러나, 이는 틀린 설정 방법이다. 3번에서 이 설정의 문제점과 개선 방법을 확인하자.

 

▶ 3. Preflight 설정 이후에도 여전히 Preflight 요청 에러가 발생한 이유

🔽 CorsFilter가 인증 필터 이후에 실행되고 있는가? 

cors() 메서드는 내부적으로 CorsFilter를 생성한다. 이를 확인하기 위해 직접 해당 클래스를 분석했다.

처음에는 CorsFilter가 인증을 요구하는 필터보다 뒤에서 실행되고 있어 문제가 발생할 것으로 추측했다. 아래는 Spring Security에서 사용하는 기본 필터들이다.

필터 체인이 초기화될 때, 등록된 필터와 그 실행 순서를 확인하기 위해 로그를 추가하여 출력해 보았다.

결과적으로, 인증을 요구하는 모든 필터가 CorsFilter 뒤에서 실행되고 있었음을 확인했다. 따라서, 이번 문제는 필터 순서의 문제는 아니었음을 알 수 있었다.

🔽 Spring Security에서 Preflight 요청 설정 방법

Spring Security 공식 문서를 정독한 결과, 원인을 파악할 수 있었다.

문제는 securityMatchers()와 authorizeHttpRequests()의 차이를 제대로 이해하지 못하고 사용한 데 있었다.

Spring Security는 HTTP 요청을 처리할 때 필터 체인을 활용하며, 애플리케이션에서는 여러 개의 필터 체인을 정의할 수 있다. 각 필터 체인은 특정 요청 경로에만 적용되며, 이 요청 경로와 필터 체인을 연결하는 역할을 securityMatchers()와 authorizeHttpRequests()가 수행한다.

• securityMatchers()
  • 특정 필터 체인이 적용될 요청을 결정한다.
  • 즉, 특정 필터 체인이 요청을 처리할지 여부를 결정짓는 기준이다.
  • 요청이 securityMatchers() 조건과 일치하지 않으면, 해당 필터 체인은 아예 실행되지 않는다.
• authorizeHttpRequests()
  • 필터 체인 내부에서 요청 허용/거부를 결정한다.
  • 즉, 필터 체인이 이미 선택된 상황에서, 요청을 허용할지/거부할지를 결정한다.
  • 요청이 필터 체인의 매칭 조건을 통과한 이후의 동작을 정의한다.

결론적으로 요청이 Spring Security의 필터 체인에 도달하려면 먼저 securityMatchers()의 조건과 일치해야 한다. 하지만 문제는 Preflight 요청을 처리하기 위한 설정이 securityMatchers()가 아닌, authorizeHttpRequests()에 작성되어 있었던 것이다. 이로 인해 Preflight 요청이 필터 체인에 도달하지 못해 문제가 발생했었다.

구글링을 통해 authorizeHttpRequests()로 Preflight 요청을 처리했다는 글이 많이 있어 이를 적용해 보았으나, 작동하지 않았다. 추후 조사해 보니, Spring Security 5.5 버전부터 securityMatchers()와 authorizeHttpRequests()의 역할이 더 명확하게 구분되었다고 한다. (이 정보는 명확하지 않으므로 참고만 바란다.)

 

 

🔨 해결 방법

▶ Allow Origin에 와일드카드(*) 사용 금지

🔽 변경 전

// CORS 설정
@Bean
public CorsConfigurationSource corsConfigurationSource() {
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    CorsConfiguration configuration = new CorsConfiguration();

    configuration.setAllowedOrigins(Arrays.asList("*")); // 와일드카드 사용
    configuration.setAllowedMethods( ... );
    configuration.setAllowedHeaders( ... );
    configuration.setAllowCredentials(true);

    source.registerCorsConfiguration("/**", configuration);

    return source;
}

🔽 변경 후

// CORS 설정
@Bean
public CorsConfigurationSource corsConfigurationSource() {
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    CorsConfiguration configuration = new CorsConfiguration();

    // 명시적인 Origin 사용
    configuration.setAllowedOrigins(
            Arrays.asList(
                    "http://localhost:8080",
                    "http://127.00.1:8080",
                    "http://localhost:5173",
                    "http://127.0.0.1:5173",
                    ...
            )
    );
    configuration.setAllowedMethods( ... );
    configuration.setAllowedHeaders( ... );
    configuration.setAllowCredentials(true);

    source.registerCorsConfiguration("/**", configuration);

    return source;
}

 

▶ CORS 적용 - CorsConfigurationSource 방식: Preflight 요청 허용

🔽 변경 전

// Spring Security 기본 설정 메서드
private void defaultSecuritySetting(HttpSecurity http) throws Exception {
    http
            // CORS 설정
            .cors(cors -> cors.configurationSource(corsConfigurationSource()))
            // authorizeHttpRequests()에 Preflight 허용 설정 추가
            .authorizeHttpRequests(authorize -> authorize
                    .requestMatchers(CorsUtils::isPreFlightRequest).permitAll())
            ...
}

🔽 변경 후

// Spring Security 기본 설정 메서드
private void defaultSecuritySetting(HttpSecurity http) throws Exception {
    http
            // CORS 설정
            .cors(cors -> cors.configurationSource(corsConfigurationSource()))
            // securityMatchers()에 Preflight 허용 설정 추가
            .securityMatchers(authorize -> authorize
                    .requestMatchers(CorsUtils::isPreFlightRequest).permitAll())
            ...
}

 

▶ CORS 적용 - CorsFilter 방식

사실 가장 쉽고 빠른 방법은 CorsFilter를 사용하는 것이다. 공식 문서에서도 이 방식을 가장 권장하고 있다. 이 방식은 귀찮게 Preflight 요청 설정을 따로 해주지 않아도 자동으로 처리해준다.

🔽 CorsFilter에서 사용하는 DefaultCorsProcessor의 Preflight 요청 처리 확인

CorsFilter에서 사용하는 DefaultCorsProcessor를 직접 확인하여, Preflight 요청을 자동으로 처리하는지 직접 확인해 보았다. DefaultCorsProcessor 내부 코드를 살펴보니, CorsUtils.isPreFlightRequest() 메서드를 통해 Preflight 요청을 처리하는 것을 확인할 수 있었다.

🔽 설정 방법

아래는 CorsFilter 설정 예시다.

@Configuration
public class CorsConfig {

    @Bean
    public CorsFilter corsFilter() {
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        CorsConfiguration configuration = new CorsConfiguration();

        configuration.setAllowedOrigins(
                Arrays.asList(
                        "http://localhost:8080",
                        "http://127.0.0.1:8080",
                        "http://localhost:5173",
                        "http://127.0.0.1:5173",
                        ...
                )
        );
        configuration.setAllowedMethods( ... );
        configuration.setAllowedHeaders( ... );
        configuration.setAllowCredentials(true);

        source.registerCorsConfiguration("/**", configuration);
        
        return new CorsFilter(source);
    }
}

위 클래스만 추가하면, SecurityConfig에서 별도의 CORS 설정을 하지 않아도 Spring MVC가 Bean으로 등록된 CorsFilter를 자동으로 감지하여 CORS 설정을 적용한다.

Spring MVC의 CORS 설정 우선순위
1. CorsFilter가 Bean으로 등록되어 있을 경우
2. CorsConfigurationSource가 Bean으로 등록되어 있을 경우
3. Spring MVC가 클래스 패스에 있으면 Spring MVC의 HandlerMappingIntrospector가 CORS 설정을 추론하여 사용

주의 사항
1. 작동하지 않을 경우, 필터 체인에 http.addFilter(corsConfig.corsFilter())를 직접 추가해야 할 수 있다.
2. CorsFilter와 CorsConfigurationSource가 둘 다 Bean으로 등록되어 있을 경우 충돌이 발생할 수 있다.

 

 

🔍 결과 관찰

Preflight 요청(OPTIONS 메서드)이 정상적으로 필터를 통과하며, 엔드포인트들이 올바르게 작동하는 것을 확인할 수 있었다.

 

 

💡 고찰

• 드디어 프로젝트 내내 골머리를 앓게 했던 CORS 문제를 해결하고, 그 근본적인 원인을 파악하는 데 성공했다. 엄청나게 많은 삽질을 했지만, 그 과정에서 Spring Security와 CORS에 대해 깊이 배우는 계기가 되었다. 이 문제가 구글링을 해도 레퍼런스가 많지 않아, 비슷한 문제를 겪는 누군가에게 도움이 될까 싶어 자세히 정리해 글을 남기고자 했다.
• 사실 프로젝트 진행 시간이 부족하다 보니, 문제의 원인을 정확히 파악하지 못한 채 해결 방법만 여러 개 도입해 에러를 잠시 해결해 놨었다. 하지만 정작 원인을 알지 못한 상태로 넘어갔던 것이 늘 찝찝하게 남아 있었다. 프로젝트가 끝난 이후 트러블슈팅을 통해 결국 원인을 파악할 수 있었고, 그동안의 삽질이 헛되지 않았음을 깨달으며 뿌듯함을 느꼈다.
• 이번 문제를 해결하는 과정에서 Spring 공식 문서를 바탕으로 원인을 분석하며, 공식 문서를 꼼꼼히 확인하는 것의 중요성을 다시 한 번 실감했다. 최근 GPT에 의존했던 점을 반성하는 계기가 되었다.
  

 

 

📍 참고 자료

• Spring 공식 문서: CORS
• Spring 공식 문서: cors()
• Spring 공식 문서: Choosing securityMatcher or requestMatchers
• Spring으로 개발하며 맞닥뜨린 CORS!
• [이슈해결] CORS with Spring (MVC, Security)
• springboot 35강 - Security Cors 설정 (정리)
• [Spring Security] Spring Security Filter Chain 에 대해