🛡️
Spring Security 치트시트

Spring Boot 3.2+ 및 Spring Security 6.x 최신 완전 가이드: Lambda DSL 기반 SecurityFilterChain, JWT 무상태(Stateless) 인증 필터 전체 구현, UserDetailsService & DB 연동, Method Security(@PreAuthorize), CORS/CSRF 정밀 제어, 401/403 커스텀 JSON 응답 및 5.x ➔ 6.x 마이그레이션 체크리스트
#spring-security#spring-boot#spring#java#jwt#authentication#authorization#oauth2#backend#security최종 업데이트: 2026-10-10
Spring Security 치트시트 핵심 명령어 및 실전 가이드

## 1. 사전 요건 & 프로젝트 빌드 구성 (Prerequisites & Setup)

### 💻 시스템 설치 및 실행 요구사양 (System Requirements)

| 항목 | 최소 사양 (Minimum) | 권장 사양 (Recommended) | 참고 및 비고 |
| :--- | :--- | :--- | :--- |
| **운영체제 (OS)** | Windows 10/11, macOS (Apple Silicon / Intel), Linux (Ubuntu, Debian, RHEL) | Ubuntu 22.04 LTS+, macOS Sonoma, Windows 11 (WSL2) | Java 가상 머신(JVM) 지원 64-bit OS |
| **CPU** | 2 코어 이상 | 4 코어 ~ 8 코어 이상 | BCrypt 해싱 연산 및 동시 인증 암호화 처리 성능 |
| **메모리 (RAM)** | 2 GB 이상 (개발/테스트) | 4 GB ~ 8 GB 이상 | Spring Boot 런타임 및 JVM 힙(Heap) 메모리 |
| **디스크 (Storage)** | 1 GB 이상의 여유 공간 | 10 GB 이상의 고속 NVMe SSD | 빌드 아티팩트, 의존성 JAR 캐시 및 DB 스토리지 |
| **네트워크 / 런타임** | Java 17 LTS, Spring Boot 3.2+ / Spring Security 6.2+ | Java 21 LTS / Java 25, Spring Boot 3.3+ | 포트 8080 (기본 HTTP), 포트 443 (HTTPS 필수) |

---

### 📦 빌드 도구별 의존성 설정 (Dependencies)

최신 Spring Boot 3.x 환경에서는 `spring-boot-starter-security`와 함께 REST API 토큰 인증을 위한 JJWT 최신 라이브러리(0.12.x)를 함께 추가합니다.

#### ① Gradle (`build.gradle`)
```groovy
dependencies {
    // Spring Boot 핵심 웹 & 보안 스타터
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'org.springframework.boot:spring-boot-starter-validation'

    // JJWT 0.12.x 최신 라이브러리 (JWT 토큰 생성 및 파싱)
    implementation 'io.jsonwebtoken:jjwt-api:0.12.6'
    runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.12.6'
    runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.12.6'

    // 테스트 환경
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.springframework.security:spring-security-test'
}
```

#### ② Maven (`pom.xml`)
```xml
<dependencies>
    <!-- Spring Boot Web & Security -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>

    <!-- JJWT 0.12.x -->
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-api</artifactId>
        <version>0.12.6</version>
    </dependency>
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-impl</artifactId>
        <version>0.12.6</version>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-jackson</artifactId>
        <version>0.12.6</version>
        <scope>runtime</scope>
    </dependency>
</dependencies>
```

---

## 2. Spring Security 핵심 멘탈 모델 & 아키텍처 (Architecture)

Spring Security는 서블릿 컨테이너(Tomcat)의 **서블릿 필터 체인(Servlet Filter Chain)** 앞단에 위치하여, 모든 HTTP 요청이 컨트롤러에 도달하기 전에 **인증(Authentication: 누구인가?)**과 **인가(Authorization: 접근 권한이 있는가?)**를 일괄 검증합니다.

### 📐 필터 체인 및 인증 처리 흐름 (ASCII Diagram)

```text
[ Client HTTP Request ] (클라이언트 요청)
          │
          ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           Servlet Container (Tomcat)                        │
│                                                                             │
│  [ DelegatingFilterProxy ] (서블릿 필터와 스프링 빈을 연결하는 중계자)       │
│             │                                                               │
│             ▼                                                               │
│  [ FilterChainProxy ] (스프링 시큐리티 필터 목록을 총괄 관리)                │
│             │                                                               │
│             ▼                                                               │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │ SecurityFilterChain (순차적으로 실행되는 보안 필터 체인 목록)         │  │
│  │                                                                       │  │
│  │ 1. CorsFilter               : Cross-Origin 리소스 공유 허용 여부 판별  │  │
│  │ 2. CsrfFilter               : CSRF 토큰 일치 여부 확인 (REST API 제외)│  │
│  │ 3. JwtAuthenticationFilter  : Bearer 토큰 추출 및 SecurityContext 저장 │  │
│  │ 4. UsernamePasswordAuth...  : 폼 로그인(아이디/비밀번호) 검증 필터     │  │
│  │ 5. ExceptionTranslation...  : 인증 예외(401) 및 인가 예외(403) 번역   │  │
│  │ 6. AuthorizationFilter      : 최종 URL 경로별 Role / Authority 검사   │  │
│  └──────────────────────────────────┬────────────────────────────────────┘  │
│                                     │ 인증 성공                               │
│                                     ▼                                       │
│                           [ DispatcherServlet ]                             │
│                                     │                                       │
│                                     ▼                                       │
│                           [ @RestController ]                               │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 🧩 인증(Authentication) 핵심 객체 구조

```text
[ SecurityContextHolder ] ──► [ SecurityContext ] ──► [ Authentication ]
                                                            ├── Principal    (사용자 식별 객체 / UserDetails)
                                                            ├── Credentials  (자격 증명 / 비밀번호 - 인증 후 삭제)
                                                            └── Authorities  (권한 목록 / Collection<GrantedAuthority>)

[ AuthenticationManager ] ──► [ ProviderManager ] ──► [ DaoAuthenticationProvider ]
                                                            ├── UserDetailsService (DB에서 유저 조회)
                                                            └── PasswordEncoder    (비밀번호 해시 일치 검증)
```

---

## 3. [초보자 1단계] 3분 헬로월드: 최소 동작 예제 (Hello World)

Spring Security 6.x의 최신 **Lambda DSL** 방식을 적용하여, 인메모리 유저 2명(일반 유저, 관리자)을 등록하고 URL 접근 권한을 제어하는 최소 동작 예제입니다.

### ① 보안 설정 클래스 (`SecurityConfig.java`)

```java
package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.provisioning.InMemoryUserDetailsManager;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    // [1] SecurityFilterChain 빈 등록 (최신 Lambda DSL 표준)
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            // URL 경로별 인가(Authorization) 규칙 설정
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()           // 누구나 접근 가능
                .requestMatchers("/api/user/**").hasRole("USER")         // USER 권한 필요
                .requestMatchers("/api/admin/**").hasRole("ADMIN")       // ADMIN 권한 필요
                .anyRequest().authenticated()                            // 그 외 모든 요청은 로그인 필수
            )
            // 브라우저 폼 로그인 및 기본 HTTP Basic 인증 활성화
            .formLogin(Customizer.withDefaults())
            .httpBasic(Customizer.withDefaults());

        return http.build();
    }

    // [2] 비밀번호 암호화 빈 (BCrypt 단방향 해시)
    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }

    // [3] 인메모리 테스트 유저 생성 (실무에서는 DB 연동으로 대체)
    @Bean
    public UserDetailsService userDetailsService(PasswordEncoder passwordEncoder) {
        UserDetails user = User.builder()
            .username("user1")
            .password(passwordEncoder.encode("user1234"))
            .roles("USER") // 자동으로 "ROLE_USER" 권한 부여
            .build();

        UserDetails admin = User.builder()
            .username("admin1")
            .password(passwordEncoder.encode("admin1234"))
            .roles("ADMIN", "USER")
            .build();

        return new InMemoryUserDetailsManager(user, admin);
    }
}
```

### ② 테스트 컨트롤러 (`HelloController.java`)

```java
package com.example.demo.controller;

import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class HelloController {

    @GetMapping("/public/info")
    public String publicEndpoint() {
        return "누구나 열람 가능한 공개 정보입니다.";
    }

    @GetMapping("/user/profile")
    public String userEndpoint(@AuthenticationPrincipal UserDetails userDetails) {
        return "로그인한 유저 환영합니다: " + userDetails.getUsername();
    }

    @GetMapping("/admin/dashboard")
    public String adminEndpoint() {
        return "최고 관리자 전용 대시보드 데이터입니다.";
    }
}
```

### ③ curl 테스트 및 검증 결과

```bash
# 1. 공개 경로 요청 (인증 없이 200 OK 성공)
curl -i http://localhost:8080/api/public/info
# HTTP/1.1 200 OK
# 누구나 열람 가능한 공개 정보입니다.

# 2. 유저 경로에 비인가 접근 시도 (401 Unauthorized 반환)
curl -i http://localhost:8080/api/user/profile
# HTTP/1.1 401 Unauthorized

# 3. HTTP Basic 인증으로 일반 유저 로그인 후 접근 (성공)
curl -i -u user1:user1234 http://localhost:8080/api/user/profile
# HTTP/1.1 200 OK
# 로그인한 유저 환영합니다: user1

# 4. 일반 유저가 관리자 경로(/api/admin/**) 접근 시도 (403 Forbidden 거부)
curl -i -u user1:user1234 http://localhost:8080/api/admin/dashboard
# HTTP/1.1 403 Forbidden
```

---

## 4. [2단계] 핵심 기능: REST API 무상태(Stateless) JWT 완전 구현

세션을 서버 메모리에 저장하지 않고, JWT(JSON Web Token)를 HTTP 요청 헤더(`Authorization: Bearer <token>`)로 전달받아 검증하는 현대적인 모던 백엔드 표준 아키텍처입니다.

### ① JJWT 0.12.x 기반 토큰 공급자 (`JwtTokenProvider.java`)

```java
package com.example.demo.security;

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.User;
import org.springframework.stereotype.Component;

import javax.crypto.SecretKey;
import java.nio.charset.StandardCharsets;
import java.util.Arrays;
import java.util.Collection;
import java.util.Date;
import java.util.stream.Collectors;

@Component
public class JwtTokenProvider {

    // 실무에서는 application.yml에서 주입받으며, 반드시 256비트(32자) 이상이어야 합니다.
    private static final String SECRET = "LuckyTechWorldSuperSecretJwtSigningKeyForSpringBootSecurity2026!";
    private static final long ACCESS_TOKEN_VALIDITY = 1000L * 60 * 60; // 1시간 (밀리초)

    private final SecretKey secretKey = Keys.hmacShaKeyFor(SECRET.getBytes(StandardCharsets.UTF_8));

    // [1] 토큰 발급 (사용자 이름과 권한 문자열 포함)
    public String createAccessToken(String username, String roles) {
        Date now = new Date();
        Date validity = new Date(now.getTime() + ACCESS_TOKEN_VALIDITY);

        return Jwts.builder()
            .subject(username)
            .claim("roles", roles) // 예: "ROLE_USER,ROLE_ADMIN"
            .issuedAt(now)
            .expiration(validity)
            .signWith(secretKey)
            .compact();
    }

    // [2] 토큰에서 Authentication 객체 역추출
    public Authentication getAuthentication(String token) {
        Claims claims = getClaims(token);
        String rolesStr = claims.get("roles", String.class);

        Collection<? extends GrantedAuthority> authorities = (rolesStr == null || rolesStr.isBlank())
            ? java.util.Collections.emptyList()
            : Arrays.stream(rolesStr.split(","))
                    .map(SimpleGrantedAuthority::new)
                    .collect(Collectors.toList());

        User principal = new User(claims.getSubject(), "", authorities);
        return new UsernamePasswordAuthenticationToken(principal, token, authorities);
    }

    // [3] 토큰 유효성 검증
    public boolean validateToken(String token) {
        try {
            getClaims(token);
            return true;
        } catch (Exception e) {
            return false;
        }
    }

    // [4] 클레임 파싱
    private Claims getClaims(String token) {
        return Jwts.parser()
            .verifyWith(secretKey)
            .build()
            .parseSignedClaims(token)
            .getPayload();
    }
}
```

---

### ② JWT 전용 요청 가로채기 필터 (`JwtAuthenticationFilter.java`)

모든 요청마다 1회 실행되는 `OncePerRequestFilter`를 상속받아 HTTP `Authorization` 헤더에서 토큰을 추출하고 SecurityContext에 등록합니다.

```java
package com.example.demo.security;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.util.StringUtils;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;

public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final JwtTokenProvider tokenProvider;

    public JwtAuthenticationFilter(JwtTokenProvider tokenProvider) {
        this.tokenProvider = tokenProvider;
    }

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain) throws ServletException, IOException {
        String token = resolveToken(request);

        // 유효한 JWT 토큰이 존재하면 SecurityContext에 인증 정보 저장
        if (StringUtils.hasText(token) && tokenProvider.validateToken(token)) {
            Authentication auth = tokenProvider.getAuthentication(token);
            SecurityContextHolder.getContext().setAuthentication(auth);
        }

        // 다음 필터로 요청 인계
        filterChain.doFilter(request, response);
    }

    private String resolveToken(HttpServletRequest request) {
        String bearerToken = request.getHeader("Authorization");
        if (StringUtils.hasText(bearerToken) && bearerToken.startsWith("Bearer ")) {
            return bearerToken.substring(7);
        }
        return null;
    }
}
```

---

### ③ 무상태 REST API용 보안 설정 (`JwtSecurityConfig.java`)

```java
package com.example.demo.config;

import com.example.demo.security.JwtAuthenticationFilter;
import com.example.demo.security.JwtTokenProvider;
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.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;

@Configuration
@EnableWebSecurity
@EnableMethodSecurity // @PreAuthorize, @PostAuthorize 메서드 보안 활성화
public class JwtSecurityConfig {

    private final JwtTokenProvider jwtTokenProvider;

    public JwtSecurityConfig(JwtTokenProvider jwtTokenProvider) {
        this.jwtTokenProvider = jwtTokenProvider;
    }

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // [1] REST API이므로 CSRF 보호 비활성화 (세션을 사용하지 않음)
            .csrf(AbstractHttpConfigurer::disable)
            // [2] 폼 로그인 및 기본 HTTP Basic 비활성화
            .formLogin(AbstractHttpConfigurer::disable)
            .httpBasic(AbstractHttpConfigurer::disable)
            // [3] 세션 생성 정책을 무상태(STATELESS)로 강제 지정
            .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            // [4] 엔드포인트별 인가 설정
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**").permitAll() // 로그인, 회원가입 API
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
                .anyRequest().authenticated()
            )
            // [5] 커스텀 JWT 필터를 UsernamePasswordAuthenticationFilter 앞단에 배치
            .addFilterBefore(new JwtAuthenticationFilter(jwtTokenProvider),
                             UsernamePasswordAuthenticationFilter.class);

        return http.build();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}
```

---

## 5. [2단계] 메서드 레벨 보안 (Method Security)

컨트롤러의 개별 엔드포인트 메서드 또는 서비스 계층(Service Layer)의 비즈니스 로직 단위로 세밀하게 권한을 검사합니다.

```java
package com.example.demo.controller;

import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    // [1] ROLE_ADMIN 역할을 가진 유저만 주문 전체 목록 조회 가능
    @GetMapping
    @PreAuthorize("hasRole('ADMIN')")
    public String getAllOrders() {
        return "전체 주문 목록 (관리자 전용)";
    }

    // [2] USER 또는 ADMIN 역할을 가진 유저만 주문 상세 조회 가능
    @GetMapping("/{orderId}")
    @PreAuthorize("hasAnyRole('USER', 'ADMIN')")
    public String getOrderDetail(@PathVariable Long orderId) {
        return orderId + "번 주문 상세 내역";
    }

    // [3] SpEL 표현식을 활용하여 현재 로그인한 유저 본인의 주문만 취소 가능
    @DeleteMapping("/{orderId}")
    @PreAuthorize("hasRole('ADMIN') or #username == authentication.name")
    public String cancelOrder(@PathVariable Long orderId, @RequestParam String username) {
        return orderId + "번 주문 취소 성공 (소유자: " + username + ")";
    }

    // [4] 현재 로그인한 주체(Principal) 정보 파라미터 직접 주입
    @GetMapping("/my")
    public String getMyInfo(@AuthenticationPrincipal UserDetails user) {
        return "현재 로그인 사용자: " + user.getUsername();
    }
}
```

---

## 6. [3단계] 실무 응용: DB/JPA 연동 & 커스텀 예외 응답 (JPA & Exception)

### ① JPA 커스텀 UserDetailsService 연동

실제 데이터베이스에서 사용자 정보를 조회하여 Spring Security 표준 `UserDetails` 객체로 변환합니다.

```java
package com.example.demo.security;

import com.example.demo.entity.Member;
import com.example.demo.repository.MemberRepository;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.util.Collections;

@Service
public class CustomUserDetailsService implements UserDetailsService {

    private final MemberRepository memberRepository;

    public CustomUserDetailsService(MemberRepository memberRepository) {
        this.memberRepository = memberRepository;
    }

    @Override
    @Transactional(readOnly = true)
    public UserDetails loadUserByUsername(String email) throws UsernameNotFoundException {
        Member member = memberRepository.findByEmail(email)
            .orElseThrow(() -> new UsernameNotFoundException("해당 이메일의 회원을 찾을 수 없습니다: " + email));

        // DB의 Role(예: "USER")을 "ROLE_USER" 권한으로 매핑
        return new User(
            member.getEmail(),
            member.getPassword(), // BCrypt 해시된 비밀번호
            Collections.singletonList(new SimpleGrantedAuthority("ROLE_" + member.getRole().name()))
        );
    }
}
```

---

### ② REST API 전용 커스텀 401 / 403 JSON 에러 핸들러

인증 실패 시 기본 HTML 로그인 폼으로 리다이렉트되지 않고, 프론트엔드가 파싱하기 쉬운 표준 JSON 에러 포맷으로 응답합니다.

#### 1) 인증 실패 (401 Unauthorized) 핸들러
```java
package com.example.demo.security;

import com.fasterxml.jackson.databind.ObjectMapper;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.http.MediaType;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.stereotype.Component;

import java.io.IOException;
import java.util.Map;

@Component
public class JwtAuthenticationEntryPoint implements AuthenticationEntryPoint {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public void commence(HttpServletRequest request,
                         HttpServletResponse response,
                         AuthenticationException authException) throws IOException {
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        response.setCharacterEncoding("UTF-8");
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);

        Map<String, Object> body = Map.of(
            "status", 401,
            "error", "Unauthorized",
            "message", "인증 토큰이 유효하지 않거나 누락되었습니다.",
            "path", request.getRequestURI()
        );

        response.getWriter().write(objectMapper.writeValueAsString(body));
    }
}
```

#### 2) 권한 부족 (403 Forbidden) 핸들러
```java
package com.example.demo.security;

import com.fasterxml.jackson.databind.ObjectMapper;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.http.MediaType;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.security.web.access.AccessDeniedHandler;
import org.springframework.stereotype.Component;

import java.io.IOException;
import java.util.Map;

@Component
public class JwtAccessDeniedHandler implements AccessDeniedHandler {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public void handle(HttpServletRequest request,
                       HttpServletResponse response,
                       AccessDeniedException accessDeniedException) throws IOException {
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        response.setCharacterEncoding("UTF-8");
        response.setStatus(HttpServletResponse.SC_FORBIDDEN);

        Map<String, Object> body = Map.of(
            "status", 403,
            "error", "Forbidden",
            "message", "해당 리소스에 접근할 권한이 부족합니다.",
            "path", request.getRequestURI()
        );

        response.getWriter().write(objectMapper.writeValueAsString(body));
    }
}
```

#### 3) SecurityConfig에 예외 핸들러 등록
```java
http.exceptionHandling(ex -> ex
    .authenticationEntryPoint(jwtAuthenticationEntryPoint) // 401 에러
    .accessDeniedHandler(jwtAccessDeniedHandler)           // 403 에러
);
```

---

## 7. [3단계] 실무 응용: CORS 정밀 제어 (Cross-Origin Policy)

SPA(React, Vue, Next.js 등) 프론트엔드와 분리된 환경에서 발생하는 브라우저 CORS(Cross-Origin Resource Sharing) 차단을 해결하기 위해 `CorsConfigurationSource`를 SecurityFilterChain 최상단에 바인딩합니다.

```java
package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.CorsConfigurationSource;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;

import java.util.Arrays;
import java.util.List;

@Configuration
public class CorsConfig {

    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration config = new CorsConfiguration();

        // 1. 허용할 프론트엔드 Origin 출처 명시 (운영 환경에서는 와일드카드 * 지양)
        config.setAllowedOrigins(List.of("http://localhost:3000", "https://techworld.sulucky5.pe.kr"));
        
        // 2. 허용할 HTTP 메서드
        config.setAllowedMethods(Arrays.asList("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"));
        
        // 3. 허용할 헤더 목록
        config.setAllowedHeaders(Arrays.asList("Authorization", "Content-Type", "X-Requested-With"));
        
        // 4. 브라우저가 응답 헤더 중 읽을 수 있도록 노출할 헤더
        config.setExposedHeaders(List.of("Authorization"));
        
        // 5. 쿠키 및 Authorization 헤더 포함 요청 허용
        config.setAllowCredentials(true);
        
        // 6. 브라우저 Preflight(OPTIONS) 요청 캐시 시간 (1시간)
        config.setMaxAge(3600L);

        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", config);
        return source;
    }
}
```
> **적용 디렉티브**: `SecurityConfig` 내부에서 `.cors(cors -> cors.configurationSource(corsConfigurationSource()))`로 주입합니다.

---

## 8. 실무 주의사항 & 5.x ➔ 6.x 마이그레이션 가이드 (Migration & Best Practices)

### ⚠️ Spring Security 5.x ➔ 6.x 핵심 변경 사항 비교

| 기능 항목 | 구버전 방식 (Spring Security 5.x) | 최신 방식 (Spring Security 6.x / Boot 3.x) |
| :--- | :--- | :--- |
| **설정 상속 구조** | `extends WebSecurityConfigurerAdapter` | 상속 제거, **`@Bean SecurityFilterChain` 직접 등록** |
| **체이닝 문법** | `.and().csrf().disable().and().cors()` | **순수 Lambda DSL 강제** (`csrf(AbstractHttpConfigurer::disable)`) |
| **URL 인가 디렉티브** | `.authorizeRequests()` | **`.authorizeHttpRequests()`** 로 명칭 변경 |
| **경로 매처 메서드** | `antMatchers("/api/**")`, `mvcMatchers()` | **`requestMatchers("/api/**")`** 로 단일 통합 |
| **메서드 보안 어노테이션** | `@EnableGlobalMethodSecurity(prePostEnabled=true)` | **`@EnableMethodSecurity`** 로 간소화 |

---

### 🛡️ 초보자가 자주 겪는 4대 함정 및 트러블슈팅

#### 1. `hasRole()` vs `hasAuthority()`의 `ROLE_` 접두사 혼동
- **원인**: `hasRole("ADMIN")`은 내부적으로 접두사 `ROLE_`을 자동으로 덧붙여 `"ROLE_ADMIN"`을 검사합니다.
- **해결책**:
  ```java
  // UserDetailsService 또는 JWT 클레임에 "ROLE_ADMIN"으로 저장되어 있을 때:
  .hasRole("ADMIN")             // ✅ 올바름 (자동으로 "ROLE_ADMIN" 매칭)
  .hasRole("ROLE_ADMIN")        // ❌ 실패 ("ROLE_ROLE_ADMIN"을 찾으므로 403 에러 발생)
  .hasAuthority("ROLE_ADMIN")   // ✅ 올바름 (완전 일치 검사)
  ```

#### 2. CORS 사전 요청(OPTIONS Preflight)에 401/403 에러 발생
- **원인**: 브라우저가 실제 요청 전 보내는 `OPTIONS` 메서드 요청에 인증 헤더가 없어 시큐리티 필터에서 차단됨.
- **해결책**:
  ```java
  .authorizeHttpRequests(auth -> auth
      .requestMatchers(org.springframework.http.HttpMethod.OPTIONS, "/**").permitAll() // Preflight 전면 허용
      .anyRequest().authenticated()
  )
  ```

#### 3. `@Async` 비동기 스레드에서 SecurityContext 유실
- **원인**: `SecurityContextHolder`의 기본 전략은 `ThreadLocal`이므로, 별도의 비동기 워커 스레드로 넘어가면 사용자 인증 정보가 전파되지 않고 `null`이 됩니다.
- **해결책**: `SecurityContextHolder.setStrategyName(SecurityContextHolder.MODE_INHERITABLETHREADLOCAL);` 설정 또는 `DelegatingSecurityContextAsyncTaskExecutor` 사용.

#### 4. 비밀번호 암호화 원문 노출 및 비밀번호 일치 검사 오류
- **주의사항**: `BCryptPasswordEncoder`는 단방향 솔팅(Salting) 해시이므로 `encoder.matches(rawPassword, encodedPassword)` 메서드를 통해서만 일치 여부를 검증해야 합니다. 문자열의 `equals()` 비교는 절대 불가능합니다.
💬
Spring Security 치트시트

의견 및 질문

댓글 수정

댓글 삭제
