Spring Security 인증 필터 예외 처리하기

인증 필터에서 발생한 예외의 공통 처리

⚠️문제

인증 필터는 기본적으로 Spring Security 필터로서 동작하며, `DispatcherServlet` 이전에 실행됩니다. 이로 인해 `@RestControllerAdvice`의 `@ExceptionHandler`를 통한 예외 처리 방식이 적용되지 않습니다.
(@ExceptionHandler는 DispatcherServlet 내에서 발생한 예외만 처리할 수 있습니다.)

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ApiException.class)
    public ResponseEntity<ErrorResponse> handleApiException(ApiException e) {
        ErrorCode errorCode = e.getErrorCode();

        return ResponseEntity
                .status(errorCode.getHttpStatus())
                .body(new ErrorResponse(errorCode));
    }
}

따라서 이 방식으로는 인증 필터에서 발생한 예외를 원하는 방식으로 공통 응답 처리할 수 없습니다.

 

✅해결

Spring Security가 제공하는 `AuthenticationEntryPoint`를 도입하여 인증 과정에서 발생하는 예외를 별도로 처리하도록 구성했습니다. 이를 통해 인증 필터에서 발생하는 예외는 AuthenticationEntryPoint에서 처리할 수 있게 되었습니다.

• AuthenticationEntryPointImpl

@Component
public class AuthenticationEntryPointImpl implements AuthenticationEntryPoint {

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException authException) throws IOException {
        response.setStatus(HttpStatus.UNAUTHORIZED.value());
        response.setContentType("application/json;charset=UTF-8");
        response.getWriter().write("{\"error\": \"AUTHENTICATION_FAIL\", \"message\": \"잘못된 인증 정보입니다.\"}");
    }
}

 

• SecurityConfig

private final AuthenticationEntryPointImpl authenticationEntryPoint;

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    ...
    http.exceptionHandling(exceptions -> exceptions
            .authenticationEntryPoint(authenticationEntryPoint)
    );
    ...
    return http.build();
}

 

인증 예외의 세부 정보 처리

⚠️문제 

Spring Security는 기본적으로 인증 관련 예외를 `AuthenticationException`으로 감싸서 AuthenticationEntryPoint로 전달합니다. 이로 인해, 넘어온 예외의 세부 정보를 확인할 수 없고, 예외 종류에 따른 적절한 응답을 할 수 없습니다.

@Slf4j
@Component
public class AuthenticationEntryPointImpl implements AuthenticationEntryPoint {

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException authException) throws IOException, ServletException {
        log.info(authException.toString()); // InsufficientAuthenticationException
        
        response.setStatus(HttpStatus.UNAUTHORIZED.value());
        response.setContentType("application/json;charset=UTF-8");
        response.getWriter().write("{\"error\": \"AUTHENTICATION_FAIL\", \"message\": \"잘못된 인증 정보입니다.\"}");
    }
}

org.springframework.security.authentication.InsufficientAuthenticationException: Full authentication is required to access this resource

 

✅해결 

인증 필터에서 발생한 예외를 HttpServletRequest의 속성에 저장한 뒤, AuthenticationEntryPoint에서 이를 조회하여 응답할 수 있도록 했습니다.

• 인증 필터에서 예외 저장

@RequiredArgsConstructor
public class AuthFilter extends OncePerRequestFilter {

    private final AuthService authService;

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        try {
            String authorizationHeader = request.getHeader(AUTHORIZATION_HEADER);
            authService.verifyAuthorizationHeader(authorizationHeader);
            String accessToken = authorizationHeader.split(" ")[1];
            authService.verifyAccessToken(accessToken);
        } catch (ApiException e) {
            request.setAttribute("exception", e);
            filterChain.doFilter(request, response);
            return;
        }
        filterChain.doFilter(request, response);
    }
}

 

• 저장한 예외를 AuthenticationEntryPoint에서 조회 및 응답

@RequiredArgsConstructor
@Component
public class AuthenticationEntryPointImpl implements AuthenticationEntryPoint {

    private final ObjectMapper objectMapper;

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException authException) throws IOException, ServletException {
        Object exception = request.getAttribute("exception");
        response.setStatus(HttpStatus.UNAUTHORIZED.value());
        response.setContentType("application/json;charset=UTF-8");
        response.getWriter().write(objectMapper.writeValueAsString(new ErrorResponse(((ApiException) exception).getErrorCode())));
    }
}

 

참고) AuthenticationException

AuthenticationException, 즉 인증 예외가 발생하면 다음 세 과정이 진행됩니다.

1. SecurityContext에서 인증 정보 삭제
   • 기존 인증 정보가 더 이상 유효하지 않다고 판단하여 Authentication을 초기화합니다.
2. AuthenticationEntryPoint 호출
   • AuthenticationException이 발생하면 필터는 AuthenticationEntryPoint를 실행하여 인증 실패를 공통으로 처리합니다.
3. 인증 프로세스의 요청 정보 저장 및 검색
   • 기본 구현체는 HttpSessionRequestCache입니다.
   • ex) 페이지 A에 접근하려다 로그인 페이지로 리다이렉션된 경우, 인증을 완료한 후, 다시 페이지 A로 이동할 수 있도록 정보를 저장합니다.

 

토큰 검증 과정에서 발생하는 JwtException 처리

⚠️문제  

토큰 만료 여부를 확인하는 코드에서는 커스텀 예외(ApiException)를 발생시키도록 설계했지만, JWT 라이브러리의 내부 로직에서 먼저 `ExpiredJwtException`이 발생하여 의도한 대로 처리되지 않았습니다. 이는 `parseSignedClaims()` 호출 과정에서 서명 검증과 동시에 토큰 만료 여부를 검증하기 때문이었습니다.

• JwtProvider

public Boolean ieExpired(String token) {
    return Jwts.parser()
        .verifyWith(secretKey)
        .build()
        .parseSignedClaims(token) // 여기서 JwtException이 발생
        .getPayload()
        .getExpiration()
        .before(new Date());
}

 

• 토큰 만료 검증 로직

String accessToken = authorization.split(" ")[1];
if (jwtProvider.ieExpired(accessToken)) {
    throw new ApiException(TOKEN_EXPIRED);
}

 

✅해결  

토큰 만료 검증을 직접 하지 않고, JWT 라이브러리의 기본 검증 로직을 활용하여 예외를 발생시키도록 코드를 단순화했습니다. 이후, JwtException과 ApiException을 구분하여 처리하도록 코드를 수정했습니다.

• 토큰의 형식, 만료여부 등과 관련된 JwtException은 직접 처리하지 않습니다.

public void verifyAccessToken(String accessToken) {
    Claims payload = getPayload(accessToken);
    String type = payload.get(CLAIM_TYPE, String.class);
    if (!type.equals(CLAIM_TYPE_ACCESS)) {
        throw new ApiException(INVALID_TOKEN_TYPE);
    }
}
    
private Claims getPayload(String token) {
    return Jwts.parser()
            .verifyWith(secretKey)
            .build()
            .parseSignedClaims(token)
            .getPayload();
}

 

• 처리 대상 예외에 JwtException도 추가합니다.

// 헤더, 토큰 검증
String accessToken;
try {
    String authorizationHeader = request.getHeader(AUTHORIZATION_HEADER);
    authService.verifyAuthorizationHeader(authorizationHeader);
    accessToken = authorizationHeader.split(" ")[1];
    authService.verifyAccessToken(accessToken);
} catch (JwtException | ApiException e) {
    request.setAttribute("exception", e);
    filterChain.doFilter(request, response);
    return;
}

 

• 예외의 종류에 따라 분기하여 각각에 맞는 적절한 응답을 할 수 있도록 했습니다.

@Override
public void commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException authException) throws IOException, ServletException {
    Object exception = request.getAttribute("exception");
    if (exception instanceof ExpiredJwtException) {
        response.setStatus(HttpStatus.UNAUTHORIZED.value());
        response.setContentType("application/json;charset=UTF-8");
        response.getWriter().write(objectMapper.writeValueAsString(new ErrorResponse(TOKEN_EXPIRED)));
        return;
    }
    // ExpiredJwtException을 제외한 나머지 JwtException 처리
    if (exception instanceof JwtException) {
        response.setStatus(HttpStatus.UNAUTHORIZED.value());
        response.setContentType("application/json;charset=UTF-8");
        response.getWriter().write(objectMapper.writeValueAsString(new ErrorResponse(INVALID_TOKEN_FORMAT)));
        return;
    }
    if (exception instanceof ApiException) {
        response.setStatus(HttpStatus.UNAUTHORIZED.value());
        response.setContentType("application/json;charset=UTF-8");
        response.getWriter().write(objectMapper.writeValueAsString(new ErrorResponse(((ApiException) exception).getErrorCode())));
    }
}

 

결과

이제 인증 과정에서 발생하는 예외를 공통으로 처리할 수 있으며, 각 예외를 구별하여 적절한 응답을 할 수 있게 되었습니다.