RFC 7662 - OAuth 2.0 Token Introspection

概要

RFC 7662 は、OAuth 2.0 においてリソースサーバーが認可サーバーに対してトークンの状態を照会するプロトコル（Token Introspection）を定義している。2015年10月に IETF によって標準化された。

OAuth 2.0（RFC 6749）では、アクセストークンの形式や内部構造はリソースサーバーに対して不透明（opaque）であることが多く、リソースサーバーがトークンの有効性・スコープ・メタデータを検証する標準的な手段が存在しなかった。本仕様はその問題を解決し、認可サーバーとリソースサーバーの間でトークン情報を交換するための標準インターフェースを提供する。

解決する課題

トークンの不透明性問題

OAuth 2.0 の標準仕様では、アクセストークンはクライアントに対して不透明な文字列として扱われる。リソースサーバーが受け取ったトークンについて、以下の情報を取得する統一的な方法が定義されていなかった：

• トークンが現在も有効か（失効・期限切れ・失効済みでないか）
• トークンに付与されたスコープ
• トークンを要求したクライアントの識別子
• トークンの対象ユーザー（リソースオーナー）

JWT に依存しない検証

JWT（RFC 7519）形式のトークンであれば、リソースサーバーが署名を検証し自律的にクレームを読み取ることも可能だが、すべての環境で JWT を使用できるわけではない。Token Introspection は、トークン形式に依存しない統一的な検証メカニズムを提供する。

主要概念・用語

用語	説明
Introspection Endpoint	認可サーバーが提供するトークン照会エンドポイント
Active Token	認可サーバーによって現在有効と判断されるトークン。有効期限内で失効しておらず、対象リソースサーバーに対して使用可能な状態
Token Type Hint	リクエスト時に提供できるトークン種別のヒント（access_token, refresh_token など）。サーバーの検索効率化に使用される
Opaque Token	内部構造を持たないランダム文字列のトークン。JWT とは対照的に、リソースサーバーがトークン自体から情報を読み取れない

プロトコルフロー

フローの説明

1. クライアントが Bearer トークンを付けてリソースサーバーの API を呼び出す
2. リソースサーバーは認可サーバーの Introspection Endpoint に HTTP POST でトークンを送信する
3. 認可サーバーはトークンの有効性（期限・失効・署名等）を検証する
4. 認可サーバーはトークンのアクティブ状態とメタデータを JSON で返す
5. リソースサーバーはレスポンスに基づいてアクセスを許可または拒否する

エンドポイント仕様

リクエスト

Introspection Endpoint への HTTP POST リクエスト。

• メソッド: POST
• Content-Type: application/x-www-form-urlencoded
• 認証: 必須（クライアント認証または Bearer トークン）

リクエストパラメータ:

パラメータ	必須	説明
token	必須	照会対象のトークン値
token_type_hint	任意	トークン種別のヒント（access_token, refresh_token 等）

リクエスト例:

POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=mF_9.B5f-4.1JqM&token_type_hint=access_token

レスポンス

Content-Type: application/json

レスポンスフィールド:

フィールド	型	必須	説明
active	Boolean	必須	トークンが現在アクティブかどうか
scope	String	任意	スペース区切りのスコープリスト
client_id	String	任意	トークンを要求したクライアント識別子
username	String	任意	リソースオーナーのユーザー識別子
token_type	String	任意	トークン種別（Bearer 等）
exp	Number	任意	有効期限（Unix タイムスタンプ）
iat	Number	任意	発行日時（Unix タイムスタンプ）
nbf	Number	任意	使用開始日時（Unix タイムスタンプ）
sub	String	任意	トークンの主体（Subject）
aud	String/Array	任意	対象オーディエンス
iss	String	任意	トークン発行者（Issuer）
jti	String	任意	トークン固有識別子（JWT ID）

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

{
  "active": true,
  "client_id": "l238j323ds-23ij4",
  "username": "jdoe",
  "scope": "read write dolphin",
  "sub": "Z5O3upPC88QrAjx00dis",
  "aud": "https://protected.example.net/resource",
  "iss": "https://server.example.com/",
  "exp": 1419356238,
  "iat": 1419350238,
  "token_type": "Bearer",
  "jti": "116d9b68-5645-4c3e-b5d9-7b2a2a2a2a2a"
}

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

{
  "active": false
}

仕様では、無効なトークンに対しては active: false のみを返し、無効である理由（期限切れ・失効・存在しない等）は開示しないことが推奨されている。これは情報漏洩を防ぐためである。

token_type_hint の処理

token_type_hint パラメータは、認可サーバーがトークンを効率的に検索するためのヒントとして機能する。

認可サーバーは token_type_hint を必ず尊重する義務はなく、あくまで検索の最適化ヒントとして扱う。

セキュリティに関する考慮事項

認証の必須化

Introspection Endpoint は必ず認証を要求しなければならない。認証なしでアクセスを許可すると、攻撃者がランダムなトークン値を試行する「トークンスキャン攻撃」が可能になる。

認可サーバーによる検証項目

認可サーバーは、active: true を返す前に以下のすべてを確認する必要がある：

• トークンの有効期限（exp）が過ぎていないこと
• 使用開始日時（nbf）を過ぎていること
• トークンが失効（revoke）されていないこと
• 署名付きトークンの場合は署名が有効であること
• リクエストしたリソースサーバーに対してトークンが使用可能であること

TLS の要件

Introspection Endpoint は TLS による保護が必須である。仕様では TLS 1.2 以上のサポートが求められており、クライアント（リソースサーバー）はサーバー証明書の検証を実施しなければならない。

レスポンスのキャッシング

リソースサーバーはパフォーマンス向上のためにレスポンスをキャッシュできるが、以下の制約に従う必要がある：

• exp フィールドが含まれる場合、その時刻を超えたキャッシュは禁止
• トークンが途中で失効される可能性を考慮し、過度に長いキャッシュ期間は避けるべき

POST メソッドの使用

GET ではなく POST を使用することで、トークン値がサーバーログや URL 履歴に記録されることを防ぐ。

プライバシーへの配慮

Introspection レスポンスには、ユーザー識別子（sub, username）などの個人情報が含まれる可能性がある。複数のリソースサーバーが同一の認可サーバーを使用する環境では、リソースサーバーごとに異なる識別子（Pairwise Pseudonymous Identifier）を返すなどの対策を検討すべきである。

関連仕様

仕様	関係
RFC 6749	OAuth 2.0 の基盤仕様。アクセストークンの概念を定義
RFC 6750	Bearer トークンの使用方法。Token Introspection のリクエストでも使用可能
RFC 7519	JWT。Introspection レスポンスのフィールドは JWT クレームと互換
RFC 7009	Token Revocation。失効したトークンは Introspection で active: false を返す
RFC 8414	Authorization Server Metadata。Introspection Endpoint の URL を公開する際に使用

参考文献

• RFC 7662 原文