📌 Spring Security - "UserDetails" & "PrincipalDetails" 완전 정복

📅 날짜

2025-04-30

---

📝 학습 내용

1️⃣ Spring Security 인증 구조 개요

Spring Security에서 사용자가 로그인하면 다음과 같은 인증 절차가 진행됩니다:

1. UsernamePasswordAuthenticationFilter가 로그인 요청을 가로챔
2. loadUserByUsername() 호출
3. 반환된 UserDetails 객체를 내부에서 검증 및 Authentication 생성
4. 인증된 정보는 SecurityContextHolder에 저장됨

이를 위해 우리가 직접 구현해야 할 두 가지 핵심 클래스가 있습니다:

• ✅ PrincipalDetails: UserDetails 인터페이스 구현체
• ✅ PrincipalDetailsService: UserDetailsService 구현체

---

2️⃣ PrincipalDetails 클래스 구현 (UserDetails 구현체)

✅ 역할

• Spring Security가 사용자 정보를 관리할 수 있도록 UserDto를 감싼 래퍼 클래스
• 로그인 성공 후 SecurityContext에 저장됨
• 권한 및 계정 상태 등을 반환하는 메서드 제공

✅ 전체 코드 + 설명

@Data
@NoArgsConstructor
@AllArgsConstructor
public class PrincipalDetails implements UserDetails {

    private UserDto userDto;  // 우리가 만든 UserDto 객체

    // 사용자의 권한 목록 반환
    @Override
    public Collection<? extends GrantedAuthority> getAuthorities() {
        Collection<GrantedAuthority> authorities = new ArrayList<>();
        // SimpleGrantedAuthority: 권한 문자열을 객체 형태로 래핑
        authorities.add(new SimpleGrantedAuthority(userDto.getRole())); // ex) ROLE_USER
        return authorities;
    }

    @Override
    public String getPassword() {
        return userDto.getPassword();  // 사용자 비밀번호
    }

    @Override
    public String getUsername() {
        return userDto.getUsername();  // 사용자 ID (unique)
    }

    @Override
    public boolean isAccountNonExpired() {
        return true;  // 계정 만료 안 됨
    }

    @Override
    public boolean isAccountNonLocked() {
        return true;  // 계정 잠김 없음
    }

    @Override
    public boolean isCredentialsNonExpired() {
        return true;  // 비밀번호 만료 안 됨
    }

    @Override
    public boolean isEnabled() {
        return true;  // 계정 활성화
    }
}

---

3️⃣ PrincipalDetailsService 클래스 구현 (UserDetailsService)

✅ 역할

• 로그인 시 사용자가 입력한 ID(username)로 DB에서 사용자 정보를 조회
• 조회 결과를 PrincipalDetails로 감싸 반환
• 조회 실패 시 UsernameNotFoundException 발생

✅ 전체 코드 + 설명

@Service
@Slf4j
public class PrincipalDetailsService implements UserDetailsService {

    @Autowired
    private UserMapper userMapper;

    @Override
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        // 로그인 시 사용자가 입력한 username 값을 기반으로 DB 조회
        UserDto userDto = userMapper.selectAt(username);

        // 조회 실패 시 예외 발생
        if (userDto == null) {
            throw new UsernameNotFoundException(username + " 존재하지 않는 계정입니다.");
        }

        // 조회된 사용자 정보를 PrincipalDetails 객체에 담아 반환
        return new PrincipalDetails(userDto);
    }
}

---

4️⃣ UserMapper 인터페이스 (MyBatis 기반)

✅ 역할

• 사용자 정보 저장 및 조회
• @Select, @Insert 어노테이션으로 SQL 직접 명시

@Mapper
public interface UserMapper {

    @Insert("INSERT INTO tbl_user (username, password, role) VALUES (#{username}, #{password}, #{role})")
    int insert(UserDto userDto);

    @Select("SELECT * FROM tbl_user WHERE username = #{username}")
    UserDto selectAt(String username);
}

✅ @Select 쿼리에서 괄호 오류 주의: username=#{username}) → username=#{username}

---

🔥 정리

구성 요소	설명
PrincipalDetails	UserDetails 구현체. UserDto를 감싸 인증된 사용자 정보로 변환
PrincipalDetailsService	UserDetailsService 구현체. 로그인 시 사용자 정보를 DB에서 조회
UserMapper	사용자 정보를 DB에서 조회/저장하는 MyBatis 인터페이스
SecurityContextHolder	인증된 사용자가 저장되는 전역 보안 컨텍스트

---

🔗 참고 자료

• Spring Security 공식 문서
• Spring UserDetails 인터페이스

---

느낀 점

이번 학습을 통해 UserDetails와 UserDetailsService가 어떻게 동작하는지 명확히 이해할 수 있었다.

특히, Spring Security 내부에서 인증 객체를 어떻게 저장하고 꺼내는지, 우리가 커스터마이징한 UserDto를 어떤 방식으로 래핑해야 하는지를 직접 구현하면서 체감할 수 있었다.

실무에서는 권한에 따라 화면을 나누거나 기능을 제한하는 데에 이 구조가 핵심 역할을 하게 될 것이다.

---

요약

• 로그인 요청 시 PrincipalDetailsService의 loadUserByUsername()이 호출됨
• 사용자 정보가 DB에서 조회되어 PrincipalDetails에 담겨 반환됨
• PrincipalDetails는 UserDetails 인터페이스 구현체로, Spring Security 내부에서 인증 객체로 사용됨
• 권한은 SimpleGrantedAuthority로 감싸야 하며, 문자열만 반환하면 안 됨

---