Spring Boot 인증 실패와 401/403 오류 디버깅

소개

Spring Boot 애플리케이션에서 401 Unauthorized 또는 403 Forbidden 오류는 빈번하게 발생한다. 원인을 모르면 시간만 낭비한다. 이 글은 초보자도 이해할 수 있도록 단계별로 문제를 진단하고 해결하는 방법을 정리한다. 핵심 키워드는 spring boot 인증 실패 디버깅, 403 forbidden spring boot 해결, spring security 401 403 원인이다.

인증과 권한 오류의 차이

간단히 구분하면 401은 인증 실패, 403은 인증은 되었지만 권한 부족을 뜻한다. 인증 정보 자체가 없거나 잘못된 경우 401이 발생한다. 반면 사용자는 인증되었지만 접근 권한이 없을 때 403이 반환된다.

기본 점검 순서

• 로그 확인: 서버 시작 로그와 요청 로그 확인
• 헤더 확인: Authorization 헤더와 토큰 유무 점검
• 보안 설정 점검: WebSecurityConfigurerAdapter 또는 SecurityFilterChain 설정 확인
• CORS/CSRF 확인: 브라우저 환경에서의 제한 여부 점검
• 권한 매핑 확인: @PreAuthorize, hasRole 등 어노테이션 검토

로그에서 확인할 항목

로그는 가장 먼저 보는 도구다. Spring Security는 인증과 권한 검사 결과를 디버그 로그로 남긴다. 로그 레벨을 DEBUG로 올려 아래 항목을 확인한다.

• 토큰 파싱 성공 여부
• 인증 객체(Authentication) 생성 여부
• 권한(GrantedAuthority) 목록
• 필터 순서로 인한 차단 지점

자주 발생하는 원인과 해결법

1) 잘못된 Authorization 헤더

Bearer 토큰을 사용하는 경우 "Authorization: Bearer <token>" 형태인지 확인한다. 토큰이 누락되면 401이 발생한다.

2) Token 검증 실패

서명 검증, 만료 시간, 토큰 형식 등을 점검한다. JWT 사용하는 경우 공개키/비밀키가 맞는지 확인한다.

3) 권한(Role) 매핑 오류

권한 이름 앞에 ROLE_ 접두사가 필요한지 확인한다. 예: hasRole('ADMIN')는 GrantedAuthority에 ROLE_ADMIN이 있어야 허용된다.

4) CSRF 차단

브라우저에서 POST/PUT/DELETE 요청 시 CSRF 토큰이 없으면 403이 발생할 수 있다. API 서버인 경우 CSRF를 비활성화하거나 클라이언트에서 토큰을 전송해야 한다.

5) CORS 설정 문제

브라우저는 CORS로 인해 요청이 차단될 수 있다. 서버 응답에 Access-Control-Allow-Origin 등이 적절히 설정되어 있는지 확인한다.

실전 예제: Security 설정 점검

아래 예제는 가장 많이 쓰이는 Spring Security 설정 구조를 보여준다. 필터 체인과 인증 매니저를 명확히 정의하면 문제를 좁히기 쉽다.

package com.example.security;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableMethodSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf().disable()
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/public/**").permitAll()
                .anyRequest().authenticated()
            )
            .httpBasic();
        return http.build();
    }
}

위 설정에서 CSRF를 일괄 비활성화하면 브라우저 전송 시 403을 예방할 수 있다. 다만 보안 요구사항에 따라 신중히 적용한다.

디버깅 팁

• 브라우저 대신 curl로 요청해 헤더와 응답을 비교한다.
• 중간 필터가 토큰을 제거하는지 확인한다.
• 단위 테스트로 인증 로직을 검증한다.
• 권한 검증 지점에 로그를 추가해 차단 위치를 정확히 파악한다.

curl로 빠르게 확인하기

curl -i -H "Authorization: Bearer <TOKEN>" http://localhost:8080/api/secure

응답 코드와 WWW-Authenticate 헤더를 확인하면 왜 401이 떨어졌는지 단서를 얻는다. 403이면 응답 본문이나 서버 로그에서 권한 검사 실패 정보를 찾는다.

체크리스트

• 로그 레벨을 DEBUG로 설정해 인증 흐름 확인
• Authorization 헤더 형식과 토큰 유효성 검증
• GrantedAuthority와 hasRole/hasAuthority 매핑 일치
• CSRF와 CORS 설정 점검
• 필터 순서 문제 확인

결론

401과 403 문제는 원인별로 접근하면 빠르게 해결할 수 있다. 로그 확인으로 문제 지점을 좁히고, 인증 헤더·토큰·권한 매핑·CSRF/CORS를 순서대로 점검한다. 위 절차를 따르면 spring boot 인증 실패 디버깅과 403 forbidden spring boot 해결, spring security 401 403 원인 파악에 도움이 된다.