[Spring Security] CSRF 설정 403 응답 문제 해결: CsrfTokenRepository에 대한 이해

⚙️ 개발 환경

Spring Boot 3.4.0

Spring Security 6.4.1

 

📌 문제 상황

디스코드잇 미션에 Spring Security를 적용하며 CSRF 보호 설정을 하고 있었습니다.

 

이 프로젝트의 프론트엔드는 서버에서 HTML을 모두 생성하는 SSR(Sever Side Rendering) 방식이 아니라,

클라이언트(브라우저)에서 Javascript를 활용해 HTML을 생성하는 CSR(Client Side Rendering) 방식입니다.

그렇기 때문에 CSRF 토큰 정보 역시 프론트에서 명시적으로 관리해야 했습니다.

 

CSRF 토큰 발급 및 검증 프로세스는 다음과 같습니다. 저는 이 요구사항에 맞춰 백엔드를 구현해야 했습니다.

 

1. 페이지가 로드될 때 서버로부터 CSRF 토큰 발급

2. CSRF 토큰을 쿠키(CSRF-TOKEN)에 저장

3. 매 요청마다 쿠키에 저장된 CSRF 토큰을 헤더(X-CSRF-TOKEN)에 포함

 

프론트엔드에서 CSRF 토큰을 발급받기 위해 GET /api/auth/csrf-token API를 추가했습니다.

@GetMapping("/csrf-token")
    public ResponseEntity<CsrfToken> getCsrfToken(CsrfToken csrfToken) {
        return ResponseEntity.ok(csrfToken);
    }

 

그리고 SecurityConfig에서 csrf 설정을 했습니다.

토큰을 쿠키에 저장해야 하므로 토큰 저장소는 CookieCsrfTokenRepository가 되어야 한다고 생각했습니다.

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    SecurityFilterChain chain(HttpSecurity httpSecurity) throws Exception {
        httpSecurity
            .authorizeHttpRequests(auth -> auth
                // 정적 리소스 요청 허용
                .requestMatchers("/assets/**", "/favicon.ico", "/index.html").permitAll()
                .requestMatchers("/", "/error/*").permitAll()
                // Swagger 요청 허용
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**", "/swagger-ui.html",
                    "/webjars/**").permitAll()
                // Actuator 요청 허용
                .requestMatchers("/actuator/**").permitAll()
                // CSRF 토큰을 발급하는 API 요청 허용
                .requestMatchers("/api/auth/csrf-token").permitAll()
                // 회원가입 API 요청 허용
                .requestMatchers(HttpMethod.POST, "/api/users").permitAll()
                // 그 외 인증 필요
                .anyRequest().authenticated())
            // 📌 여기!! ----------------------------------------------------------------------- 
            .csrf(csrf -> csrf
                // JavaScript에서 쿠키를 읽을 수 있게 함
                .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse()))
            // ---------------------------------------------------------------------------------
            // LogoutFilter 제외
            .logout(httpSecurityLogoutConfigurer -> httpSecurityLogoutConfigurer.disable())
            .httpBasic(Customizer.withDefaults())
            .formLogin(Customizer.withDefaults());
        return httpSecurity.build();
    }

 

실행 결과

 

우선 /api/auth/csrf-token 요청으로 프론트에서는 CSRF 토큰 값을 가져갑니다.

 

그 다음 POST 요청에 대해 403 응답이 옵니다.

 

이때 Request Header를 보면 쿠키와 헤더에 CSRF 토큰이 모두 제대로 들어있습니다.

 

그러나 서버 로그를 보면 "Invalid CSRF token"이라며 CSRF 검증 과정에 실패했습니다.

리퀘스트 헤더와 쿠키 모두에 제대로 된 CSRF 토큰을 가지고 있는 것 같은데 왜일까요?

 

디버깅: CsrfFilter 내부 동작

디버깅 모드로 다시 한 번 요청을 날려봅시다.

이번에는 다음과 같이 Request를 보내고 있습니다.

 

 

CsrfFilter에서 doFilterInternal() 메서드에 중단점을 걸었습니다.

아까 콘솔 로그에서 "Invalid CSRF token..."을 봤으니 우리는 else문을 봐야 합니다.

protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        DeferredCsrfToken deferredCsrfToken = this.tokenRepository.loadDeferredToken(request, response);
        request.setAttribute(DeferredCsrfToken.class.getName(), deferredCsrfToken);
        CsrfTokenRequestHandler var10000 = this.requestHandler;
        Objects.requireNonNull(deferredCsrfToken);
        var10000.handle(request, response, deferredCsrfToken::get);
        if (!this.requireCsrfProtectionMatcher.matches(request)) {
            if (this.logger.isTraceEnabled()) {
                this.logger.trace("Did not protect against CSRF since request did not match " + this.requireCsrfProtectionMatcher);
            }

            filterChain.doFilter(request, response);
        } else {
            CsrfToken csrfToken = deferredCsrfToken.get();
            String actualToken = this.requestHandler.resolveCsrfTokenValue(request, csrfToken);
            if (!equalsConstantTime(csrfToken.getToken(), actualToken)) {
                boolean missingToken = deferredCsrfToken.isGenerated();
                this.logger.debug(LogMessage.of(() -> {
                    return "Invalid CSRF token found for " + UrlUtils.buildFullRequestUrl(request);
                }));
                AccessDeniedException exception = !missingToken ? new InvalidCsrfTokenException(csrfToken, actualToken) : new MissingCsrfTokenException(actualToken);
                this.accessDeniedHandler.handle(request, response, (AccessDeniedException)exception);
            } else {
                filterChain.doFilter(request, response);
            }
        }
    }

 

이때 제 예상으로는 

서버의 토큰 저장소에서 가져온 csrfToken 값과 리퀘스트에서 보낸 actualToken 값이 같아야 합니다.

 

 

 

그런데 actualToken 값은 null이고, csrfToken 값은 제가 생각과 달리

"X-CSRF-TOKEN" 헤더가 아니라 "X-XSRF-TOKEN"에 해당합니다!

 

그러고보니 아까 CSRF 발급 요청에서..

 

 

응답에서 headerName이 X-XSRF-TOKEN이라 적혀있네요.

왜 CSRF가 아니라 XSRF라고 되어 있는걸까요?

 

CSRF 토큰 저장소(CsrfTokenRepository) 비교

CSRF 토큰의 생성 및 관리는 CsrfTokenRepository라는 인터페이스를 정의하고 그것을 구현한 클래스에 위임합니다.

 

• HttpSessionCsrfTokenRepository
  • 기본 설정
  • CSRF 토큰을 HttpSession에 저장합니다.
  • Request 헤더인 X-CSRF-TOKEN 또는 요청 매개변수인 _csrf에서 토큰을 읽습니다.
• CookieCsrfTokenRepository
  • CSRF 토큰을 XSRF-TOKEN 쿠키에 저장합니다.
  • 토큰을 XSRF-TOKEN 쿠키에 작성합니다.
  • Request 헤더인 X-XSRF-TOKEN 헤더 또는 요청 매개변수인 _csrf에서 토큰을 읽습니다.
  • withHttpOnlyFalse() 설정으로 Javascript에서 쿠키를 읽을 수 있게 할 수 있습니다.

토큰 저장소를 어떻게 하느냐에 따라 CSRF 토큰이 저장되는 위치가 다릅니다.

그런데 제가 config 설정에서 토큰 저장소를 CookieCsrfTokenRepository로 명시를 했죠.

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    SecurityFilterChain chain(HttpSecurity httpSecurity) throws Exception {
        httpSecurity
            .authorizeHttpRequests(auth -> auth
                // 정적 리소스 요청 허용
                .requestMatchers("/assets/**", "/favicon.ico", "/index.html").permitAll()
                .requestMatchers("/", "/error/*").permitAll()
                // Swagger 요청 허용
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**", "/swagger-ui.html",
                    "/webjars/**").permitAll()
                // Actuator 요청 허용
                .requestMatchers("/actuator/**").permitAll()
                // CSRF 토큰을 발급하는 API 요청 허용
                .requestMatchers("/api/auth/csrf-token").permitAll()
                // 회원가입 API 요청 허용
                .requestMatchers(HttpMethod.POST, "/api/users").permitAll()
                // 그 외 인증 필요
                .anyRequest().authenticated())
            // 📌 여기!! ----------------------------------------------------------------------- 
            .csrf(csrf -> csrf
                // JavaScript에서 쿠키를 읽을 수 있게 함
                .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse()))
            // ---------------------------------------------------------------------------------
            // LogoutFilter 제외
            .logout(httpSecurityLogoutConfigurer -> httpSecurityLogoutConfigurer.disable())
            .httpBasic(Customizer.withDefaults())
            .formLogin(Customizer.withDefaults());
        return httpSecurity.build();
    }

 

그러니 CsrfFilter에서는 X-XSRF-TOKEN 헤더에서 값을 읽고 있었습니다.

프론트엔드에서는 토큰을 발급받아 X-CSRF-TOKEN 헤더에 저장하여 요청을 보내고 있었으니

서로 맞지 않았던 거죠.

 

참고: https://bestdevelop-lab.tistory.com/100

 

✅ 해결

해결 방법은 두 가지가 있습니다.

1. 프론트에서 CSRF 토큰을 X-XSRF-TOKEN 헤더에 보내거나

2. CsrfFilter에서 X-CSRF-TOKEN 헤더에서 값을 읽거나

 

2번 방법은 아주 간단합니다.

SecurityConfig에서 csrf 설정 시 CookieCsrfTokenRepository를 빼면 됩니다.

X-CSRF-TOKEN 헤더에 토큰을 저장하는 HttpSessionCsrfTokenRepository는 기본값이니 따로 명시하지 않았습니다.

또한 csrf 보호도 기본이 활성화이므로 따로 설정하지 않았습니다.(disable()하면 안 됨)

 

이 방법으로 하니 403 응답이 더 이상 오지 않고 정상적으로 동작합니다!

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    SecurityFilterChain chain(HttpSecurity httpSecurity) throws Exception {
        httpSecurity
            .authorizeHttpRequests(auth -> auth
                // 정적 리소스 요청 허용
                .requestMatchers("/assets/**", "/favicon.ico", "/index.html").permitAll()
                .requestMatchers("/", "/error/*").permitAll()
                // Swagger 요청 허용
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**", "/swagger-ui.html",
                    "/webjars/**").permitAll()
                // Actuator 요청 허용
                .requestMatchers("/actuator/**").permitAll()
                // CSRF 토큰을 발급하는 API 요청 허용
                .requestMatchers("/api/auth/csrf-token").permitAll()
                // 회원가입 API 요청 허용
                .requestMatchers(HttpMethod.POST, "/api/users").permitAll()
                // 그 외 인증 필요
                .anyRequest().authenticated())
            // LogoutFilter 제외
            .logout(httpSecurityLogoutConfigurer -> httpSecurityLogoutConfigurer.disable())
            .httpBasic(Customizer.withDefaults())
            .formLogin(Customizer.withDefaults());
        return httpSecurity.build();
    }
 }