JWTの署名を検証して改ざんを確認する方法

JWTの署名を検証すると、トークンが発行時の内容のままかどうか、そしてその署名が自分の知っている秘密鍵で作られたものかどうかを確認できます。APIのレスポンスで受け取ったトークンが改ざんされていないかを自分で確かめたい開発者に向けた記事です。
署名がどのように計算・比較されるのか、そして「検証失敗」が表示される2つの異なる原因を、コードの動作そのままに説明します。
まとめ ① JWTはheader.payload.signatureという3つの部分がピリオドでつながった文字列で、headerとpayloadは暗号化ではなくBase64Urlでエンコードされているだけです。 ② signatureはheaderとpayloadを合わせた文字列を秘密鍵でHMAC-SHA256計算した値で、検証とは同じ計算をもう一度行い、値が一致するかどうかを比べることです。 ③ 検証失敗は秘密鍵が違う場合でも内容が改ざんされた場合でも同じように現れ、失敗メッセージだけではどちらなのか区別できません。
検証失敗は見たけれど、原因が分からないとき
バックエンドAPIがログイン時にJWTを発行し、以降のリクエストごとにクライアントがAuthorizationヘッダーにそのトークンを載せて送る、という構成はよくあります。サーバーはリクエストが来るたびにトークンの署名を計算し直し、本当に自社サーバーが発行したトークンなのかを確認します。
問題は、この検証で「失敗」が出る瞬間です。サーバーを再デプロイして環境変数のシークレットキーが変わった場合や、テスト環境で別のキーを誤って設定した場合も、画面には改ざんされたトークンとまったく同じ「失敗」としてしか表示されません。仕組みを知らないと、見当違いの場所で原因を探すことになります。
もうひとつよくある誤解が、「payloadに入っているユーザー情報は暗号化されているから安全だ」という考えです。実際にはpayloadはBase64Urlでエンコードされているだけなので、トークン文字列さえあれば誰でもその内容を読めます。
この誤解から、パスワードや個人番号のような機密情報をpayloadにそのまま入れてしまうミスが起きることもあります。
ツールを使わずに署名を自分で計算して検証する方法
JWTはピリオド(.)でつながった3つの部分です。header.payload.signatureの順で、それぞれ次の内容を持ちます。
- header: 署名アルゴリズム(alg)とトークンタイプ(typ)を持つJSON
- payload: 実際に格納したいデータ(claims)を持つJSON
- signature: headerとpayloadを合わせた文字列を秘密鍵で署名した値
headerとpayloadはそれぞれ、JSONをBase64Urlでエンコードしたものです。暗号化ではなくエンコードなので、鍵がなくても誰でも元のJSONに戻せます。
たとえばHS256トークンのheader部分であるeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9は、次のようにデコードされます。
{"alg":"HS256","typ":"JWT"}
Base64Urlは標準のBase64と2文字だけ異なります。+が-に、/が_に変わっており、末尾の=パディングは省略されています。標準のbase64デコーダーを使うには、この2文字を戻してパディングを補う必要があります。
signatureを検証する手順は次のとおりです。まずトークンのheader部分とpayload部分をピリオドでつなぎ直し、header.payloadという文字列を作ります。
この文字列を発行時と同じ秘密鍵でHMAC-SHA256計算し、Base64Urlでエンコードすると、トークンの3番目の部分と正確に一致するはずです。
printf '%s' "$HEADER.$PAYLOAD" | openssl dgst -sha256 -hmac "シークレットキー" -binary | openssl base64
この計算は決定的(deterministic)です。同じ文字列と同じ鍵を入れれば、いつでも同じ署名になります。
headerやpayloadを1文字だけ変えても、再計算した署名はまったく別の値になり、元の署名とはもう一致しません。「改ざんを検出する」というのは、実際にはこの比較ひとつで成り立っています。
手作業でやると、Base64とBase64Urlの文字の置き換え、省略されたパディングの復元、HMACコマンドの文法で間違えやすくなります。毎回この手順を繰り返すのも面倒です。
JWT生成・検証ツールで確認する。
ブラウザ上ですぐに署名を計算・比較できます。入力した秘密鍵とトークンはサーバーに送信されません。

検証失敗の2つの原因、そしてエンコードと暗号化の混同
「検証失敗」という結果ひとつには、異なる2つの原因が重なっています。再計算した署名がトークンの署名と違えば、原因に関係なく同じように「失敗」としか表示されないためです。
| 原因 | 何が違うのか | 確認する方法 |
|---|---|---|
| シークレットキーの不一致 | 署名計算に使った鍵そのものが発行時と違う | 発行サーバーが使う鍵とまったく同じ文字列か(空白・改行を含む)を再確認 |
| 内容の改ざん | headerまたはpayloadのJSON値が発行後に変わった | 発行時と同じ鍵を入れたのに失敗するなら、内容が変わった側 |
つまり検証失敗のメッセージ自体は、2つの原因を区別してくれません。正しい鍵を確実に把握している状態で失敗するなら、そのとき初めて「内容が変わった」と絞り込めます。
2つ目の混同は「payloadは暗号化されている」という考えです。エンコードと暗号化は目的そのものが異なります。
| 項目 | Base64Urlエンコード (JWT payload) | 暗号化 |
|---|---|---|
| 目的 | データをテキストに置き換えて表す | 内容を第三者が読めないように隠す |
| 復元に鍵が必要か | いいえ | はい |
| 元に戻せる範囲 | トークン文字列さえあれば誰でも | 正しい復号鍵を持つ人だけ |
署名(signature)が保証するのは完全性(発行後に変わっていないこと)と発行者確認(その秘密鍵を知っている側が作ったこと)です。機密性(内容を隠すこと)は保証しません。
payloadに入っている値は、署名が有効かどうかに関係なく、トークンを持つ誰もがデコードして読めます。
まとめ
- JWTはheader.payload.signatureという3つの部分がピリオドでつながった文字列です。
- headerとpayloadはBase64Urlエンコードにすぎないので、誰でもデコードして読めます。暗号化ではありません。
- signatureはheader.payload文字列を秘密鍵でHMAC-SHA256計算した値で、検証とはこの計算をやり直して値が一致するか比べることです。
- 「検証失敗」はシークレットキーの不一致と内容の改ざんのどちらの場合でも同じように現れ、メッセージだけでは区別できません。
- 署名は完全性と発行者確認のためのものであり、payloadの内容を隠す機能ではありません。
ブラウザ上ですぐに署名を計算・比較できます。入力した秘密鍵とトークンはサーバーに送信されません。
よくある質問
JWTのpayloadは暗号化せずにそのまま見てもいいのですか?
デコードするだけで内容を見られます。headerとpayloadはBase64Urlでエンコードされたものなので、鍵がなくても誰でも元のJSONに戻せます。このツールの検証タブも、署名が正しいかどうかに関係なく、デコードされたJSONを常に一緒に表示します。
検証に失敗したら、必ずトークンは偽造されているのですか?
いいえ。検証に使ったシークレットキーが発行時の鍵と違う場合でも、同じように失敗として表示されます。発行サーバーが使う鍵とまったく同じ文字列を入れたのに失敗するなら、そのときに内容が変わった可能性を調べる番です。
RSAのような非対称鍵アルゴリズムで署名されたトークンも検証できますか?
このツールはHMAC-SHA256(HS256)の対称鍵署名のみに対応しています。RSAなどの非対称鍵アルゴリズム(RS256など)で署名されたトークンは、このツールでは検証できません。
このツールに入力したシークレットキーやトークンはサーバーに送信されますか?
送信されません。署名の生成と検証はブラウザのWeb Crypto APIを使って端末内だけで計算され、入力した値が外部に出ることはありません。
この記事は韓国語の原文をもとに作成しています。 韓国語の原文を読む