JWT Decoder と Verifier の使い分け

JWTの中身確認（Decoder）と真正性確認（Verifier）は目的が異なります。まず役割を分けることで、401/403の切り分け速度が上がります。

役割の違い（先にここだけ確認）

• JWT Decoder: header/payload を可読化する。署名の正当性は保証しない。
• JWT Verifier: 署名・鍵・alg・kid・iss・aud を検証し、真正性を判定する。
• 結論: 認可判断は Verifier 側の結果を基準にする。

症状別の入口

• トークンの exp/nbf/iat を確認したい → Decoder
• 署名不正や鍵ローテーション不整合を疑う → Verifier
• 401/403 で原因が不明 → 401/403 ガイド → Authorization / WWW-Authenticate

401/403 切り分けフロー（推奨）

1. 1) Decoderで claims を読む（exp/nbf/aud/iss/scope）
2. 2) Verifierで署名と鍵整合を確認する（alg/kid）
3. 3) 401/403ページでHTTPヘッダー要因を切り分ける

比較軸（実務で効く観点）

• 目的: Decoder は可読化、Verifier は検証
• 入力: Decoder はトークン単体、Verifier は鍵/JWKS/検証条件も必要
• 失敗時の次手: Decoder失敗は形式確認、Verifier失敗は鍵・alg・iss/aud を確認
• 利用場面: Decoder は一次確認、Verifier は本番判定

調査前に揃える入力セット

• 失敗リクエストの Authorization ヘッダー（マスク済み）
• WWW-Authenticate 応答（401時）
• 検証に使う鍵情報（secret / public key / JWKS）
• 期待する iss / aud / scope と環境時刻

運用プレイブック（短縮版）

1. 401が急増: まず Verifier で署名失敗率と kid 不一致を確認
2. 403が増加: Decoder で scope/role claim 変化を確認
3. 時刻起因を疑う: exp/nbf とサーバーNTP同期状況を併せて確認
4. 再発防止: 401/403ごとに reason code をログ項目として固定

関連ツール

• JWT Decoder
• JWT Verifier
• JWT 401/403 Troubleshooting
• Authorization Inspect
• WWW-Authenticate Inspect

よくある誤り

• Decoderの表示だけで「有効トークン」と判断してしまう
• aud/iss の検証を実装せず、署名検証だけで通してしまう
• 401時に WWW-Authenticate を見ずにアプリ側だけを疑う

実装チェックリスト

• 許可algを固定し、none や想定外algを拒否する
• iss/aud の期待値を設定で管理し、環境差を防ぐ
• 鍵ローテーション時は旧鍵の猶予期間を持つ
• トークン内容のログ出力は最小化し、個人情報クレームを残さない
• 認可判断は Decoder ではなく検証結果ベースで行う

FAQ

Decoder で claims が読めれば十分ですか？

十分ではありません。真正性判断は Verifier で署名・鍵・iss/aud を検証して行います。

Verifier 失敗時の最短確認項目は？

alg/kid の一致、使用鍵、iss/aud、exp/nbf と時刻ズレの順で確認すると切り分けが速いです。

参照仕様

• RFC 7519 (JWT)
• RFC 8725 (JWT BCP)