[TIL-20260127] @AuthenticationPrincipal , Swagger JWT 인증 설정

🍀 To Do List

 

 

 

👩🏻‍💻 Today I Learned ...

 

@AuthenticationPrincipal 사용해서 유저 정보 가져오기

 

@AuthenticationPrincipal은 Spring Security의 Authentication 객체(로그인한 사용자의 이름, 권한, 역할 등이 담겨있음) 에서 현재 인증된 사용자의 정보를 직접 가져올 수 있게 해주는 어노테이션이다.

 

 

JWT Filter에서 Authentication 객체를 생성해서 Security Context에 저장하면

아래와 같은 구조로 principal 저장된다.

 

SecurityContextHolder
    └─ SecurityContext
        └─ Authentication (UsernamePasswordAuthenticationToken)
            ├─ principal: AuthUser(id=123, email="user@...", ...)

 

 

 

Controller 실행 시, Spring이 내부적으로 SecurityContextHolder에서 principal 값을 가져와서 Principal 클래스로 캐스팅해준다.

user 객체에는 user id, email 등의 정보가 담겨있기 때문에 , controller와 service 단에서 보안상 안전하게 유저 정보를 사용할 수 있다.

 

 

@AuthenticationPrincipal 어노테이션 이용해서 Controller에서 유저 정보를 안전하게 가져오는 방향으로 리팩토링을 진행했는데

자세한 내용은 개발 일지에 따로 작성할 예정이다. ✏️

 

 

참고 :

Spring Security의 @AuthenticationPrincipal 이해하기

 

 

 

Swagger 설정

 

build.gradle.kt

implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.13")

 

Spring Boot 3.x 환경에서 사용하는 springdoc 최신 버전으로, /swagger-ui.html 또는 /swagger-ui/index.html 로 접근 가능하다.

 

Swagger에 JWT 인증 설정

 

 

info()

Swagger UI 상단에 표시되는 API 문서 정보를 설정한다.

.info(
    Info()
        .title("KOU App API")                    // ← API 제목
        .version("v1.0.0")                       // ← 버전
        .description("...")                      // ← 설명
)

 

components()

API 전역에서 사용할 보안 스키마, 공통 모델 등을 정의한다.

.components(
		Components()
			.addSecuritySchemes( // ← 보안 스키마
				"bearerAuth", // ← 스키마 이름 (Controller에서 참조)
				SecurityScheme()
					.type(SecurityScheme.Type.HTTP)  // ← HTTP 인증 스키마// ← 인증 타입
					.scheme("bearer")
					.bearerFormat("JWT") // ← Bearer 포맷
					.`in`(SecurityScheme.In.HEADER) // ← 위치 (헤더)
					.name("Authorization") // ← 헤더 이름
					.description("JWT 토큰을 입력하세요 (Bearer 제외)"),  // ← 설명
	),
)

 

 

 

 

Swagger UI에서  Authorize 🔓 버튼을 클릭하여 AccessToken 값을 입력하면 ,

 Postman에서 Authorization 탭에 AccessToken 값을 입력하여 API 요청하는 것과 동일하게 동작하는 걸 볼 수 있다.

 

 

참고 : 

Spring Boot(Kotlin) — 4편. Swagger(OpenAPI) 설정 가이드