JWT invalid signature가 날 때 확인할 6가지

JWT 검증에서 invalid signature가 나오면 토큰 내용이 이상해 보이기보다, 발급 쪽과 검증 쪽의 조건이 어긋난 경우가 더 많습니다. 이 에러는 단순히 "토큰이 틀렸다"가 아니라, 시크릿, 알고리즘, 키 선택, 토큰 전달 과정 중 하나가 맞지 않는다는 신호로 봐야 합니다.

1) 발급 시크릿과 검증 시크릿이 같은가

가장 흔한 원인은 환경 변수 불일치입니다. 로컬에서는 .env.local의 값으로 발급했는데, 서버는 다른 시크릿으로 검증하고 있을 수 있습니다. 멀티 환경에서 .env, 시크릿 매니저, 배포 플랫폼 설정이 다르면 쉽게 발생합니다.

2) 알고리즘 설정이 같은가

토큰은 HS256으로 발급했는데 서버는 RS256로 검증하면 당연히 실패합니다. 반대로 공개키/개인키 기반 토큰인데 대칭키 시크릿으로 검증해도 같은 문제가 납니다. 디코더에서 alg를 보는 것은 도움이 되지만, 실제로는 서버가 허용하는 알고리즘 목록과 맞는지가 더 중요합니다.

3) 토큰이 전달 과정에서 변형되지 않았는가

복사 과정에서 공백이 들어가거나, 프록시나 쿠키 저장 중 문자열이 잘리거나, Base64URL 문자가 바뀌면 서명이 깨집니다. 모바일 앱과 웹, API 게이트웨이를 거치는 동안 헤더 포맷이 달라지는 사례도 있습니다. 따라서 원본 토큰과 실제 서버가 받은 토큰이 같은지 비교하는 과정이 필요합니다.

4) Bearer 접두사 처리에 문제는 없는가

서버에 Authorization: Bearer <token> 형태로 왔는데 검증 코드가 접두사까지 포함한 채 검증하면 실패합니다. 반대로 일부 프록시는 헤더를 재구성하면서 토큰 값만 넘기기도 합니다. 토큰 파싱 단계와 검증 단계를 분리해서 로그를 남기면 이런 문제를 빨리 찾을 수 있습니다.

5) 키 회전(kid) 또는 공개키 선택 문제가 없는가

JWK 기반 검증에서는 토큰 헤더의 kid에 맞는 키를 찾아야 합니다. 키 회전 이후 오래된 키 캐시를 계속 보고 있거나, 잘못된 kid를 참조하면 서명 검증이 실패합니다. 이 경우 단순 시크릿 문제처럼 보여도 실제 원인은 키 선택 로직입니다.

6) 토큰을 사람이 수정하지 않았는가

payload를 디코딩해서 값 하나를 바꾸고 다시 붙여 넣으면, 서명은 자동으로 다시 계산되지 않습니다. 개발 중 디버깅 편의 때문에 payload를 손으로 만졌다가 그대로 검증 API에 넣으면 invalid signature가 나는 것이 정상입니다. JWT는 header와 payload를 읽는 것은 쉽지만, 다시 유효하게 만드는 것은 별개입니다.

7) 빠른 디버깅 순서

1. 디코더로 header의 alg, kid와 payload를 확인
2. 발급 서버와 검증 서버의 시크릿/키 설정 비교
3. 서버가 실제로 받은 토큰 문자열을 로그로 확인
4. Bearer 제거 로직 확인
5. 키 회전 또는 JWK 캐시 사용 여부 확인

이 순서대로 보면 대부분의 invalid signature는 빠르게 정리됩니다.

8) 만료와 서명 실패를 구분해야 한다

어떤 팀은 만료된 토큰도 전부 invalid signature처럼 뭉뚱그려 처리합니다. 하지만 실제로는 expired와 invalid signature는 다른 문제입니다. 만료는 시간과 갱신 로직 문제이고, invalid signature는 키 또는 토큰 무결성 문제에 더 가깝습니다. 에러 메시지를 분리해 두면 운영 속도가 훨씬 빨라집니다.

9) 체크리스트

• 발급과 검증 환경 변수 값이 동일한가
• alg와 검증 알고리즘 목록이 일치하는가
• 토큰 문자열이 중간에 변형되지 않았는가
• Bearer 접두사를 제거한 뒤 검증하는가
• 키 회전 이후 올바른 kid를 참조하는가
• 만료 에러와 서명 에러를 구분해서 기록하는가

10) 관련 도구

JWT Decoder로 토큰 구조를 빠르게 확인할 수 있습니다. 다만 이 도구는 서명 검증을 하지 않으므로, 실제 문제 해결은 서버 설정과 키 관리 로직을 함께 봐야 합니다.