メインコンテンツまでスキップ

トークン有効期限パターン

このドキュメントの目的​

トークン有効期限の戦略を理解し、サービスに適したパターンを選択・設定することが目標です。

学べること​

✅ トークン戦略の基礎

  • 4つのトークン有効期限パターンの違い
  • セキュリティと利便性のトレードオフ
  • 各パターンの推奨ユースケース

✅ 実践的な知識

  • Management APIでの設定方法
  • デフォルト設定の理解

所要時間​

⏱️ 約10分

前提条件​

  • how-to-02でテナント作成完了
  • 認可サーバー設定の基本理解

トークン有効期限パターンの概要​

アクセストークンおよびリフレッシュトークンの有効期限管理には、主に以下の4つのパターンがあります。それぞれの特徴は、セキュリティと利便性のバランスに応じて選択してください。

パターン概要推奨度
ローテーション＋固定セキュリティ重視。長期利用は不可。セキュアな実装のため推奨。◎ 推奨
ローテーション＋延長セキュリティ・利便性ともに高い。○ 選択可
非ローテーション＋固定利便性重視。ただし、セキュリティリスクがある。△ 注意
非ローテーション＋延長利便性重視。ただし、セキュリティリスクがある。△ 注意

各パターンの詳細​

アクセストークン（AT）有効期限：30分 リフレッシュトークン（RT）有効期限：60分 における各パターンの有効期限の詳細を説明します。

1. ローテーション＋固定パターン（◎ 推奨）​

リフレッシュトークンはローテーションされますが、有効期限は「初回発行時点から固定」で延長されません。
セキュリティを最重視したい場合に推奨される実装パターンです。

  • リフレッシュトークン自体の有効期限は延長されない
  • 有効期間満了後は再認証が必要
  • セキュリティを最重視するサービスに最適

2. ローテーション＋延長パターン（○ 選択可）​

リフレッシュトークンを使ってトークンを再発行するたびに、新しいリフレッシュトークンが発行され、その有効期限も「今」から再度延長されます。
セッションが続く限り、ログイン状態を長期間維持できます。FAPI等で採用例あり。

  • リフレッシュトークンを使うたび、有効期限が「今」から再延長される
  • 古いトークンセット（アクセストークン・リフレッシュトークン）は無効化される

3. 非ローテーション＋固定パターン（△ 注意）​

リフレッシュトークンはローテーションせず、かつ有効期限も「初回発行時点から固定」です。

  • リフレッシュトークンはずっと同じで、有効期限も初回発行時から変わらない
  • 有効期限切れ後は再認証が必須
  • セキュリティリスクが比較的高い

4. 非ローテーション＋延長パターン（△ 注意）​

リフレッシュトークン自体はローテーションせず、最初に発行されたものをずっと使い続けます。
ただし、トークンを再発行するたびにリフレッシュトークンの有効期限が延長されます。

  • 使うリフレッシュトークンは常に同じ
  • トークン再発行のたびにそのリフレッシュトークンの有効期限が延長される
  • セキュリティリスクが比較的高い

設定方法​

各パターンは以下の2つの設定項目で制御します：

設定項目説明設定値デフォルト
refresh_token_strategyリフレッシュトークンの有効期限戦略"FIXED" / "EXTENDS""FIXED"
rotate_refresh_tokenリフレッシュトークンのローテーション有無true / falsetrue

パターン別設定​

パターンrefresh_token_strategyrotate_refresh_token
ローテーション＋固定（◎推奨）"FIXED"true
ローテーション＋延長"EXTENDS"true
非ローテーション＋固定"FIXED"false
非ローテーション＋延長"EXTENDS"false

Management API での設定例​

curl -X PUT https://api.local.test/v1/management/tenants/{tenant-id}/authorization-server \
  -H "Content-Type: application/json" \
  -d '{
    "extension": {
      "refresh_token_strategy": "FIXED",
      "rotate_refresh_token": true,
      "refresh_token_duration": 3600
    }
  }'

デフォルト設定​

設定を省略した場合、最もセキュアな ローテーション＋固定パターン が適用されます：

  • refresh_token_strategy: "FIXED"
  • rotate_refresh_token: true

クライアントレベルのオーバーライド​

テナントレベルの設定に加えて、クライアントごとにトークン戦略をオーバーライドできます。

クライアントの extension オブジェクトに設定することで、そのクライアントだけ異なる戦略を適用できます。未設定の場合はテナント設定にフォールバックします。

設定例​

curl -X PUT https://api.local.test/v1/management/tenants/{tenant-id}/clients/{client-id} \
  -H "Content-Type: application/json" \
  -d '{
    "extension": {
      "refresh_token_strategy": "EXTENDS",
      "rotate_refresh_token": true,
      "refresh_token_duration": 2592000
    }
  }'

ユースケース​

シナリオテナント設定クライアントオーバーライド理由
モバイルアプリFIXED + rotateEXTENDS + rotate長期ログイン維持
管理画面EXTENDS + rotateFIXED + rotateセキュリティ強化
バッチ処理FIXED + rotateFIXED + !rotateトークン値の固定化

アクセストークンの形式（Opaque vs JWT）​

アクセストークンの形式は、authorization_server.extension.access_token_type で制御します。

形式概要トークン例
opaque（デフォルト）ランダム文字列。リソースサーバーはIntrospectionエンドポイントで検証dGhpcyBpcyBhbiB...
jwtheader.payload.signature 形式。JWKSで署名検証してローカル検証可能eyJhbGci...eyJzdWIi...signature

Opaque トークン（デフォルト）​

  • トークン自体には情報を含まないランダム文字列
  • リソースサーバーはアクセストークンを受け取るたびに、IdPの Introspectionエンドポイント に問い合わせてトークンの有効性を確認する
  • Revocation（失効）が即時反映される: トークンを失効させると、次回のIntrospection問い合わせで即座に無効と判定される
  • IdPへのネットワーク通信が毎回発生するため、レイテンシが増加する

JWT トークン​

  • トークン自体にクレーム（ユーザー情報、有効期限等）を含む自己完結型トークン
  • リソースサーバーはIdPの JWKSエンドポイント から公開鍵を取得し、トークンの署名をローカルで検証できる
  • IdPへの毎回の問い合わせが不要なため、パフォーマンスに優れる
  • ただし、トークンを失効させても有効期限が切れるまでリソースサーバー側では有効と判定される可能性がある

使い分けの指針​

ユースケース推奨形式理由
即時失効が重要（金融、決済等）opaqueRevocationが即時反映される
リソースサーバーのパフォーマンス重視jwtIntrospection不要でローカル検証可能
マイクロサービス間通信jwtサービス間でIdPに依存せず検証可能
セキュリティ最優先opaqueトークンに情報が含まれず、漏洩時のリスクが低い

設定例​

テナントレベルでの設定​

curl -X PUT https://api.local.test/v1/management/tenants/{tenant-id}/authorization-server \
  -H "Content-Type: application/json" \
  -d '{
    "extension": {
      "access_token_type": "JWT"
    }
  }'

デフォルト設定​

設定を省略した場合、opaque が適用されます。即時失効が可能なセキュアなデフォルトです。

注意: access_token_type は認可サーバーレベルの設定です。クライアント単位でのオーバーライドはサポートされていません。

まとめ​

要件やセキュリティレベルに応じて、最適なトークン管理方式を選択してください。 特にセキュリティを重視する場合、「ローテーション＋固定」パターンを強く推奨します。 アクセストークン形式は、即時失効の重要度とパフォーマンス要件に応じてopaqueまたはJWTを選択してください。