🧠 Ghost Admin API에서 JWT 인증 오류 해결기

Ghost 블로그에서 Admin API를 호출하려면 JWT를 발급해야 합니다.
문서도 많고 예제도 있어서 간단해 보이지만, 실제로는 작은 차이 하나로 계속 인증 오류가 발생할 수 있습니다.

이번 글은 datetime.utcnow()로 JWT를 발급했을 때 발생한 401 Invalid JWT 문제의 원인을 분석하고,
"왜 datetime.now()로는 되는데, utcnow()로 하면 실패할까?"라는 질문에 대한 모든 해답을 담았습니다.

⏳ JWT 기본 구조

JWT는 일반적으로 다음 두 가지 시간 관련 정보를 포함합니다:

{
  "iat": 1712900400,
  "exp": 1712900700
}

🔐 Ghost는 어떻게 JWT를 검증할까?

Ghost는 jsonwebtoken이라는 Node.js 라이브러리를 통해 JWT를 검증합니다.
Ghost의 핵심 코드 (core/server/services/auth/api-key/admin.js)는 다음과 같습니다:

const verified = jwt.verify(token, secret, {
    audience: '/admin/',
    algorithms: ['HS256'],
    ignoreExpiration: false
});

ignoreExpiration: false는 만료시간(exp)을 반드시 검사하겠다는 의미입니다.

❓ 실험 결과: now()는 되고, utcnow()는 실패?

실험 1 - datetime.now() 사용 (KST 기준)

• 생성된 iat: 현재 시간보다 미래로 인식
• ✅ 정상 인증됨

실험 2 - datetime.utcnow() + 10초 사용

• 생성된 iat: Ghost 서버보다 과거 시점으로 인식
• ❌ 401 INVALID_JWT 오류 발생

🧭 원인은 서버 시간과의 오차

컨테이너 내부에서 확인한 서버 시간:

$ docker exec -it ghost date
Sat Apr 12 15:14:10 UTC 2025

즉, JWT 발급 시점이 서버 시간보다 앞서 있어야 토큰이 유효합니다.
utcnow()는 실제 서버보다 몇 초 과거로 찍히는 문제가 있었던 것이죠.

✅ 정리

💡 실전 팁

• 가능한 datetime.utcnow() + 5~10초 버퍼 추가
• 서버는 반드시 NTP 동기화
• 토큰 유효 시간은 5~10분 이내 유지

🙇 마무리하며

이번 문제는 단순히 코드를 고치는 게 아니라,
시간 동기화와 JWT 표준 이해가 함께 필요한 이슈였습니다.

이 글은 Joon의 실험과 ChatGPT의 코드 리뷰를 기반으로 작성되었습니다.

🏷 태그

tech, ghost, jwt, debug