RFC 7519 · JSON Web Signature

JWT 入門

JSON Web Token（JWT）は、クレームをコンパクトで URL 安全な文字列として表すオープン標準（RFC 7519）です。OAuth 2.0 や OpenID Connect で広く使われますが、形式自体は汎用的で、正しい検証材料を持つ者は署名を確認しクレームを解釈できます（鍵と時刻管理の範囲内で）。

本ページでは JWT の組み立て方、各部分の読み方、トーク単体から期待できる保証とできないことを説明します。

01

コンパクトな直列化とエンコード

通常の形（JSON Web Signature, JWS）では、JWT はドットで区切られた 3 セグメント（ヘッダー、ペイロード、署名）です。最初の 2 つは JSON を Base64URL でエンコードしたもの（標準 Base64 ではない）で、パディング省略や URL 安全な文字によりヘッダーやクエリに載せやすくなります。

Base64URL は暗号化ではありません。ヘッダーとペイロードは文字列を持つ者なら誰でも読めます。署名は、署名鍵を制御する者が最初の 2 セグメントを生成したことを示しますが、内容を隠しません。

02

JWT の構造

コンパクトな JWS 形では各セグメントの役割は次のとおりです。

ヘッダー

通常 typ（多くは "JWT"）と alg（署名アルゴリズム）を含みます。JWKS から公開鍵を選ぶ kid など、スタックが要求するメタデータも載ります。

ペイロード

クレームを含む JSON オブジェクト: 主体、有効期間、オーディエンス、アプリ固有フィールドなど。発行者が定義すればネストも可能です。

署名

"header.payload" のバイト列（2 つのエンコード済みセグメントとその間のドット）に対する暗号値で、ヘッダーのアルゴリズムと共有秘密（HMAC）または非対称秘密鍵（RSA、ECDSA、EdDSA）を用います。

03

クレーム: ペイロードの中身

クレームは名前と値のペアです。意味は文脈に依存しますが、RFC 7519 は登録済み名を定め、ライブラリや API が一貫して解釈できるようにしています。

登録済みクレーム

例: iss, sub, aud, exp, nbf, iat, jti。exp と nbf は Unix 時刻です。正しく検証するには検証側に信頼できる時刻が必要です。

パブリッククレーム

IANA の「JSON Web Token Claims」レジストリに登録すると多くの実装間で相互運用しやすくなりますが、意味は当事者が合意するまで慣習にすぎません。

プライベートクレーム

発行者と利用者の間で合意した名前（内部ロールやテナント ID など）。登録名と衝突させないか、両側を完全に制御する場合に限って使ってください。

04

アルゴリズムの概要

ヘッダーの alg が署名の計算方法を選びます。モデルを誤ると、誰が検証できるかや秘密の共有方法に影響します。

  • HMAC（HS*）: 共有秘密で署名と検証。単一サービスでは単純ですが、検証者全員が秘密を保持する必要があります。
  • RSA や ECDSA/EdDSA: 発行者が秘密鍵で署名し、検証者は公開鍵を使用（多くは JWKS 配布）。マイクロサービスや署名秘密を持てない公開クライアントに適します。
  • アルゴリズム "none" は本番で受け入れてはいけません。誤設定で署名なしトークンを許す恐れがあります。未知または無効なアルゴリズムは明示的に拒否してください。
05

セキュリティ: 信頼、プライバシー、検証

有効な署名は、署名鍵を制御する者が発行し、ヘッダーとペイロードが改ざんされていないことを示します。それ自体は暗号化ではありません。

パスワード、API キー、長寿命の秘密をペイロードに入れないでください。署名に加えて機密性が必要なら転送は TLS、形式は JWE など別ワークフローを検討します。

サーバーは期待する鍵または JWKS で署名を検証し、exp（通常は nbf も）を確認し、アーキテクチャが依存する場合は aud と iss を強制し、適切なら短命とリフレッシュを使います。

06

よくある用途

JWT は次のような用途で使われます:

  • 認証済みアイデンティティと認可（ベアラーアクセストークン、OpenID Connect の ID トークン）
  • 分散システムでサービス間にアイデンティティや委任を伝播
  • 安全な保存とリフレッシュ戦略と組み合わせてクライアントのセッション状態を表現
  • API ゲートウェイやリソースサーバーで OAuth 2.0 スコープやカスタムクレームを運ぶ
07

実務上の限界

JWT を設計するときの制約の例:

  • サイズ: 多くは HTTP ヘッダーに載ります。大きいペイロードは遅延を増やしプロキシ制限に当たることがあります。
  • 失効: 純粋なステートレス JWT は、追加インフラ（拒否リスト、イントロスペクション、極めて短い有効期間）なしでは即時失効できません。
  • 時刻ずれ: exp と nbf の検証は発行者と検証者の時刻がおおむね同期していることを前提とします。