@AuthenticationPrincipal

@AuthenticationPrincipal

• Spring Security에서 로그인한 사용자의 정보를 컨트롤러 메서드 파라미터로 간편하게 주입해주는 어노테이션
• Spring Security의 SecurityContextHolder에 저장된 인증 객체(Authentication)로부터 Principal 정보를 꺼내서, 컨트롤러 파라미터에 주입함
• 내부적으로는 SecurityContextHolder.getContext().getAuthentication().getPrincipal()을 호출하는 것과 같음

---

📦 내부 구조

로그인하면 Spring Security가 이 과정을 자동으로 처리한다.

• 사용자가 로그인 → Authentication 객체 생성
• Authentication.getPrincipal()에 로그인한 사용자 정보(UserDetails 구현체)가 들어감
• 이 Principal을 @AuthenticationPrincipal을 통해 꺼내쓸 수 있음

---

💡 예시 

@GetMapping("/me")
public ResponseEntity<?> getMyInfo(@AuthenticationPrincipal SecurityUser securityUser) {
    return ResponseEntity.ok(securityUser);
}

• 여기서 SecurityUser는 커스텀 UserDetails 구현체
• 로그인한 유저의 정보를 바로 securityUser로 받을 수 있음

---

⚠️ 인증되지 않았을 때

• 인증되지 않은 요청에서 @AuthenticationPrincipal을 쓰면 null이 주입됨
• 그래서 보통은 다음처럼 @PreAuthorize나 @AuthenticationPrincipal Optional<User>로 방어힘

@GetMapping("/me")
public ResponseEntity<?> getMyInfo(@AuthenticationPrincipal Optional<SecurityUser> userOpt) {
    if (userOpt.isEmpty()) return ResponseEntity.status(401).build();
    return ResponseEntity.ok(userOpt.get());
}

---

💡 SpEL (Spring Expression Language) 활용

• UserDetails 안에 있는 특정 필드만 받고 싶때 SpEL 사용

@GetMapping("/me-id")
public ResponseEntity<Long> getMyId(
    @AuthenticationPrincipal(expression = "id") Long userId) {
    return ResponseEntity.ok(userId);
}

• SecurityUser.getId()를 호출한 결과를 주입

---

💡 커스터마이징 예: @CurrentUser

@AuthenticationPrincipal을 좀 더 도메인에 맞는 이름으로 바꿔서 쓰는 경우

@Target({ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@AuthenticationPrincipal
public @interface CurrentUser {
}

 

사용 예시

@GetMapping("/profile")
public ResponseEntity<?> profile(@CurrentUser SecurityUser user) {
    ...
}

---

📌 정리

항목	설명
어노테이션	@AuthenticationPrincipal
사용 위치	컨트롤러 메서드 파라미터
반환 값	UserDetails 객체 (ex. SecurityUser)
인증 안 됨	null 주입
커스터마이징	@CurrentUser로 래핑 가능
내부 구현	SecurityContextHolder.getContext().getAuthentication().getPrincipal() 호출과 동일

---

출처

OpenAI의 ChatGPT (https://openai.com)