JWTの構造

3つのセグメント、2つのドット

コンパクトな直列化はheader.payload.signatureです。各セグメントは独立にBase64urlエンコードされ、ドットは文字通りの区切りです。このエンコーディングは意図的にパディングを落としており、トークンは英字、数字、ハイフン、アンダースコアだけで構成されます。エスケープなしでURL、ヘッダー、Cookieの中で安全です。最初の2つのセグメントのデコードは、ハックではありません。トークンを調べるための、意図された方法です。検証が行われるのは3つ目のセグメントです。

シグネチャがその上で計算された本物のトークンは、正確に次のようにデコードされます：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyXzg0OTIiLCJhdWQiOiJhcGkuZXhhbXBsZS5jb20iLCJpYXQiOjE3NjcyMjU2MDAsImV4cCI6MTc2NzMxMjAwMCwianRpIjoiYjBmNmMyZDQtNGU3YS00YzFmLTlhMmItM2Q1ZTdmOWExYzNlIn0.iDPqw4BRxZtM064Y3EH83XLB0cgEjbj5snSXeM846VY

{"alg":"HS256","typ":"JWT"}

{"iss":"https://auth.example.com","sub":"user_8492",
 "aud":"api.example.com","iat":1767225600,
 "exp":1767312000,
 "jti":"b0f6c2d4-4e7a-4c1f-9a2b-3d5e7f9a1c3e"}

ヘッダー：トークンの目次

ヘッダーは小さなJSONオブジェクトです。正式にはJWS Protected Header。ほぼすべての仕事をするのは2つのフィールドです。algは署名アルゴリズムを名指し、typはメディアタイプを記録します。慣習上はJWTです。3つ目のkid（キーID）は、発行者が複数の鍵を公開しているとき、検証者を正しい鍵へ導きます。ヘッダーは署名されますが、暗号化は決してされません。そして信頼できるのは、シグネチャの検証が通ったあとだけです。その時点までは、algは事実ではなくクレームです。

ペイロード：登録済みクレームと、それぞれが約束するもの

ペイロードはクレームのJSONオブジェクトです。7つはRFC 7519に登録され、正確で相互運用可能な意味を持ちます。それ以外はすべて、発行者と受け手の間の私的なものです。時刻はNumericDate値——Unixエポックからの秒数であって、ミリ秒ではありません——であり、時刻系のクレームは検証者への助言にすぎません。確認するのは検証者の仕事であって、フォーマットが強制するものではありません。

シグネチャ：HS256、RS256、そして検証の仕組み

シグネチャは、署名入力——エンコード済みのヘッダー、1つのドット、エンコード済みのペイロード——に対して、ヘッダーが名指すアルゴリズムで計算されます。HS256は共有秘密鍵を使うHMAC-SHA256です。高速で対称ですが、署名者とすべての検証者が単一の信頼ドメインを成すときにだけ適切です。秘密鍵を持つ者は誰でもトークンを作れてしまうからです。RS256はRSAです。発行者が秘密鍵で署名し、誰でも——ブラウザを含めて——公開されている公開鍵で検証できます。これこそ、OAuth 2.0やOpenID Connectのようなフェデレーテッドプロトコルの既定になっている理由です。

検証は、シグネチャを再計算して比較します。メカニズムはそれだけです。だからこそ、検査がどう走るかを決めるのは、algヘッダーひとつです。ライブラリは2010年代前半のアルゴリズム混同攻撃のあと、自らを固めました。algにnoneを主張するトークンや、公開鍵をHMACの秘密鍵に見立ててHS256として再生されたRS256トークンが、検証を通るのは、期待するアルゴリズムを固定し損ねた検証者に対してだけです。

HS256: HMAC-SHA256(secret, header + '.' + payload)
       署名者と検証者が秘密鍵を共有する

RS256: RSA-SHA256(private key, header + '.' + payload)
       発行者が署名し、誰でも公開鍵で検証できる

発行者ごとに想定するアルゴリズムを固定する。
トークン自身のヘッダーだけから決めない。
alg: none は決して受け入れない。

署名はされても封はされていない：シグネチャがしないこと

シグネチャが証明するのは、トークンが鍵の持ち主によって発行され、それ以降改ざんされていないこと——完全性と真正性です。機密性はゼロです。Base64urlはエンコーディングであり、ペイロードはトークンを見た者すべてが読めます。ブラウザ拡張、URLでトークンが運ばれるときの中継プロキシ、ログ収集者も含めて。そこからいつも守るべきルールが導かれます。JWTペイロードに秘密を決して入れない。トークンをURLで決して送らない。そして、デコードしたすべてのクレームを、判断ではなくデータとして扱う。

最後の点こそ、クライアント側の罠です。ブラウザはトークンをデコードしてexpやsubを読めます。しかしトークンを実質的に検証することはできません。発行者の鍵を持っていないからです。HS256では、秘密鍵はそもそもブラウザに届いてはならず、RS256では、クライアント側の検査は保持者が何にアクセスできるかについて何も証明しません。クライアントは、表示のためにトークンを調べることはできます。名前を見せる、期限切れを警告する、といったことです。しかし、シグネチャとすべてのクレームを検証するのは、毎回のリクエストでサーバーの仕事です。調べることは検証ではなく、読めることは認可されたことではありません。

トークンを安全に調べる——実務上のループ

規律ある検査ループは数秒で済みます。ヘッダーとペイロードをデコードし、時計と突き合わせてexpとnbfを確認し、issとaudが期待どおりか確かめる。そしてそのときはじめて——サーバーで——固定したアルゴリズムと正しい鍵でシグネチャを検証します。最終検証以外はすべて純粋なテキスト処理です。だからこそ、完全にブラウザ内で動作するデコーダーこそ適切なツールなのです。本物のトークンはベアラークレデンシャルであり、クレデンシャルは自分が管理するタブの中に置くべきものであって、転送するかもしれないウェブサイトの中に置くべきものではありません。

この構造が与えてくれないものも覚えておいてください。失効——jtiベースのブロックリストはサーバー側で構築し、確認しなければなりません。機密性——暗号化されたトークンが必要ならJWEを使います。そして信頼——設定したことのない発行者からの、構造的に完璧なトークンは無価値です。構造は何が約束されたかを教えます。約束が守られたままであることを教えるのは、検証だけです。