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

2. Introspection Endpoint (イントロスペクションエンドポイント)

イントロスペクションエンドポイントは、OAuth 2.0 トークンを表すパラメータを受け取り、そのトークンが現在アクティブであるかどうかを含む、トークンに関連するメタ情報を表す JSON [RFC7159] ドキュメントを返す OAuth 2.0 エンドポイントです。アクティブなトークンの定義は認可サーバーに依存しますが、これは一般に、この認可サーバーによって発行され、期限切れになっておらず、取り消されておらず、イントロスペクション呼び出しを行っている保護されたリソースで使用するために有効なトークンです。

イントロスペクションエンドポイントは、セクション 4 で説明されているように、トランスポート層セキュリティメカニズムによって保護されなければなりません (MUST)。保護されたリソースがイントロスペクションエンドポイントの場所を発見する方法は、この仕様の範囲外です。

2.1. Introspection Request (イントロスペクションリクエスト)​

保護されたリソースは、[W3C.REC-html5-20141028] で定義されている "application/x-www-form-urlencoded" データとして送信されるパラメータを持つ HTTP POST [RFC7231] リクエストを使用して、イントロスペクションエンドポイントを呼び出します。保護されたリソースは、トークンを表すパラメータと、認可サーバーの応答を支援するために保護されたリソースが知っている追加のコンテキストを表すオプションのパラメータを送信します。

token : 必須 (REQUIRED)。トークンの文字列値。アクセストークンの場合、これは OAuth 2.0 [RFC6749] セクション 5.1 で定義されているトークンエンドポイントから返された "access_token" 値です。リフレッシュトークンの場合、これは OAuth 2.0 [RFC6749] セクション 5.1 で定義されているトークンエンドポイントから返された "refresh_token" 値です。他のトークンタイプは、この仕様の範囲外です。

token_type_hint : オプション (OPTIONAL)。イントロスペクションのために提出されたトークンのタイプに関するヒント。保護されたリソースは、認可サーバーがトークンの検索を最適化するのを助けるために、このパラメータを渡してもかまいません (MAY)。サーバーが指定されたヒントを使用してトークンを見つけることができない場合、サポートされているすべてのトークンタイプにわたって検索を拡張しなければなりません (MUST)。認可サーバーは、特にトークンタイプを自動的に検出できる場合は、このパラメータを無視してもかまいません (MAY)。このフィールドの値は、OAuth Token Revocation [RFC7009] で定義されている "OAuth Token Type Hints" レジストリで定義されています。

イントロスペクションエンドポイントは、クエリにさらなるコンテキストを提供するために、他のオプション (OPTIONAL) パラメータを受け入れてもかまいません (MAY)。例えば、認可サーバーは、正しいクライアントがトークンを提示している可能性が高いかどうかを判断するために、保護されたリソースにアクセスしているクライアントの IP アドレスを知りたいと思うかもしれません。このパラメータまたは他のパラメータの定義は、この仕様の範囲外であり、サービスドキュメントまたはこの仕様への拡張によって定義されます。認可サーバーが追加情報なしでトークンの状態を判断できない場合、セクション 2.2 で説明されているように、トークンがアクティブではないことを示すイントロスペクション応答を返すべきです (SHOULD)。

トークンスキャン攻撃を防ぐために、エンドポイントは、このエンドポイントにアクセスするために何らかの形式の認可も要求しなければなりません (MUST)。例えば、OAuth 2.0 [RFC6749] で説明されているクライアント認証や、OAuth 2.0 Bearer Token Usage [RFC6750] で説明されているベアラートークンなどの別の OAuth 2.0 アクセストークンです。これらの認証資格情報を管理および検証する方法は、この仕様の範囲外です。

例えば、以下は、保護されたリソースがトークンイントロスペクションエンドポイントを呼び出して、OAuth 2.0 ベアラートークンについて問い合わせている様子を示しています。保護されたリソースは、この呼び出しを認可するために別の OAuth 2.0 ベアラートークンを使用しています。

以下は、非規範的なリクエストの例です:

POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer 23410913-abewfq.123483

token=2YotnFZFEjr1zCsicMWpAA

この例では、保護されたリソースは、クライアント識別子とクライアントシークレットを使用して、イントロスペクションエンドポイントに対して自身を認証しています。保護されたリソースは、アクセストークンについて問い合わせていることを示すトークンタイプヒントも送信しています。

以下は、非規範的なリクエストの例です:

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

2.2. Introspection Response (イントロスペクションレスポンス)​

サーバーは、以下のトップレベルメンバーを持つ "application/json" 形式の JSON オブジェクト [RFC7159] で応答します。

active : 必須 (REQUIRED)。提示されたトークンが現在アクティブであるかどうかを示すブール値のインジケーター。トークンの "active" 状態の詳細は、認可サーバーの実装とそれがトークンについて保持している情報によって異なりますが、"active" プロパティに対して "true" 値が返されることは、一般に、そのトークンがこの認可サーバーによって発行され、リソースオーナーによって取り消されておらず、有効な時間枠内にあること (例えば、発行時刻の後で有効期限の前) を示します。このようなチェックの実装に関する情報については、セクション 4 を参照してください。

scope : オプション (OPTIONAL)。このトークンに関連付けられたスペース区切りのスコープのリストを含む JSON 文字列。OAuth 2.0 [RFC6749] のセクション 3.3 で説明されている形式です。

client_id : オプション (OPTIONAL)。このトークンを要求した OAuth 2.0 クライアントのクライアント識別子。

username : オプション (OPTIONAL)。このトークンを認可したリソースオーナーの人間が読める識別子。

token_type : オプション (OPTIONAL)。OAuth 2.0 [RFC6749] のセクション 5.1 で定義されているトークンのタイプ。

exp : オプション (OPTIONAL)。JWT [RFC7519] で定義されているように、このトークンの有効期限を示す、1970年1月1日 UTC からの秒数で測定された整数タイムスタンプ。

iat : オプション (OPTIONAL)。JWT [RFC7519] で定義されているように、このトークンが最初に発行された日時を示す、1970年1月1日 UTC からの秒数で測定された整数タイムスタンプ。

nbf : オプション (OPTIONAL)。JWT [RFC7519] で定義されているように、このトークンがそれ以前に使用されてはならない日時を示す、1970年1月1日 UTC からの秒数で測定された整数タイムスタンプ。

sub : オプション (OPTIONAL)。JWT [RFC7519] で定義されているトークンのサブジェクト (Subject)。通常、このトークンを認可したリソースオーナーの機械可読識別子。

aud : オプション (OPTIONAL)。JWT [RFC7519] で定義されているように、このトークンの意図されたオーディエンス (Audience) を表すサービス固有の文字列識別子または文字列識別子のリスト。

iss : オプション (OPTIONAL)。JWT [RFC7519] で定義されているように、このトークンの発行者 (Issuer) を表す文字列。

jti : オプション (OPTIONAL)。JWT [RFC7519] で定義されているトークンの文字列識別子。

特定の実装は、この JSON オブジェクトのトップレベルメンバーとして独自のサービス固有の応答名を使用してこの構造を拡張してもかまいません (MAY)。ドメイン間でまたがって使用されることを意図した応答名は、セクション 3.1 で定義されている "OAuth Token Introspection Response" レジストリに登録されなければなりません (MUST)。

認可サーバーは、同じリクエストを行う異なる保護されたリソースに対して異なる応答をしてもかまいません (MAY)。例えば、認可サーバーは、保護されたリソースがその動作に必要な以上の大規模なネットワークに関する情報を知ることを防ぐために、各保護されたリソースに対して特定のトークンから返されるスコープを制限してもかまいません (MAY)。

応答は、パフォーマンスを向上させ、イントロスペクションエンドポイントへの負荷を軽減するために保護されたリソースによってキャッシュされてもかまいません (MAY) が、保護されたリソースが認可決定を行うために使用する情報のライブネス (鮮度) が犠牲になります。応答がキャッシュされる場合のトレードオフに関する詳細については、セクション 4 を参照してください。

例えば、以下の応答には、アクティブなトークンに関する一連の情報が含まれています:

以下は、非規範的な応答の例です:

HTTP/1.1 200 OK
Content-Type: application/json

{
 "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" に設定されたイントロスペクション応答を返さなければなりません (MUST)。認可サーバーの状態を第三者に過度に開示することを避けるために、認可サーバーは、トークンがアクティブでない理由を含め、非アクティブなトークンに関する追加情報を含めるべきではありません (SHOULD NOT)。

以下は、取り消されたか、その他の理由で無効なトークンに対する非規範的な応答の例です:

HTTP/1.1 200 OK
Content-Type: application/json

{
 "active": false
}

2.3. Error Response (エラーレスポンス)​

保護されたリソースが、イントロスペクションエンドポイントに対して認証するために OAuth 2.0 クライアント資格情報を使用し、その資格情報が無効である場合、認可サーバーは、OAuth 2.0 [RFC6749] のセクション 5.2 で説明されているように、HTTP 401 (Unauthorized) で応答します。

保護されたリソースが、イントロスペクションエンドポイントへの呼び出しを認可するために OAuth 2.0 ベアラートークンを使用し、認可に使用されたトークンに十分な権限が含まれていないか、このリクエストに対して無効である場合、認可サーバーは、OAuth 2.0 Bearer Token Usage [RFC6750] のセクション 3 で説明されているように、HTTP 401 コードで応答します。

アクティブでない、またはその他の理由で無効なトークン (または保護されたリソースが知ることを許可されていないトークン) に対する、適切に形成され認可されたクエリは、この仕様ではエラー応答とは見なされないことに注意してください。これらの場合、認可サーバーは代わりに、セクション 2.2 で説明されているように、"active" フィールドが "false" に設定されたイントロスペクション応答で応答しなければなりません (MUST)。

に最終更新