Spring Security에서 모든 에러가 403으로 발생하는 문제

 

 

Spring Security를 사용할 때 400 에러가 발생해야할 상황에 403에러가 발생하는 문제가 발생했습니다..

 

왜 모든 에러가 403 Forbidden으로 응답될까?

 

현재 상황은 Spring Boot 애플리케이션에 Spring Security를 적용하고 API를 테스트중 분명 로직상으로는 400 Bad Request (예: 요청 DTO 유효성 검사 실패) 또는 409 Conflict (예: 중복된 리소스 생성 시도) 등이 발생해야 하는데, 뜬금없이 403 Forbidden 응답만 돌아오는 상황입니다.

 

또 그렇다고 에러가 아닌 정상 요청을 보내면 403이 아니라 200이 돌아오고 있습니다.

 

Spring Security는 어떻게 에러를 처리하는가?

 

Spring Boot와 Spring Security가 예외를 처리하는 과정을 살펴보면

 

1. 애플리케이션에서 예외 발생
   
   => 컨트롤러의 유효성 검사 실패(MethodArgumentNotValidException), 서비스 로직에서의 IllegalArgumentException 등 예외 발생
   
   
2. Spring Boot의 기본 예외 처리
   
   => Spring Boot는 이러한 예외가 발생하면 기본적으로 response.sendError()를 호출하여 WAS(예: Tomcat)에게 에러 상황을 알림
   
   
3. WAS의 에러 페이지 요청
   
   => WAS는 이 에러를 받으면 사용자에게 보여줄 적절한 에러 페이지를 다시 Spring Boot 애플리케이션에 요청함
   (이때 요청하는 경로가 바로 "/error" )
   
   
4. Spring Security의 개입 (여기서 문제 발생!!)
   
   => Spring Security는 기본적으로 모든 요청을 감시하며, 인증되지 않은 접근을 차단하는데 만약 SecurityConfig에서 /error 경로에 대해 특별히 접근 권한을 설정해주지 않았다면, Spring Security는 이 "/error" 요청조차 "인증되지 않은 사용자의 접근"으로 간주함
   
   
5. Http403ForbiddenEntryPoint 호출
   
   => 인증되지 않은 사용자가 보호된 리소스(/error 경로)에 접근하려고 할 때, Spring Security는 기본적으로 Http403ForbiddenEntryPoint를 호출함
   
   (이 컴포넌트는 클라이언트에게 403 Forbidden 응답을 보냄)

 

결국, 이런 흐름으로 원래 발생했던 예외(400, 409 ... 등)는 /error 경로로 리디렉션되는 과정에서 Spring Security에 의해 가로막히고, 최종적으로는 403 응답만 받게 되는 것임

 

해결 과정 및 각 컴포넌트의 역할

 

1. SecurityConfig에 "/error" 경로 허용

 

// SecurityConfig.java
private static final String[] PERMIT_URL_ARRAY = {
        // ... 다른 경로들 ...
        "/error",
        // ...
};

// ...
.authorizeHttpRequests(auth -> auth
        .requestMatchers(PERMIT_URL_ARRAY).permitAll()
        .anyRequest().authenticated()
)
// ...

 

가장 먼저 "/error" 경로에 대해 모든 사용자가 접근할 수 있도록 permitAll() 설정하였음

 

이렇게 하면 Spring Security가 "/error" 경로 자체에 대한 접근을 막지 않으므로, Tomcat이 에러 페이지를 요청했을 때 403 대신 Spring Boot의 BasicErrorController가 응답을 처리할 수 있게됨

 

BasicErrorController는 발생한 예외에 따라 적절한 HTTP 상태 코드(ex. 400, 500)와 기본 오류 메시지를 JSON 형태로 반환해줌

 

=> 하지만 BasicErrorController가 반환하는 응답 형식이 기대했던 표준화된 API 오류 응답 형식이 아닐 수 있고, 특히 Spring Security가 직접 처리하는 인증(Authentication) 및 인가(Access Denied) 관련 예외에 대해서는 여전히 기본 동작대로 HTML 페이지를 반환하려고 하거나, 원치 않는 방식으로 처리될 수 있음!!!

(AuthenticationEntryPoint와 AccessDeniedHandler를 커스터마이징하는 이유임🙂‍↔️)

 

2. customAuthenticationEntryPoint 와 customAccessDeniedHandler 등록

 

// SecurityConfig.java

// ...
.exceptionHandling(exceptions -> exceptions
        .authenticationEntryPoint(customAuthenticationEntryPoint()) // 인증 실패 시 처리
        .accessDeniedHandler(customAccessDeniedHandler())       // 인가 실패 시 처리
)
// ...

@Bean
public AuthenticationEntryPoint customAuthenticationEntryPoint() {
    return (request, response, authException) -> {
        response.setContentType("application/json;charset=UTF-8");
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); // 401
        Map<String, Object> body = new HashMap<>();
        body.put("status", HttpServletResponse.SC_UNAUTHORIZED);
        body.put("error", "Unauthorized");
        body.put("message", "인증이 필요하거나 유효하지 않은 인증 정보입니다: " + authException.getMessage());
        new ObjectMapper().writeValue(response.getWriter(), body);
    };
}

@Bean
public AccessDeniedHandler customAccessDeniedHandler() {
    return (request, response, accessDeniedException) -> {
        response.setContentType("application/json;charset=UTF-8");
        response.setStatus(HttpServletResponse.SC_FORBIDDEN); // 403
        Map<String, Object> body = new HashMap<>();
        body.put("status", HttpServletResponse.SC_FORBIDDEN);
        body.put("error", "Forbidden");
        body.put("message", "해당 리소스에 접근할 권한이 없습니다: " + accessDeniedException.getMessage());
        new ObjectMapper().writeValue(response.getWriter(), body);
    };
}

 

• AuthenticationEntryPoint: 인증되지 않은 사용자(ex, 유효하지 않은 JWT 토큰, 토큰 없음)가 보호된 리소스에 접근하려고 할 때 호출됨
  
  => customAuthenticationEntryPoint에서는 이를 가로채서 일관된 JSON 형식의 401 Unauthorized 응답을 보내도록 설정

• AccessDeniedHandler: 인증은 되었지만(유효한 사용자는 맞지만) 해당 리소스에 접근할 특정 권한이 없는 경우 호출됨
  
  => customAccessDeniedHandler에서는 이를 가로채서 일관된 JSON 형식의 403 Forbidden 응답을 보내도록 설정
  
  

이 두 handler를 SecurityConfig의 exceptionHandling()에 등록하면 Spring Security 필터 체인 내에서 발생하는 인증/인가 관련 예외는 정의한 방식대로 깔끔하게 JSON 응답으로 처리됨

 

3. GlobalExceptionHandler 추가 (@RestControllerAdvice)

 

// 예시: GlobalExceptionHandler.java

@Slf4j
@RestControllerAdvice 
public class GlobalExceptionHandler {

    // 공통 에러 응답 생성 메소드
    private ResponseEntity<Map<String, Object>> createErrorResponse(HttpStatus status, String errorCode, String message, Map<String, String> validationErrors) {
        Map<String, Object> responseBody = new HashMap<>();
        responseBody.put("status", status.value());
        responseBody.put("error", errorCode);
        responseBody.put("message", message);
        if (validationErrors != null && !validationErrors.isEmpty()) {
            responseBody.put("errors", validationErrors);
        }
        return ResponseEntity.status(status).body(responseBody);
    }

    // DTO 유효성 검사 실패 시 (jakarta.validation.Valid)
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST) // 기본적으로 400 응답
    public ResponseEntity<Map<String, Object>> handleValidationExceptions(MethodArgumentNotValidException ex) {
        log.warn("Validation failed: {}", ex.getMessage());
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getAllErrors().forEach((error) -> {
            String fieldName = ((FieldError) error).getField();
            String errorMessage = error.getDefaultMessage();
            errors.put(fieldName, errorMessage);
        });
        return createErrorResponse(HttpStatus.BAD_REQUEST, "ValidationFailed", "입력값 유효성 검사에 실패했습니다.", errors);
    }

    // 서비스 로직 등에서 명시적으로 잘못된 인수를 전달했을 때
    @ExceptionHandler(IllegalArgumentException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST) // 400 응답
    public ResponseEntity<Map<String, Object>> handleIllegalArgumentException(IllegalArgumentException ex) {
        log.warn("Illegal argument: {}", ex.getMessage(), ex);
        return createErrorResponse(HttpStatus.BAD_REQUEST, "IllegalArgument", ex.getMessage(), null);
    }

    // 부적절한 상태에서 메소드가 호출되었을 때 (예: 이미 처리된 요청 재시도)
    @ExceptionHandler(IllegalStateException.class)
    @ResponseStatus(HttpStatus.CONFLICT) // 409 응답 (또는 상황에 따라 400)
    public ResponseEntity<Map<String, Object>> handleIllegalStateException(IllegalStateException ex) {
        log.warn("Illegal state: {}", ex.getMessage(), ex);
        return createErrorResponse(HttpStatus.CONFLICT, "IllegalState", ex.getMessage(), null);
    }
    
    // ... 기타 예외 처리 메서드

    // 위에서 명시적으로 처리하지 않은 모든 예외
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR) // 500 응답
    public ResponseEntity<Map<String, Object>> handleAllUncaughtException(Exception ex) {
        log.error("Unhandled exception occurred: {}", ex.getMessage(), ex);
        return createErrorResponse(HttpStatus.INTERNAL_SERVER_ERROR, "InternalServerError", "서버 내부 오류가 발생했습니다. 관리자에게 문의해주세요.", null);
    }
}

 

GlobalExceptionHandler는 @RestControllerAdvice 어노테이션을 사용하여 애플리케이션 전반에서 발생하는 예외들을 한 곳에서 처리하는 역할을함

=> Spring Security의 인증/인가 필터를 통과한 후, 컨트롤러나 서비스 레이어에서 발생하는 예외들(예: MethodArgumentNotValidException (DTO 유효성 검증 실패), IllegalArgumentException, IllegalStateException 등 비즈니스 로직 관련 예외)을 처리함

 

@ExceptionHandler 어노테이션을 사용해 특정 예외 타입별로 처리 로직을 정의할 수도 있음

 

/error 경로를 열고, Spring Security 예외 처리기를 커스텀했더라도, 애플리케이션 코드 내에서 발생하는 일반적인 예외들은 여전히 BasicErrorController에 의해 기본 방식으로 처리될 수 있는데 GlobalExceptionHandler를 사용하면 이러한 예외들까지도 미리 정의한 일관된 JSON 오류 형식으로 응답할 수 있게됨

결론

 

정리를 해보면

 

1. 어떤 종류의 예외든 발생하면, Spring Boot는 /error 경로로 내부 리디렉션을 시도함
   
   
2. SecurityConfig에서 "/error" 경로를 permitAll()로 설정했기 때문에, 이 /error 요청은 Spring Security에 의해 차단되지 않음
   
   
3. 이제 예외의 종류에 따라 처리 주체가 달라짐

• Spring Security 관련 예외 (인증 실패, 인가 실패)는 HttpSecurity에 등록된 customAuthenticationEntryPoint 또는 customAccessDeniedHandler가 동작하여 미리 정의한 401 또는 403 JSON 응답을 반환함

• 애플리케이션 레벨 예외 (ex. DTO 유효성 검사, 비즈니스 로직 예외 등)는 /error 경로를 통해 BasicErrorController로 전달되려 하지만, 그 전에 @RestControllerAdvice로 선언된 GlobalExceptionHandler가 먼저 가로챔 
  
  => GlobalExceptionHandler 내의 적절한 @ExceptionHandler 메소드가 해당 예외를 처리하여, 우리가 정의한 HTTP 상태 코드(400, 409, 500 등)와 JSON 오류 메시지를 반환함

이렇게 클라이언트는 어떤 종류의 오류가 발생하든 일관되고 명확한 오류 응답을 받을 수 있게 됨

 

=> 기존의 모든 오류가 403으로 덮어쓰이는 에러가 해결됨!!