Spring Security DebugFilter로 보는 실시간 권한 체크

Spring Security의 DebugFilter는 요청이 들어올 때마다 필터 체인 진행 상황·인증·인가 의사결정 과정을 콘솔에 그대로 보여줍니다. 단 몇 줄 설정이면 “왜 403 Forbidden이 떴을까?”를 로그만 보고 바로 파악할 수 있어요.

---

1. DebugFilter가 하는 일

• org.springframework.security.web.debug.DebugFilter가 Filter Chain 가장 앞에 삽입되어 요청‧응답 정보를 상세히 남깁니다.
• 세션 생성·Authentication 객체·AccessDecisionManager 처리 결과까지 모두 로깅해 인증 ↔ 인가 경계를 실시간으로 확인할 수 있습니다.

주의 : DebugFilter는 민감 정보(헤더·세션 ID)를 그대로 노출하므로 로컬/스테이징 에서만 사용하세요.

---

2. 활성화 방법 3종

1. 애너테이션 한 줄
   

   @EnableWebSecurity(debug = true)
   public class SecurityConfig { }

2. application.yml
   

   spring:
     security:
       filter:
         debug: true

   
   
3. 로깅 레벨 강화(선택)

logging:
  level:
    org.springframework.security: DEBUG   # 인증·인가 전반
    org.springframework.security.web.FilterChainProxy: TRACE  # 필터 단계별

 

이 세 가지 중 한 가지만 설정해도
********************************************************************
********** Security debugging is enabled. *************
********** This may include sensitive information. *************
********** Do not use in a production system! *************
********************************************************************
배너가 뜨며 디버그 로그가 시작됩니다.

---

3. 로그 읽는 포인트

Request received for GET '/api/posts/1':
...
Security filter chain: [
  WebAsyncManagerIntegrationFilter
  SecurityContextPersistenceFilter
  HeaderWriterFilter
  LogoutFilter
  UsernamePasswordAuthenticationFilter
  ...
]
DEBUG o.s.s.w.a.i.FilterSecurityInterceptor : Authorizing filter invocation [GET /api/posts/1] with attributes [ROLE_USER]
DEBUG o.s.s.ac.vote.AffirmativeBased         : Voter: RoleVoter, returned: 1

1. Security filter chain : 요청마다 필터 순서가 찍혀서 커스텀 필터 위치 확인이 쉽습니다.
2. FilterSecurityInterceptor : 인가 검사 진입 시점.
3. AffirmativeBased / RoleVoter : AccessDecisionManager가 어떤 Voter로 결정했는지와 결과(0 거부, 1 허용)를 알려줍니다.

---

4. 실시간 권한 디버깅 시나리오

1. 로컬에서 DebugFilter를 켜고 /admin/dashboard 접속.
2. 콘솔에 “Voter returned 0” 가 찍히면 권한 거부 → 해당 URI에 필요한 Role 확인.
3. @PreAuthorize("hasRole('ADMIN')") 로직이라면, 토큰에 ROLE_ADMIN 클레임이 누락됐는지 JWT Payload를 검증.
4. Role 정상 추가 후 재시도 → 로그에 Voter returned 1 & 컨트롤러 진입 메시지까지 확인되면 문제 해결!

---

5. 베스트 프랙티스

• DEBUG → TRACE 단계별로 범위를 좁혀라. TRACE 레벨은 방대한 로그를 쏟아내므로 필요한 URI에서만 활성화.
• profile 별 분리 : application-dev.yml 에만 spring.security.filter.debug=true 설정.
• 모니터링 연동 : 실서비스에선 Micrometer + Prometheus로 401/403 지표를 수집하고, DebugFilter는 마지막 진단용으로만 사용.
• 로그 파싱 툴 : ELK Stack이나 CloudWatch Insights로 FilterSecurityInterceptor 키워드를 필터링하면 권한 문제를 빠르게 찾을 수 있습니다.