JWT 認証フロー：アクセストークン、リフレッシュトークン、失効

JSON Web Token が人気なのは、API が誰も呼び出さずにトークンを確認できるからです。署名を検証し、クレームを読めば終わりです。しかしこの性質は、JWT の問題の大半の原因でもあります。照会できないトークンは、取り消せないトークンです。チームはノート PC が盗まれたときや、従業員が退職したときに、初めてこのことに気づきます。

この記事では、アクセストークン、リフレッシュトークン、シーケンス図を使って JWT 認証フロー全体を順に説明します。そのうえで、すべての API に必要な検証、ブラウザーでのトークンの保存場所、リフレッシュトークンのローテーション、鍵のローテーション、そして現実的な失効の選択肢を扱います。

JWT とは何か、何ではないか

JWT（RFC 7519）は、ドットで区切られた 3 つの base64url 部分からなる、コンパクトで URL セーフな文字列です。ヘッダー、クレームのペイロード、署名です。デコードすると、アクセストークンは次のようになります。

{ "alg": "RS256", "kid": "2026-10", "typ": "at+jwt" }
{
  "iss": "https://auth.example.com",
  "sub": "user_8412",
  "aud": "orders-api",
  "scope": "orders:read orders:write",
  "iat": 1793606400,
  "exp": 1793607300,
  "jti": "a3f1c9e2"
}

誤解の大半は、次の 3 点から生まれます。

• 署名付きの JWT は暗号化されていません。 トークンを持っていれば誰でもペイロードを読めます。保持者に見られて困る秘密や個人データは入れないでください。
• JWT はプロトコルではなくフォーマットです。 クライアントがトークンを取得する方法は別のところ、通常は OAuth 2.0 と OpenID Connect で定義されています。その部分は OAuth 2.0 フロー図で扱っています。
• フローに出てくるトークンがすべて JWT とは限りません。 アクセストークンは JWT であることが多いですが、リフレッシュトークンは認可サーバーだけが照会できる不透明なランダム文字列であることがよくあります。

どのトークンにも出てくる登録済みクレームは次のとおりです。

フローを順に追う

1. サインイン。 ユーザーは認可サーバーで認証します。通常は PKCE 付きの OAuth 認可コードフローを使います。
2. トークンの応答。 認可サーバーは、短命なアクセストークン（JWT、たとえば 15 分）と長命なリフレッシュトークンを返します。
3. API の呼び出し。 アプリはリクエストのたびに Authorization: Bearer <access token> を送ります。
4. ローカルでの検証。 API は、JWKS エンドポイントから一度取得してキャッシュした認可サーバーの公開鍵で署名を検証し、続いてクレームを確認します。リクエストごとに認可サーバーを呼び出すことはありません。
5. 期限切れ。 15 分後、API は 401 Unauthorized を返します。
6. リフレッシュ。 アプリはリフレッシュトークンを認可サーバーのトークンエンドポイントに送り、新しいアクセストークンと、ローテーションを使う場合は新しいリフレッシュトークンを受け取ります。
7. 再試行。 アプリは、失敗したリクエストを新しいアクセストークンで繰り返します。

ステップ 3 と 4 こそ、チームが JWT を選ぶ理由です。数千件の API リクエストがあっても、共有のセッションストアは要りません。ステップ 5 と 6 はその代償であり、セキュリティ上の作業の大半はここにあります。

トークンの検証：チェックリスト

JWT を受け付けるすべての API は、同じ確認をこの順序で行うべきです。

1. 想定するアルゴリズムだけを許可します。 alg ヘッダーを鵜呑みにしてはいけません。RFC 8725 は 2 つの古典的な攻撃を説明しています。alg を none にする攻撃と、RS256 のトークンを HS256 に書き換え、素朴なライブラリに公開鍵を HMAC の秘密鍵として使わせて検証させる攻撃です。
2. キャッシュした JWKS から kid で鍵を選び、未知の kid を見たらセットを再取得します。ただし短い間隔で 1 回までにします。
3. 署名を検証します。
4. iss と aud を確認します。 別の API 向けに発行されたトークンは、ここで失敗しなければなりません。
5. exp と nbf を、60 秒程度の小さな時計の許容幅を持たせて確認します。
6. トークンの種類を確認します。 RFC 9068 のアクセストークンは typ: at+jwt を持っており、ID トークンがアクセストークンとして使い回されるのを防ぎます。
7. そのうえで認可します。 スコープ、ロール、リソースの所有権です。

Node.js の jose ライブラリを使えば、リストの大半は 1 回の呼び出しで済みます。

import { createRemoteJWKSet, jwtVerify } from 'jose'

const JWKS = createRemoteJWKSet(new URL('https://auth.example.com/.well-known/jwks.json'))

export async function verifyAccessToken(token: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: 'https://auth.example.com',
    audience: 'orders-api',
    algorithms: ['RS256'],
    typ: 'at+jwt',
    clockTolerance: 60,
  })
  return payload // scopes and sub are checked by the caller
}

アクセストークンの有効期間はどれくらいにすべきか

有効期間とは、盗まれたトークンが使え、しかも取り消せない時間枠のことです。短いほど安全ですが、リフレッシュの通信は増えます。8 時間の勤務時間中ずっと操作しているユーザーの場合は次のとおりです。

ほとんどのチームは、アクセストークンを 5〜15 分に落ち着かせます。1 日有効なアクセストークンは、失効させられないセッション Cookie と同じです。

リフレッシュトークンのローテーション

リフレッシュトークンは数日から数週間有効なので、漏えいすればアクセストークンの漏えいより深刻です。OAuth セキュリティの現在のベストプラクティスである RFC 9700 は、ブラウザーアプリやモバイルアプリのようなパブリッククライアントが持つリフレッシュトークンに対して、次の 2 つのうちいずれかの保護を求めています。

• 送信者制約付きのリフレッシュトークン。 相互 TLS や DPoP によって、クライアントが持つ鍵に結び付けます。
• ローテーション。 リフレッシュのたびに新しいリフレッシュトークンを返して古いものを無効にし、認可サーバーはそのチェーンを記録します。攻撃者と正規のクライアントが同じトークンを使えば、どちらかが無効化済みのトークンを提示することになり、サーバーは有効なリフレッシュトークンを失効させます。これで両者のチェーンが終わります。

ローテーションを使えば、盗まれたリフレッシュトークンは数週間続く問題から、正規のクライアントが次にリフレッシュした時点で終わる問題に変わります。代償として、ユーザーは再サインインが必要になります。またトークンエンドポイントは、2 つのタブが同時にリフレッシュしても再利用検知が誤作動しないように対処する必要があり、通常は短い猶予期間を設けます。

ブラウザーでのトークンの保存場所

ブラウザーベースのアプリケーション向け OAuth に関する IETF のドラフトは、backend for frontend パターンを、トークンを JavaScript から完全に遠ざける選択肢として説明しています。トークンをブラウザーに置くなら、アクセストークンはメモリに、リフレッシュトークンはトークンエンドポイントにスコープを限定した HttpOnly Cookie に置いてください。

失効：実際に機能する方法

JWT の署名を取り消すことはできません。できるのは API に受け付けをやめさせることだけで、どの方法もステートレスさを少しずつ手放すことになります。

実用的な組み合わせは次のとおりです。アクセストークンは 15 分以下にし、ローテーションするリフレッシュトークンをログアウト時とパスワード変更時に失効させ、まれな「今すぐすべての場所からサインアウト」には、ユーザー単位の基準時刻を使います。

署名鍵のローテーション

鍵は漏れ、アルゴリズムは古くなります。ローテーションは初日から計画しておきましょう。新しい公開鍵は、それで署名を始める 1 日ほど前に JWKS で公開し、すべての API のキャッシュに行き渡らせます。署名を新しい kid に切り替えます。古い鍵は、それで署名した最後のトークンの期限が切れるまで JWKS に残し、その後に削除します。未知の kid を見たら再取得する API なら、緊急のローテーションも再起動なしで乗り切れます。

JWT フロー図

図の読み方は次のとおりです。

• 3 本のライフライン。 左がブラウザーアプリ、中央が認可サーバー、右が注文 API です。時間は下に向かって流れます。
• ログインとトークンの応答が一番上にあります。アプリはアクセストークンとリフレッシュトークンを受け取ります。
• 正常系：API への Bearer リクエストとその応答です。API はキャッシュした JWKS の鍵でトークンを検証し、認可サーバーを一切呼び出しません。
• opt フラグメントは期限切れの場合を扱います。401、リフレッシュ、古いリフレッシュトークンを無効化した新しいトークンの組、そして再試行したリクエストです。
• Markdown ブロックには、デコードしたトークンと検証項目を載せています。

レビュアーが確認できる認証フローを描くには

• すべての矢印で、すべてのトークンに名前を付けます。 種類と有効期間も添えて、「アクセストークン（JWT、15 分）」のように書きます。どのトークンがどこへ行くのかが曖昧だと、本物のバグが隠れます。
• 検証がどこで行われるかを示します。 署名を検証するライフラインにノートを置き、その鍵がどこから来るのかを書きます。
• 失敗の経路を描きます。 期限切れ、リフレッシュトークンの再利用、ログアウトはフラグメントに描きます。インシデントの大半はそこから始まります。
• 秘密は図に載せません。 プレースホルダーの値を使いましょう。図は思っている以上に広く共有されます。

ライフラインとフラグメントについてはシーケンス図の例で詳しく扱っています。より広いアクセスモデルの中でトークンの確認がどこに位置するかは、ゼロトラストアーキテクチャ図を参照してください。

Archboard で作る

1. Google または GitHub でサインインし、図を作成します。
2. シーケンスパックの ライフライン ノードを 3 つ追加します。Browser app、Auth server、Orders API です。
3. メッセージを上から下へ、ライフライン間のエッジとして描きます。ログイン、トークンの応答、Bearer リクエストとその応答です。それぞれに運ぶトークンのラベルを付けます。
4. 期限切れの経路を囲むように、演算子を opt にしたシーケンスパックの 複合フラグメント を追加します。401、リフレッシュ要求、新しいトークンの組、再試行です。
5. デコードしたトークンと検証チェックリストを書いた基本パックの Markdown ブロックを追加します。

この例で使うダイアグラムノードは 5 個で、Free プランの範囲に収まります。

よくある質問

JWT は暗号化されていますか？ 署名付きの JWT は暗号化されていません。ペイロードは base64url でエンコードされているだけで、トークンを持つ人なら誰でも読めます。暗号化されたトークンには JSON Web Encryption がありますが、ほとんどのアクセストークンは署名だけです。

JWT を localStorage に保存すべきですか？ 長期間有効なものには使わないでください。クロスサイトスクリプティングのバグがあれば、localStorage は読まれてしまいます。アクセストークンはメモリに、リフレッシュトークンは HttpOnly Cookie に置くか、トークンを backend for frontend に置いてください。

JWT がステートレスなら、ユーザーをどうやってログアウトさせればよいですか？ リフレッシュトークンを失効させて新しいアクセストークンが発行されないようにし、アクセストークンを短く保ちます。即時に効かせたい場合は、API が確認するユーザー単位の基準時刻か、jti の拒否リストを追加します。

ID トークンとアクセストークンの違いは何ですか？ ID トークンは、誰がサインインしたかをクライアントに伝えるもので、クライアント向けです。アクセストークンは API 向けです。API は ID トークンを拒否すべきで、typ と aud の確認がそれを明確にします。

HS256 と RS256 のどちらを使うべきですか？ HS256 は 1 つの共有シークレットを使うため、トークンを検証するサービスはどれもトークンを発行できてしまいます。RS256 や ES256 なら、API は公開鍵で検証し、秘密鍵は認可サーバーだけが持ちます。サービスが複数あるなら、こちらのほうが安全な既定の選択です。

無料で始める — 1 シート、クレジットカード不要。