Skip to content

MS_TokenIntrospection

Jump to bottom
nishi_74322014 edited this page Sep 1, 2026 · 1 revision

OAuth 2.0 Token Introspection

概要

OAuth 2.0 コア仕様を補足。

トークン（refresh_token, access_token）のメタデータ（JSON）を取得する
メカニズム（Token Introspection）
（Resource Server が Client から受け取った Token のメタデータを
Authorization Server に要求する方法）。

目的

以下のトークンのメタデータのセットを判断する。

  • 期限、無効化
  • アクセス権（scope）
  • 承認者（Issuer）
  • 対象クライアント（audience）

シーケンス

  1. Resource Server が Authorization Server にトークンが有効か問い合わせる。
  2. Authorization Server が Resource Server にトークンの有効性を回答する。

補足（いつ必要になるか）: Introspection が必要になるのは、
アクセス トークンが「ハンドル型」の場合である。

トークン形式 検証方法
自己完結型（JWT） Resource Server が署名を検証するだけで完結（Introspection 不要）
ハンドル型（ランダム文字列） 中身が無いので、Authorization Server に問い合わせるしかない

それぞれのトレードオフは次のとおり。

自己完結型（JWT） ハンドル型 + Introspection
性能 速い（ネットワーク往復なし） 遅い（毎回問い合わせ）
即時失効 できない（有効期限まで有効） できる
トークン サイズ 大きい 小さい
情報漏洩 中身が読める（Base64url） 読めない

**「即時失効が要件かどうか」**が最大の分かれ目である。
OAuth 2.0 Token Revocationと組み合わせて
初めて意味を持つ点に注意。

仕様

  • Authorization Server に照会することを許可するプロトコルを定義。
  • メタデータを取得するメカニズムには、
    SAML、JWT、独自のサービス間通信メカニズムなどの
    構造化トークンフォーマットの使用が含まれる。

Introspection Endpoint

  • Authorization Endpoint の規則と同様
    • HTTP 要求の平文認証情報の送信
    • SSL/TLS（サーバ証明）の利用
  • 自動検出など、URL を取得する手段は、この仕様の範囲外

Request

HTTP POST 要求（application/x-www-form-urlencoded）を使用して、
以下のパラメタを Introspection Endpoint に送信する。

  • 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

移行メモ（正誤）: 元ページの Request 節の説明が
「取り消したいトークン」「失効のためのトークンのタイプに関するヒント」と
なっており、また「Revocation Endpoint に送信する」と書かれていたが、
これはOAuth 2.0 Token Revocationからの
コピー時の取り違えである。上記のとおり訂正した。

Process

  • クライアント認証
  • トークン検証

補足（Introspection Endpoint の保護は必須）: この
エンドポイントは保護されていなければならない。
誰でも叩けると、

  • トークンの総当たり判定（有効なトークンを探せる）
  • 有効なトークンの中身の窃取（sub / scope が漏れる）

が可能になる。RFC 7662 も認証を MUST としている。
Resource Server ごとにクレデンシャルを発行し、
自分に向けられたトークン以外は照会させない（aud を確認する）
設計が望ましい。

Response

application/json

成功時のパラメタ

# パラメタ 説明
1 iss 発行者
2 token_type トークンのタイプ
3 client_id client_id
4 aud Client の可読識別子（≠ client_id）
5 sub Resource Owner の機械可読識別子
6 username Resource Owner の人間可読識別子
7 exp 有効期限
8 iat 発行日時
9 nbf Not Before タイムスタンプ
10 active true / false（唯一の必須パラメタ）
11 scope スペース区切りの scope リスト
12 jti トークン識別子

有効な場合の例。

{
  "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,
  "extension_field": "twenty-seven"
}

無効な場合の例。

{
  "active": false
}

補足（無効なトークンでも 200 を返す）: 「トークンが無効」でも
HTTP 200 + {"active": false} を返すのが仕様である。
404 や 401 を返してはならない。

理由は情報を与えないためで、
「存在しないトークン」と「期限切れのトークン」と
「失効させられたトークン」を区別させない。
攻撃者にヒントを与えない設計になっている。

一方、401 を返すのはクライアント認証に失敗したときである。
この 2 つを取り違えないこと。

失敗時

  • ケース: クライアント認証に失敗 / トークン検証に失敗
  • レスポンス: HTTP 401 (Unauthorized)、OAuth 2.0 の
    Error Response のエラーコードを返す。

実装

参考

Tags: 移行, IT国際標準, 認証基盤, クレームベース認証, OAuth

このWikiは「Open棟梁Project」,「OSSコンソーシアム 開発基盤部会」によって運営されています。

NetDevInfraWiki

マイクロソフト系技術情報 Wiki
Open 棟梁 Wiki

（未着手）

開発基盤部会 Wiki

移行管理: DONE ／ TODO

Clone this wiki locally