[트러블슈팅] JWT secret 키 길이 부족으로 인한 WeakKeyException

TROUBLESHOOTING

JWT secret 키 길이 부족으로 인한 WeakKeyException 해결

목차

• 1. 구현 배경
• 2. 문제 상황
• 3. 원인
• 4. 해결
• 5. 왜 시작 시점에 터지는가
• 6. 배운 점

1. 구현 배경

JWT 기반 인증 시스템을 구현했다. JwtProvider에 @PostConstruct로 init() 메서드를 작성해 애플리케이션 시작 시 secret 키를 초기화하도록 했고, application.yml에 jwt.secret 값을 설정했다.

JWT 서명에는 secret 키가 사용된다. 이 키는 토큰이 변조되지 않았는지 검증하는 기준이 되기 때문에, 사용하는 알고리즘이 요구하는 최소 길이를 만족해야 한다.

2. 문제 상황

애플리케이션을 실행하자마자 서버가 시작되지 않았고, jwtProvider 빈 생성 과정에서 초기화 메서드 실행에 실패했다.

Error creating bean with name 'jwtProvider': Invocation of init method failed

스택 트레이스를 따라가보니 근본 원인은 WeakKeyException이었다. 지정한 secret 키의 길이가 JWT HMAC-SHA 알고리즘에서 요구하는 보안 기준을 충족하지 못했다.

io.jsonwebtoken.security.WeakKeyException: The specified key byte array is 152 bits
which is not secure enough for any JWT HMAC-SHA algorithm.

3. 원인

원인은 application.yml에 설정한 jwt.secret 기본값이 너무 짧았기 때문이다.

app.jwt.secret=${JWT_SECRET:change-me-for-local}

기본값으로 사용한 change-me-for-local은 길이가 짧아 HMAC-SHA256 알고리즘의 최소 요구 키 길이인 256비트(32바이트)를 만족하지 못했다.

HMAC-SHA256을 사용할 경우 secret 키는 최소 32바이트 이상이어야 한다. 그보다 짧은 키를 사용하면 jjwt가 WeakKeyException을 발생시켜 애플리케이션 시작을 막는다.

4. 해결

해결 방법은 jwt.secret 값을 32자 이상으로 변경하는 것이다. 로컬 환경에서는 충분한 길이의 임시 secret 값을 설정해 서버가 정상적으로 기동되도록 했다.

jwt:
  secret: booktine-secret-key-for-jwt-signing-must-be-32bytes-or-longer

secret 키 길이를 충분히 늘린 뒤 서버가 정상적으로 기동되었고, JwtProvider 초기화도 성공했다.

운영 환경에서 사용할 secret 키는 직접 작성하기보다, 아래와 같은 명령어로 충분히 긴 랜덤 값을 생성하는 것이 안전하다.

openssl rand -base64 64

생성한 값은 코드나 설정 파일에 직접 작성하지 않고 환경변수로 분리한 뒤, application.yml에서 참조하도록 구성한다.

jwt:
  secret: ${JWT_SECRET}

로컬 환경은 application-local.yml에 별도로 관리하거나, .env 파일로 분리해두는 방식이 깔끔하다.

5. 왜 런타임이 아니라 시작 시점에 터지는가

처음에는 요청을 처음 처리할 때 오류가 발생하는 것이 아니라, 왜 서버 시작 시점에 바로 실패하는지 의문이 들었다.

이유는 jjwt가 의도적으로 초기화 시점에 키 유효성을 검증하기 때문이다. @PostConstruct로 키를 초기화하는 시점에 스펙 미달 여부를 확인하고, 기준을 만족하지 못하면 즉시 예외를 던진다.

 

잘못된 키로 서버가 뜬 뒤 인증 요청이 들어올 때 문제가 발생하는 것보다, 아예 서버가 시작되지 못하게 막는 쪽이 더 안전하다. 이런 방식을 fail-fast라고 부른다.

fail-fast는 문제가 있는 설정이나 상태를 가능한 한 빠른 시점에 발견하고 차단하는 방식이다. 보안 설정처럼 잘못된 상태로 서버가 실행되면 위험해질 수 있는 영역에서는 특히 중요한 패턴이다.

스펙 미달 키로 서명된 토큰이 실제 트래픽에서 사용되는 상황 자체를 막는다는 점에서, jjwt의 초기화 시점 검증은 보안 측면에서도 올바른 설계라고 볼 수 있다.

6. 배운 점

• HMAC-SHA256 기준 secret 키는 최소 32바이트, 즉 256비트 이상이어야 한다.
• jjwt는 스펙 미달 키를 런타임이 아니라 초기화 시점에 차단한다.
• 운영 환경에서는 secret 값을 설정 파일에 직접 작성하지 말고 환경변수로 분리해야 한다.
• 운영 secret은 직접 작성한 문자열보다 충분한 길이의 랜덤 값을 사용하는 것이 안전하다.

정리하면, JWT secret은 단순한 문자열 설정값이 아니라 토큰의 신뢰성을 결정하는 보안 요소다. 알고리즘이 요구하는 최소 길이를 만족하고, 운영 환경에서는 반드시 환경변수로 안전하게 관리해야 한다.