OAuth 2.0トークンイントロスペクション（RFC 7662）

トークンイントロスペクション（RFC 7662）

アクセストークンが不透明な文字列（自己完結型JWTではない）の場合、リソースサーバーはローカルで検証できません。トークンイントロスペクションは、リソースサーバーがトークンがアクティブかどうか、誰に発行されたか、どのスコープを持つかを確認するために呼び出す標準APIエンドポイントを提供します。

イントロスペクションリクエスト

POST /introspect HTTP/1.1
Host: auth.example.com
Authorization: Basic czZCaGRSa3F0MzoZ...
Content-Type: application/x-www-form-urlencoded

token=2YotnFZFEjr1zCsicMWpAA&token_type_hint=access_token

アクティブなトークンのレスポンス

{
  "active": true,
  "scope": "read write",
  "client_id": "s6BhdRkqt3",
  "username": "johndoe",
  "token_type": "Bearer",
  "exp": 1709123456,
  "iat": 1709119856,
  "sub": "user-12345",
  "aud": "https://api.example.com",
  "iss": "https://auth.example.com"
}

非アクティブなトークンのレスポンス

{
  "active": false
}

主要なレスポンスフィールド

フィールド	説明
active	Boolean — 唯一の必須フィールド。トークンが有効かどうかを示す。
scope	トークンに関連付けられたスペース区切りのスコープ
client_id	トークンが発行されたクライアント
username	リソースオーナーの人間が読める識別子
exp	有効期限（Unixタイムスタンプ）
sub	サブジェクト識別子（ユーザーID）
aud	トークンの意図された対象者

JWT vs 不透明トークン

	JWT	不透明トークン
検証	ローカル（署名検証）	リモート（イントロスペクションエンドポイント）
パフォーマンス	高速（ネットワーク呼び出しなし）	低速（リクエストごとのネットワーク呼び出し、キャッシュ可能）
取り消し	困難（有効期限まで）	即時（イントロスペクションがactive=falseを返す）
サイズ	大きい（ペイロード含む）	小さい（参照のみ）

イントロスペクションの使用場面

• 即時のトークン取り消しが必要な場合
• トークンが不透明な参照の場合
• リソースサーバーがトークンに関する認可サーバーのメタデータを必要とする場合
• レイテンシーを軽減するためにキャッシュ（例：30-60秒）と組み合わせ可能