JWT とは？仕組み・構造とテストすべきポイント

JWT（JSON Web Token）

英語： JWT

別名： JSON Web Token, ジョット, JSON ウェブトークン, JSON Web Tokens

定義

JSON Web Token は header.payload.signature 形式のコンパクトな署名付きトークンで、ユーザー ID、有効期限、オーディエンスなどのクレームを運びます。

JSON Web Token（JWT、「ジョット」と発音されることが多い）は、Base64url でエンコードされた 3 つの部分をドットで区切った文字列です。署名方法を示すヘッダー、クレームを含むペイロード、そして署名で構成されます。API は通常これを Authorization: Bearer <token> ヘッダーで受け取り、署名を検証することで、データベースを参照せずにクレームを信頼します。OAuth 2.0 や OpenID Connect のプロバイダーの多くは、アクセストークンや ID トークンを JWT として発行しています。

具体例

デコードしたペイロードです。

{
  "iss": "https://auth.example.com",
  "sub": "user_7f3a",
  "aud": "orders-api",
  "role": "member",
  "iat": 1767225600,
  "exp": 1767229200
}

iss は発行者、sub は主体（通常はユーザー）、aud は想定される受信者、iat/exp は Unix エポックからの秒数で表した発行時刻と有効期限です。Node 22 では、ライブラリなしでペイロードを読めます。

const [, payload] = token.split('.');
const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));

エンコードであって暗号化ではない

標準的な署名付き JWT（JWS）はエンコードされているだけで、暗号化されていません。上のコードが示すとおり、トークンを持っている人なら誰でもすべてのクレームを読めます。署名が証明するのは、鍵を持つ誰かがトークンを発行し、改ざんされていないということだけです。したがって、トークンが実際に暗号化されている（JWE という、別のあまり一般的でない形式）場合を除き、JWT のペイロードに秘密情報や個人データを入れてはいけません。トークンをデコードすることは検証することと同じではありません。トークンをデコードするだけのテストは、その真正性について何も確認していません。

テストすべきこと

期限切れのトークン： exp を過去に設定するか経過するのを待ち、401 を期待します。
改ざんされたペイロード： role を admin に変えて古い署名のままにし、401 を期待します。受け入れられたら、サーバーは署名を検証していません。
alg: none： 署名のないトークンは拒否されなければなりません。
誤ったオーディエンスや発行者： 別の API 向けの有効なトークンは、ここでは使えてはいけません。
有効なトークンだが権限が違う： ユーザーは認証済みだが認可されていないので、401 ではなく 403 を期待します。
ログアウトと失効： JWT は通常、有効期限まで有効なので、ログアウトやパスワード変更の後にシステムがどう動くかを確認します。短い有効期限とリフレッシュトークンの組み合わせが一般的な緩和策です。