OAuth トークンの設計（アクセス/リフレッシュ/イントロスペクション）

トークン設計は「漏れた後」を前提に決める

OAuth 2.0 のフロー（誰がどの経路でトークンを受け取るか）は OAuth 2.0 の認可フロー内部 で扱いました。本稿はその先、発行されたトークンそのものをどう設計するかを扱います。トークンは必ず漏れうる前提で、形式・寿命・失効・送信者バインディングを組み合わせ、漏洩時の被害時間と被害範囲を最小化するのが設計の目的です。

OAuth には役割の異なる3種のトークンがあります。

• アクセストークン：API（リソースサーバー）に提示し、限定された権限（スコープ）を行使する。短命。
• リフレッシュトークン：アクセストークンが期限切れになったとき、再ログインなしで新しいアクセストークンを得るための長命トークン。認可サーバーにのみ提示する。
• ID トークン：OIDC でユーザーの認証結果を伝える JWT。API のアクセス制御には使わない。詳細は OpenID Connect の信頼モデル を参照。

混同しやすいのが「ID トークンを API 認可に使う」誤りです。ID トークンは**クライアントが受信者（aud）**で、API 宛てではありません。API に渡すのはアクセストークンだけです。

不透明トークン vs JWT

アクセストークンの形式は2系統あります。どちらを選ぶかで、検証方法・失効可能性・漏洩耐性が根本から変わります。

JWT の構造と署名検証の急所は JWT の構造と署名検証 で詳述しています。要点は、JWT は改ざんを検知するが秘匿はしないこと、検証ではアルゴリズムと鍵をサーバー側で固定することです。

選択の指針は明快です。即時失効の要件が強いなら不透明トークン＋イントロスペクション、多数のマイクロサービスが独立に高速検証したいなら JWT。両者を折衷し、外向きには不透明トークンを配り、ゲートウェイで JWT に変換して内部に流す Phantom Token パターンも実務でよく使われます。これは「失効可能性」と「分散検証」の両取りを狙う設計です。

アクセストークンの寿命

アクセストークンの寿命は短いほど安全です。漏洩しても、exp（有効期限）が来れば自動的に使えなくなり、被害時間が有限になるからです。

寿命の典型値:
  アクセストークン   : 5〜15分     ← 漏洩の影響時間を最小化
  リフレッシュトークン: 数日〜数週間 ← ローテーションで都度差し替え
  ID トークン        : 数分        ← 認証直後の一回限りの確認用

ここで「短くすると再認証が頻発して UX が悪化するのでは」という疑問が出ますが、それを吸収するのがリフレッシュトークンです。ユーザーは長命のリフレッシュトークンを使い、裏でアクセストークンを静かに更新するため、再ログインは発生しません。短いアクセストークン寿命のコストは、リフレッシュの仕組みが肩代わりするのがこの設計の肝です。

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

リフレッシュトークンは長命なので、漏洩したときの被害が大きい。これを補うのがローテーション（rotation）です。原理は単純で、リフレッシュトークンを使うたびに新しいものへ差し替え、古いものを失効させる——つまり一度使ったリフレッシュトークンは二度と使えません。

1. クライアントが RT1 でアクセストークンを更新
2. 認可サーバーは AT_new と RT2 を返し、RT1 を失効済みにする
3. 次回はクライアントが RT2 を使う → RT3 が返り、RT2 が失効
   …以降、リフレッシュのたびに番号が進む

ローテーション単体では盗難を防げませんが、**reuse detection（再利用検知）**と組み合わせると強力です。仕組みはこうです。ローテーション済みの古いトークン（RT1）が再び提示されたら、それは「正規ユーザーと窃取者の両方が同じ系列を使っている」証拠とみなし、その系列（token family）全体を即座に失効させます。

なお SPA など public client（client_secret を秘匿できない）でリフレッシュトークンを扱う場合、ローテーションと再利用検知は必須とされます（OAuth 2.0 Security BCP）。トークンの保管は localStorage を避け、HttpOnly Cookie やメモリ内に留めるなど、セッション管理の原理 と同じ Cookie 属性の配慮が要ります。

トークンバインディング（DPoP / mTLS）

ここまでの対策をすべて施しても、標準の Bearer トークンは「持っている者が使える」性質が残ります。盗まれたアクセストークンは、窃取者がそのまま提示するだけで通ってしまう。これを断つのが送信者制約（sender-constrained）トークンで、トークンを特定の鍵に縛り付けます。

DPoP（Demonstrating Proof-of-Possession）の原理は、アクセストークンに「このトークンはこの公開鍵の持ち主専用」という束縛（cnf クレーム＝鍵のサムプリント）を埋めることです。クライアントは API 呼び出しごとに、対象 URL・HTTP メソッド・時刻を含む小さな JWT（DPoP proof）を自分の秘密鍵で署名して添えます。

リクエスト:
  Authorization: DPoP <access_token>   ← cnf に公開鍵のサムプリント
  DPoP: <proof_jwt>                    ← htu/htm/iat を秘密鍵で署名
リソースサーバーの検証:
  1. proof の署名を proof 内の公開鍵で検証
  2. その公開鍵のサムプリントが access_token の cnf と一致するか
  3. htu（URL）・htm（メソッド）が今のリクエストと一致するか、iat が新鮮か

アクセストークンを盗んでも、対応する秘密鍵はクライアント内にしか無いため、窃取者は正しい proof を作れず弾かれます。htu/htm を縛ることで、別の宛先への使い回しも防げます。mTLS は同じ目的を TLS 層で達成し、証明書のハッシュをトークンに埋めて TLS ハンドシェイクで所持を証明します。

失効とイントロスペクション

不透明トークンの真価は即時失効にあります。ログアウト・権限剥奪・漏洩検知の際、認可サーバー側で実体を消せば、次の照会で無効になります。

• 失効（RFC 7009）：クライアントが /revoke エンドポイントにトークンを送り、認可サーバーが無効化する。リフレッシュトークンを失効させると、紐づくアクセストークンも失効するのが推奨動作。
• イントロスペクション（RFC 7662）：リソースサーバーが /introspect にトークンを送り、認可サーバーが active（有効/無効）とスコープ・有効期限・sub などのメタデータを返す。

POST /introspect
  token=<opaque_access_token>
レスポンス:
  { "active": true, "scope": "read:orders", "sub": "user-123", "exp": 1750000000 }
  active が false なら、失効済みか期限切れ → 即拒否

イントロスペクションは毎回ネットワーク往復が発生するため、認可サーバーがボトルネックになりがちです。短い TTL のキャッシュで緩和できますが、キャッシュ期間中は失効が遅延するトレードオフがあります。「失効の即時性」と「検証の性能」は対立する——この緊張関係こそトークン設計の本質です。

スコープ設計

スコープはトークンが行使できる権限の範囲で、最小権限の原則を貫くのが基本です。

• 粒度：read:orders write:orders のように動詞＋リソースで分け、過大な admin 一括スコープを避ける。
• audience（aud）：トークンの宛先 API を aud/resource で限定し、ある API 向けトークンが別 API で使い回せないようにする（Resource Indicators, RFC 8707）。
• 同意：ユーザーが何を許可したか分かる単位で設計し、不要なスコープを既定で要求しない。

まとめ

OAuth トークン設計は「漏れる前提」で被害の時間と範囲を絞る作業です。形式は即時失効が要るなら不透明トークン＋イントロスペクション（RFC 7662）、分散高速検証なら JWT を選び、JWT は寿命を 5〜15 分に抑えることが事実上の失効手段になります。リフレッシュトークンはローテーションと再利用検知を組み合わせ、盗難されても系列ごと失効させて窃取を露見させます。Bearer の弱点は DPoP（RFC 9449）や mTLS（RFC 8705）の送信者バインディングで塞ぎ、盗んでも秘密鍵がなければ使えなくします。失効は RFC 7009、スコープは最小権限と aud 限定で範囲を絞ります。形式・寿命・失効・バインディング・スコープを「失効の即時性 対 検証の性能」というトレードオフの中で組み合わせるのが、堅牢なトークン設計の勘所です。