アイキャッチ画像: セキュリティロックのアイコンを表示したノートパソコン。写真提供: Dan Nelson on Pexels(無料利用可)

JSON Web Tokenは、Webが持つ最も標準に近い身分証明書です。自分が誰で、何を許されているかを記した、署名付きの自己完結文書。ブラウザとサーバーの間を毎リクエスト行き来し、現代のAPIとモバイルアプリのログインフローの大部分を支えています。そして同時に、確実に繰り返されるセキュリティ事故の発生源でもあります——JWTは使うのは簡単で、正しく使うのは繊細だからです。

本ガイドでは、JWTの構造、署名と検証の実際の仕組み、落とし穴の場所、そして素の不透明セッショントークンを選ぶべき場面を解説します。トークンのヘッダー・ペイロード・クレームをブラウザで確認するには、無料のJWTデコーダーを。

JWTの解剖

JWTはドットで区切られた3つのBase64urlエンコード部分です:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9  ← ヘッダー
.eyJzdWIiOiIxMjM0NTY3ODkwIn0            ← ペイロード
.s5T_6eJ7xQ8...                          ← 署名
  • ヘッダー — メタデータ:署名アルゴリズム(alg)とトークン種別(typ)。典型は {"alg":"HS256","typ":"JWT"}
  • ペイロード — クレーム:識別子(sub)、有効期限(exp)、発行者(iss)、オーディエンス(aud)、加えてアプリ独自のフィールド
  • 署名 — 最初の2つの部分から、アルゴリズムと鍵で計算。改ざんを防ぐのはこれ

デコードがすることとしないことを明確に。ヘッダーとペイロードは誰でもBase64urlデコードできます——JWTデコーダーはまさにそれを、鍵なしで行います。デコードはクレームを明かすだけ。正しい鍵に対する署名検証だけが、クレームの真正性を証明します。この2つは頻繁に混同され、「JWTセキュリティ」事故の大半は「デコードだけして検証しない」システムから生まれます。

署名と検証の仕組み

HS256(HMAC-SHA256)は単一の対称秘密鍵を使います:

署名 = HMAC-SHA256(秘密鍵, base64url(ヘッダー) + "." + base64url(ペイロード))

サーバーは秘密鍵で署名し、再計算して検証します。検証する全員が共有する鍵が1つ——漏れたら誰でもトークンを偽造できます。

RS256(RSA with SHA-256)は秘密鍵/公開鍵のペアを使います。認可サーバーが秘密鍵で署名し、リソースサーバーは公開鍵で検証します。検証者に秘密を配る必要がなく、これがマルチサービス・マルチテナントの標準であり、OpenID Connectプロバイダーの必須要件です。

サーバーが毎リクエストで実行すべき検証チェックリスト:パース、署名検証、exp(未失効)、iss/aud(意図した発行者・宛先)の確認、そして初めてクレームを信じる。

クレーム:入れるもの、入れないもの

知っておくべき標準クレーム:

クレーム意味
subサブジェクト——ユーザー/エンティティID
iss発行者——誰が署名したか
audオーディエンス——誰宛てか
exp有効期限(Unix秒)
iat / nbf発行時刻/有効開始時刻

独自クレームの設計ルール:必要最小限の情報。 トークンは毎リクエスト送信され、クレームが増えるほど肥大化し、クレームはクライアントから読めます(デコードは無料)。秘密——APIキー、パスワードハッシュ、カード断片——はJWTペイロードに絶対に入れてはいけません。"api_key": "..." を載せたトークンは「起きるのを待つバグ」ではなく、バグそのものです。

セキュリティの落とし穴ランキング

1. alg: "none" の受け入れ。 アルゴリズムなしを宣言するトークンは無条件に拒否しなければなりません。歴史的に一部のライブラリが許可し——「alg none攻撃」——攻撃者に署名を完全に剥がさせました。トークンが主張するアルゴリズムではなく、あなたが期待するアルゴリズムであることを検証してください。

2. 弱い/漏洩したHS256秘密鍵。 「secret」「changeme」、ハードコードされたデモ鍵は秒で偽造されます。秘密鍵は最低32ランダムバイト、環境変数に保存、ローテーション必須。

3. localStorageへのトークン保存。 localStorageは同一オリジンのあらゆるスクリプトから読める——つまりXSSの脆弱性が即座にトークン窃取にエスカレートします。HttpOnlyクッキーが安全な輸送手段です。ヘッダー方式を使わざるを得ないなら、有効期限を短く。

4. 長寿命トークン。 exp が1年のトークンは、盗まれたら1年使える認証情報です。短命のアクセストークン(分単位)とリフレッシュトークンのローテーションで、被害範囲を数分に縮められます。

5. aud と iss の未確認。 別サービスのために正しく署名されたトークンを自サービスが受け入れるのは、サービス間偽造です。両フィールドを確認しましょう。

アクセストークンとリフレッシュトークン

現代のパターンは認証情報を2つに分けます:

  • アクセストークン — 短命(5〜60分)、毎リクエストに添付、実際のAPIアクセスを許可
  • リフレッシュトークン — 長命、サーバー側または強化クッキーに保持、新しいアクセストークン発行専用、使用ごとに無効化(ローテーション)

この分割が短い有効期限を実用的にします。ユーザーは5分ごとに再ログインせず、盗まれたアクセストークンは攻撃者が何かする前に失効します。JWTはアクセストークンの役割に向いており、リフレッシュトークンは通常サーバー側に保存される不透明値です。

JWTを使うべきでない場面

JWTは無条件のアップグレードではありません。不透明セッショントークン——サーバー側に保存されるランダムID——がJWTに勝る場面が3つあります。即時の失効が必要なとき(JWTは exp まで有効、それ以上は追加インフラが必要)、トークンが大きなクレームを運ぶとき(毎リクエストの5KB JWTは純粋なオーバーヘッド)、監査と制御がステートレス性より重要なとき(サーバー側セッションは中央で一括無効化できる)。正直なルール:単一サービス+データベースなら不透明セッションの方がシンプルで安全。JWTが複雑さに見合うのは、多数のサービスや複数の信頼ドメインがあるときです。

JWTデコーダーでのデバッグ

401の謎を最速で解く道:JWTデコーダーにトークンを貼り、exp を現在時刻と比較し、aud/iss が自サービスと一致するか確認し、alg がバックエンドの期待と一致するか確認する。デコーダーは iat/exp をローカル時刻に自動変換し、完全にブラウザ内で動作——トークンはページの外に出ません。Base64ツール(JWTは内部でBase64url)とSHAハッシュジェネレーター(HS256はHMAC-SHA-256)が自然な相棒です。

検証の実装:すべての言語で効くチェックリスト

スタックが何であれ、検証手順は同じです——そして順序が重要。よくある脆弱性は、署名を検証せず exp だけを見る(またはその逆)ことです:

1. トークンを「.」で分割し、正確に3パートであることを要求
2. 設定していないalgを拒否——トークン自身の主張ではなく、
   許可リスト(例: {"RS256"} または {"HS256"})だけを受け付ける
3. 正しい鍵で最初の2パートの署名を検証
4. ペイロードをデコードしexpを検証:now >= exp なら拒否
   (時計ずれの許容は小さく、例: 30秒)
5. あれば nbf と iat の妥当性を検証
6. iss と aud を期待値と照合
7. ここで初めてクレームを読み、認可する

エコシステム別ライブラリメモ:

  • Node.js: jsonwebtoken が一般的——デフォルトに任せず { algorithms: ['RS256'] } を明示
  • Python: PyJWT。jwt.decode(token, key, algorithms=["RS256"], audience=..., issuer=...) を使う
  • Go: golang-jwt/jwt。jwt.WithValidMethods で使うメソッドだけ登録
  • Java: jjwt(io.jsonwebtoken)。Jwts.parser().verifyWith(key) で特定アルゴリズムを要求

どのエコシステムでも繰り返されるミスは同じです。トークンが宣言する alg を何でも受け入れる寛容な設定。アルゴリズムを許可リスト化すれば、残りはその1つの決定から従います。

鍵管理。 HS256の秘密鍵は環境変数かシークレットマネージャーに置き、最低32ランダムバイト、スケジュールでローテーション——旧トークンがローテーション中も検証できるよう重複期間を設けます。RS256の鍵はアイデンティティプロバイダーかJWKSエンドポイントに置き、リソースサーバーは公開鍵(またはJWKS文書)を取得して短いTTLでキャッシュします。どちらの鍵種別もアプリケーションコードやフロントエンドのバンドルに埋め込まないでください。

手で読むトークン:デコーダーが見せるもの

この最小トークンを例に:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MiIsIm5hbWUiOiJBZGEiLCJleHAiOjE3OTg3NTg0MDB9.sig

JWTデコーダーに貼ると:

  • ヘッダー: {"alg":"HS256","typ":"JWT"} — HMAC署名、対称秘密鍵
  • ペイロード: sub: 42、name: "Ada"、exp: 1798758400 — デコードされ、ツールがローカル時刻に変換
  • 署名: 表示用に短縮——鍵が供給されていないため、ツールは意図的に検証しません

この表示がデコードで得られるすべてです:構造とクレーム。トークンが有効かは、鍵を持つサーバーだけが答えられる問いです——デバッガーにトークンを貼ることが何かを「ハッキング」すると思っている人に、繰り返し伝える価値のある事実です。

よくある質問


JWTの構造とクレームはRFC 7519に基づく。HMAC/RSAのアルゴリズム名はRFC 7518に基づく。OpenID Connectの署名要件はOpenID Connect Core仕様に基づく。