필터 아키텍처 : 주요 보안 필터

- Spring Security에서 제공하는 주요 보안 필터들의 역할

- 각 필터가 요청 / 응답 처리 과정에서 어떤 작업을 수행하는지 구체적으로 알기

- UsernamePasswordAuthenticationFilter와 BasicAuthenticationFilter의 차이 알기

- 인증, 권한 부여, 예외 처리, 세션 관리까지 필터 체인 내에서 어떻게 수행되는가

---

주요 보안 필터의 이해

Spring Security는 다양한 보안 시나리오를 처리하기 위해 여러개의 보안 필터(Filter)를 제공한다

이 필터들은 Servlet Filter Chain 안에서 순차적으로 동작하며, 각자의 역할을 수행한다

 

1. UsernamePasswordAuthenticationFilter

이 필터는 Spring Security에서 가장 널리 사용되는 인증 필터중 하나임

기본적으로 폼 로그인(Form Login) 요청을 처리하기 위해 사용된다

하지만 반드시 폼 로그인에만 국한되지 않고, 개발자가 원하는 방식으로 확장해 REST API 기반 로그인 처리 등에도 활용 가능함

 

 

(1) 주요 역할

• 클라이언트가 전달한 사용자 이름(username)과 비밀번호(password)를 HTTP 요청에서 추출한다
• 추출한 인증 정보를 기반으로 UsernamePasswordAuthenticationToken 객체를 생성한다
• 생성된 토큰은 AuthenticationManager로 전달되어 실제 인증 절차가 진행된다
• 인증에 성공하면 SecurityContext에 인증 객체가 저장되고, 이후의 요청에서 인증된 사용자로 인식된다

(2) 기본 동작 흐름

1. 사용자가 로그인 요청(/login 등 엔드포인트)에 username, password를 전달함
2. UsernamePasswordAuthenticationFilter에서는 요청에서 해당 값을 추출한다
3. UsernamePasswordAuthenticationToken을 생성하여 AuthenticationManager에 전달함
4. AuthenticationManager는 등록된 AuthenticationProvider(DaoAuthenticationProvider 등)를 통해 사용자 정보를 검증한다
5. 인증 성공시 SecurityContextHolder에 인증 정보가 저장된다

UsernamePasswordAuthenticationFilter.. 이름 참 길다!

 

 

(3) 확장 가능성

• REST API 로그인 처리 : 기본 폼 요청이 아닌 JSON 기반 로그인 요청을 처리하도록 확장할 수 있음
  가령 username과 password를 JSON Request Body에서 추출하는 커스텀 필터로 변형할 수 있다
• 엔드포인트 변경 : 기본 URL(/login) 외에 원하는 로그인 엔드포인트로 설정을 변경할 수 있다
• 추가 인증 요소 : 단순 username / password 외에 OTP, Captcha, 2FA 코드 등을 함께 검증하도록 확장할 수 있다

 

(4) 주의

• 이 필터는 어디까지나 username / password 기반 인증만 담당한다
• OAuth2, OIDC 기반 인증은 별도의 필터(OAuth2LoginAuthenticationFilter 등)가 동작하므로
  UsernamePasswordAuthenticationFilter 와는 직접적으로 연관되지 않는다

 

 

 

2. BasicAuthenticationFilter

• 역할 : HTTP Basic 인증을 처리함
• 주요 동작
  1. 요청 헤더에서 Authorization: Basic ... 값을 확인함
  2. Base64 디코딩을 통해 username:password를 추출함
  3. AuthenticationManager를 통해 인증을 진행함

# 대충 이런 형태
GET /secure-data HTTP/1.1
Host: example.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

 

REST API 서버에서 테스트나 간단한 인증 방식으로 자주 사용된다고 함

 

구분	UsernamePasswordAuthenticationFilter	BasicAuthenticationFilter
인증 방식	ID / PW 기반 로그인(POST / login)	HTTP Basic(Authorization 헤더)
입력 방식	요청 파라미터(username, password)	요청 헤더(Authorization: Basic ...)
사용 예시	웹 애플리케이션 로그인 폼	REST API 보안, 테스트 환경 등

 

 

 

3. DefaultLoginPageGeneratingFilter

FilterChain 설정을 하지 않고 implements만 하고 실행하면 나오는 화면

 

플리즈 로그~인

 

• 역할 : 사용자가 별도의 로그인 페이지를 구현하지 않은 경우, Spring Security가 기본으로 제공하는 로그인 페이지
• 특징
  • HTML 폼을 자동으로 생성함
  • 학습이나 빠른 테스트 목적에서 편리함
  • 실무에서는 거의 사용하지 않고, 커스텀 로그인 페이지를 구현하는 경우가 많음

 

 

4. LogoutFilter

• 역할 : 사용자의 로그아웃을 처리함
• 주요 동작
  1. 기본적으로 /logout 요청을 감지함
  2. 세션 무효화(Session Invalidation)를 수행함
  3. SecurityContext에서 인증 정보를 제거함

 

Spring Security 5 버전 Logout 빌드

@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.logout()
            .logoutUrl("/logout")
            .logoutSuccessUrl("/login?logout")
            .invalidateHttpSession(true)
            .deleteCookies("JSESSIONID");
    }
}

 

 

Spring Boot 3.xx / Spring Security 6 버전

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
                .logout(logout -> logout
                        .logoutUrl("/logout")
                        .logoutSuccessUrl("/login?logout")
                        .invalidateHttpSession(true)
                        .deleteCookies("JSESSIONID")
                        );
        return http.build();
    }

 

* 실무에서는 로그아웃 후 특정 페이지로 리다이렉트 하거나, 토큰 기반 로그아웃 처리를 추가하는 경우가 많다고 함

 

 

 

5. SecurityContextPersistenceFilter

• 역할 : 요청이 시작될 때 SecurityContext를 로드하고, 요청이 끝나면 SecurityContext를 저장한다
• 동작 원리
  • 일반적으로 세션(HttpSession)에 SecurityContext를 저장한다
  • 따라서 사용자가 로그인하면 다음 요청에서도 동일한 인증 정보를 유지할 수 있다

Client 요청에 따른 SecurityContextPersistenceFilter의 SecurityContext 저장 흐름

 

 

* 로그인 유지(Session 기반 인증)의 핵심 필터임

 

 

 

6. ExceptionTranslationFilter

• 역할 : 보안 처리 중 발생하는 예외(AuthenticationException, AccessDeniedException)을 처리한다
• 주요 동작
  • 인증이 필요한데 인증되지 않은 경우 - > 로그인 페이지로 리다이렉트함
  • 인가 실패(권한 없음)인 경우 - > 403 Forbidden 응답을 반환함

// 예시
try {
    chain.doFilter(request, response);
} catch(AuthenticationException ex) {
    // 인증 실패 시 처리 로직 작성
    redirectToLoginPage();
} catch(AccessDeniedException ex) {
    sendError403();
}

 

 

 

7. FilterSecurityInterceptor

• 역할 : 최종 인가(Authorization) 결정을 수행하는 필터
• 주요 동작
  1. 현재 요청에 필요한 권한을 확인함
  2. AccessDecisionManager를 통해 접근 허용 / 거부 여부를 결정함
  3. 인가가 허용되면 Controller로 요청이 전달됨

    @PreAuthorize("hasRole('ADMIN')")
    @GetMapping("/admin")
    public String admin() {
        return "admin";
    }

 

* 실무에서 @PreAuthorize, @Secured 같은 애너테이션이 동작하는 기반이 되는 필터임

---

팁

* 모든 보안 필터가 항상 동작하는것은 아니다. 설정(HttpSecurity)에 따라 일부만 활성화된다

* Custom Filter를 추가할 땐 적절한 위치를 반드시 지정해야한다.

(인증 전에 동작해야하는 경우 UsernamePasswordAuthenticationFilter 앞에 등록하기)

* 디버깅 시 springSecurityFilterChain 로그를 확인하면 어떤 필터가 수행중인지 확인할 수 있다

---

 정리

필터	역할	특징
UsernamePasswordAuthenticationFilter	폼 로그인 처리	username, password 인증
BasicAuthenticationFilter	HTTP Basic 인증 처리	Authorization 헤더 기반
DefaultLoginpageGeneratingFilter	기본 로그인 페이지 생성	실무보다는 테스트용
LogoutFilter	로그아웃 ㅊ처리	세션 무효화, 쿠키 삭제
SecurityContextPersistenceFilter	SecurityContext 관리	세션 유지 기반
ExceptionTranslationFilter	인증 / 인가 예외 처리	로그인 리다이렉트, 403 처리
FilterSecurityInterceptor	최종 인가 결정	AccessDecisionManager 활용