JWT(JSON Web Token)는 인증과 인가를 구현할 때 가장 많이 사용되는 방식 중 하나다. 하지만 JWT 자체보다 더 중요한 것은 토큰을 생성할 때 필요한 설정 정보를 어떻게 관리하느냐다.
발급자(issuer), 비밀키(secret), 만료 시간(expired) 같은 값들은 코드에 하드코딩되면 안 되고, 환경별로 분리되어야 하며, 무엇보다 외부에 노출되지 않아야 한다.
이 글에서는 JWT 생성에 필요한 정보들을 yml 설정 파일과 ConfigurationProperties 클래스를 통해 안전하고 명확하게 관리하는 방법을 정리한다.
JWT 설정 ConfigurationProperties 설계
JWT 토큰을 생성할 때 필요한 값은 많지 않다. 대표적으로 발급자, 비밀키, 만료 시간 정도면 충분하다. 이 값들을 하나의 설정 클래스로 묶어두면 JWT 관련 로직의 응집도를 크게 높일 수 있다.
Spring에서는 @ConfigurationProperties를 통해 외부 설정 파일의 값을 타입 안정성 있게 바인딩할 수 있다. 이 방식은 @Value를 여러 개 쓰는 것보다 가독성과 유지보수성이 훨씬 좋다.
JWT 설정 클래스는 단순한 getter 역할만 하도록 만들되, 비밀키는 그대로 노출하지 않는 것이 중요하다. 문자열 형태의 secretKey를 Key 객체로 변환하는 책임을 설정 클래스 내부에 두는 이유도 여기에 있다.
record를 사용할 수도 있지만, record는 자동으로 모든 필드를 노출하는 accessor를 제공한다. 보안 정보가 포함된 설정에서는 의도적으로 getter를 제어할 수 있는 일반 클래스가 더 안전한 선택이 된다.
JWT 설정 yml 분리와 보안 관리
JWT 설정 정보를 application.yml에 직접 작성할 수도 있다. 하지만 비밀키는 절대 공개되면 안 되는 정보다. 그래서 별도의 yml 파일로 분리해 관리하는 것이 일반적이다.
application-jwt.yml처럼 역할이 드러나는 파일명으로 분리하면 보안 목적과 설정 책임이 명확해진다. 환경별로 다른 비밀키를 사용해야 할 경우에도 설정 파일만 교체하면 되므로 운영이 편해진다.
Spring Boot 2.4 이후에는 spring.config.import를 통해 외부 yml 파일을 명시적으로 불러올 수 있다. 이 방식은 설정의 출처를 코드에서 확인할 수 있어 의존 관계를 파악하기 쉽다.
비밀키는 사람이 직접 작성하지 않고 openssl 같은 도구로 충분히 긴 난수를 생성하는 것이 좋다. 짧은 문자열이나 의미 있는 단어는 보안 사고의 원인이 된다.
JWT 설정 바인딩과 테스트 검증
설정 클래스를 만들고 yml을 분리했다면 Spring 애플리케이션이 실제로 해당 값을 잘 읽어오는지 확인해야 한다.
@EnableConfigurationProperties를 통해 설정 클래스를 명시적으로 등록하면 Spring 컨텍스트 초기화 시점에 yml 값이 객체로 바인딩된다.
이 과정을 테스트 코드로 검증해두면 설정 누락이나 오타를 조기에 발견할 수 있다. 특히 배포 환경에서 JWT 설정이 잘못되면 모든 인증 로직이 실패할 수 있기 때문에 사전 검증은 매우 중요하다.
설정 테스트는 비즈니스 로직 테스트와 달리 단순하지만 효과가 크다. JWT 설정 객체가 null 없이 정상 로드되는지만 확인해도 운영 리스크를 크게 줄일 수 있다.
JWT 설정은 단순한 설정 작업이 아니다. 인증 시스템의 신뢰성과 보안을 좌우하는 핵심 요소다. 설정 정보를 코드와 분리하고, 의도를 드러내는 클래스로 관리하는 습관은 규모가 커질수록 큰 차이를 만든다.
JWT를 구현할 때 토큰 로직보다 먼저 설정 구조부터 고민해야 하는 이유가 여기에 있다.