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();
}

 

인증 예외의 세부 정보 처리

문제 

지금처럼 필터에서 예외가 발생하면 AuthenticationEntryPoint로 넘어갈 때 기존 예외의 정보 저장 없이 AuthenticationException으로 감싸서 AuthenticationException을 전달합니다. (정확히는 InsufficientAuthenticationException입니다.) 이로 인해, 발생한 예외의 세부 정보를 확인할 수 없고, 예외 종류에 따른 적절한 응답을 할 수 없습니다.

@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) {
        setErrorResponse(response, TOKEN_EXPIRED);
        return;
    }
    // ExpiredJwtException을 제외한 나머지 JwtException 처리
    if (exception instanceof JwtException) {
        setErrorResponse(response, INVALID_TOKEN_FORMAT);
        return;
    }
    if (exception instanceof ApiException) {
        setErrorResponse(response, ((ApplicationException)exception).getErrorCode());
    }
}

private void setErrorResponse(HttpServletResponse response, ErrorCode errorCode) throws IOException {
	response.setStatus(errorCode.getHttpStatus().value());
	response.setContentType("application/json;charset=UTF-8");

	ErrorResponse errorResponse = new ErrorResponse(errorCode);
	response.getWriter().print(objectMapper.writeValueAsString(errorResponse));
}

 

결과

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