JWKSの視覚的イメージ

「公開鍵、どこに置いたっけ？」

JWTの署名検証に RSA などの公開鍵方式を使うとき、必ずぶち当たる壁があります。
「公開鍵はどうやって配布するのが一番安全？」「鍵を更新したとき、全サーバーの設定を書き換えるの？」

そんな悩みをスマートに解決するのが JWKS (JSON Web Key Set) という仕組みです。

JWKS：公開鍵の「ショーケース」

JWKS（ジェイ・ダブリュー・ケー・エス）は、その名の通り「JSON形式で書かれた鍵のセット」です。
認証サーバー（Auth0 や Cognito など）が特定の URL でこの JSON を公開し、検証側の API サーバーがそれを読み取りに行きます。

いわば、**「最新の公開鍵はこちらに展示していますので、ご自由にお持ち帰りください」**というショーケースのようなイメージです。

なぜ JWKS が嬉しいのか？

  1. 自動ローテーション: 鍵を新しくしても、ショーケースの中身を入れ替えるだけ。APIサーバーはURLを見に行くだけで最新の鍵を手に入れられます。
  2. 複数の鍵を管理: 「古い鍵」と「新しい鍵」を同時に置いておけるので、移行期間もスムーズです。
  3. 世界標準: OAuth 2.0 や OIDC で広く採用されているため、多くのライブラリが標準で対応しています。

JWKSのナカミ：ただのJSONです

一見難しそうですが、中身はとてもシンプルです。 keys という配列の中に、個々の鍵の情報が入っています。

{
  "keys": [
    {
      "kty": "RSA",           // 鍵の種類（RSAとか）
      "use": "sig",           // 用途（署名用だよ！）
      "kid": "my-key-2024",   // 鍵の識別子（名前みたいなもの）
      "n": "...",             // 公開鍵のデータその1
      "e": "AQAB"             // 公開鍵のデータその2
    }
  ]
}

DevToolKits で JWKS を「作る側」を体験する

当サイトの JWKS生成ツール を使えば、開発やテストに必要な鍵ペアをブラウザ上だけで作成できます。

「公開鍵（JWKS形式）」と「秘密鍵（PEM形式）」の両方が手に入るので、ローカルでの認証機能の実装テストに最適です。もちろん、ブラウザ内ですべて完結するため、秘密鍵がインターネットに流れる心配はありません。

JWT署名検証でJWKSが使われる流れ

JWKSは単体で使うというより、JWTの署名検証とセットで登場します。
典型的な流れは次の通りです。

  1. 認証サーバーがJWTを発行する。
  2. JWTヘッダーには、署名に使った鍵を示す kid が入る。
  3. APIサーバーはJWKSエンドポイントから公開鍵一覧を取得する。
  4. kid が一致する公開鍵を選ぶ。
  5. その公開鍵でJWTの署名を検証する。

この仕組みによって、APIサーバーは秘密鍵を持つ必要がありません。
署名に使う秘密鍵は認証サーバー側に置き、検証側は公開鍵だけを使うため、役割を分けて安全に運用できます。

JWKSを扱うときの注意点

JWKSは便利ですが、設定を誤ると認証まわりのトラブルにつながります。
実装時は次の点を確認しておくと安心です。

  • JWTヘッダーの kid とJWKS内の kid が一致しているか
  • alg が想定している署名アルゴリズムか
  • JWKSの取得結果を適切にキャッシュしているか
  • 鍵ローテーション時に新旧の鍵を一時的に並べているか
  • 失効した鍵をいつ削除するか決めているか

とくに鍵ローテーションでは、新しい鍵で発行されたJWTと、古い鍵で発行済みのJWTが同時に存在する期間があります。
その間はJWKSに複数の公開鍵を載せ、どちらのJWTも検証できる状態にしておくのが一般的です。

よくある質問

JWKSに秘密鍵を入れてもいいですか？

入れてはいけません。JWKSとして外部に公開するのは、署名検証に使う公開鍵です。
秘密鍵はJWTを発行する側だけが保持し、ブラウザやAPI利用者から見える場所には置かないでください。

kid は必須ですか？

複数の鍵を扱う運用では、kid が非常に重要です。
JWTヘッダーの kid とJWKS内の kid を照合することで、検証側はどの公開鍵を使えばよいか判断できます。
鍵ローテーションを考えるなら、最初から kid を付けておくのがおすすめです。

ローカル開発用のJWKSはどう作ればいいですか？

JWKS生成ツール でテスト用の鍵ペアを生成し、公開鍵側をJWKSとして使えます。
本番の秘密鍵を貼り付けたり共有したりせず、開発用と本番用の鍵を分けて管理してください。

まとめ

JWKSは、複雑な鍵管理をシンプルに、安全にしてくれる優れた仕組みです。
仕組みを理解して使いこなすことで、あなたの認証システムはぐっと洗練されたものになります。「鍵の配布」に迷ったら、このショーケースの仕組みを思い出してくださいね。