OAuth 2.0 Token Introspection

Abstract

概要

This specification defines a method for a protected resource to query an OAuth 2.0 authorization server to determine the active state of an OAuth 2.0 token and to determine meta-information about this token. OAuth 2.0 deployments can use this method to convey information about the authorization context of the token from the authorization server to the protected resource.

本仕様は、保護リソースが OAuth 2.0 認可サーバーに問い合わせて、OAuth 2.0 トークンが有効 (active) な状態にあるかどうかを判定し、そのトークンに関するメタ情報を得るための方法を定義する。OAuth 2.0 のデプロイメントは、この方法を使って、トークンの認可コンテキストに関する情報を認可サーバーから保護リソースへ伝えることができる。

1.Introduction

1.はじめに

In OAuth 2.0 [RFC6749], the contents of tokens are opaque to clients. This means that the client does not need to know anything about the content or structure of the token itself, if there is any. However, there is still a large amount of metadata that may be attached to a token, such as its current validity, approved scopes, and information about the context in which the token was issued. These pieces of information are often vital to protected resources making authorization decisions based on the tokens being presented. Since OAuth 2.0 does not define a protocol for the resource server to learn meta-information about a token that it has received from an authorization server, several different approaches have been developed to bridge this gap. These include using structured token formats such as JWT [RFC7519] or proprietary inter-service communication mechanisms (such as shared databases and protected enterprise service buses) that convey token information.

OAuth 2.0 [RFC6749] において、トークンの内容はクライアントにとって不透明 (opaque) である。これは、トークン自体の内容や構造 (そもそも存在するとして) について、クライアントが何も知る必要がないことを意味する。しかし、トークンには依然として、現在の有効性、承認されたスコープ、トークンが発行されたコンテキストに関する情報など、多くのメタデータが付随しうる。これらの情報は、提示されたトークンに基づいて認可判断を行う保護リソースにとって、しばしば不可欠なものである。OAuth 2.0 は、リソースサーバーが認可サーバーから受け取ったトークンのメタ情報を知るためのプロトコルを定義していないため、この隙間を埋めるためにいくつもの異なるアプローチが開発されてきた。たとえば、JWT [RFC7519] のような構造化トークン形式を使うものや、トークン情報を伝える独自のサービス間通信機構 (共有データベースや保護されたエンタープライズサービスバスなど) を使うものがある。

This specification defines a protocol that allows authorized protected resources to query the authorization server to determine the set of metadata for a given token that was presented to them by an OAuth 2.0 client. This metadata includes whether or not the token is currently active (or if it has expired or otherwise been revoked), what rights of access the token carries (usually conveyed through OAuth 2.0 scopes), and the authorization context in which the token was granted (including who authorized the token and which client it was issued to). Token introspection allows a protected resource to query this information regardless of whether or not it is carried in the token itself, allowing this method to be used along with or independently of structured token values. Additionally, a protected resource can use the mechanism described in this specification to introspect the token in a particular authorization decision context and ascertain the relevant metadata about the token to make this authorization decision appropriately.

本仕様は、認可された保護リソースが、OAuth 2.0 クライアントから提示されたトークンについて、そのメタデータの集合を判定するために認可サーバーへ問い合わせることを可能にするプロトコルを定義する。このメタデータには、トークンが現在有効 (active) であるか否か (あるいは期限切れか、その他の理由で失効しているか)、トークンがどのようなアクセス権を持つか (通常は OAuth 2.0 のスコープで伝えられる)、およびトークンが付与された認可コンテキスト (誰がトークンを認可し、どのクライアントに発行されたかを含む) が含まれる。トークンイントロスペクションにより、保護リソースは、この情報がトークン自体に含まれているか否かにかかわらず問い合わせることができ、この方式を構造化されたトークン値と併用することも、それとは独立に使用することもできる。さらに、保護リソースは本仕様に記述する仕組みを用いて、特定の認可判断のコンテキストにおいてトークンをイントロスペクトし、その認可判断を適切に行うためにトークンに関する関連メタデータを確認することができる。

1.1.Notational Conventions

1.1.表記規約

The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document are to be interpreted as described in [RFC2119].

本文書における 'MUST'、'MUST NOT'、'REQUIRED'、'SHALL'、'SHALL NOT'、'SHOULD'、'SHOULD NOT'、'RECOMMENDED'、'NOT RECOMMENDED'、'MAY'、'OPTIONAL' というキーワードは、[RFC2119] に記述されているとおりに解釈される。

Unless otherwise noted, all the protocol parameter names and values are case sensitive.

特に断りのない限り、すべてのプロトコルパラメータ名および値は大文字・小文字を区別する。

1.2.Terminology

1.2.用語

This section defines the terminology used by this specification. This section is a normative portion of this specification, imposing requirements upon implementations.

本節は、本仕様で使用する用語を定義する。本節は本仕様の規範的な部分であり、実装に要件を課すものである。

This specification uses the terms "access token", "authorization endpoint", "authorization grant", "authorization server", "client", "client identifier", "protected resource", "refresh token", "resource owner", "resource server", and "token endpoint" defined by OAuth 2.0 [RFC6749], and the terms "claim names" and "claim values" defined by JSON Web Token (JWT) [RFC7519].

本仕様は、OAuth 2.0 [RFC6749] で定義される「アクセストークン」「認可エンドポイント」「認可グラント」「認可サーバー」「クライアント」「クライアント識別子」「保護リソース」「リフレッシュトークン」「リソースオーナー」「リソースサーバー」「トークンエンドポイント」という用語、および JSON Web Token (JWT) [RFC7519] で定義される「クレーム名」「クレーム値」という用語を使用する。

This specification defines the following terms:

本仕様は次の用語を定義する:

Token Introspection The act of inquiring about the current state of an OAuth 2.0 token through use of the network protocol defined in this document.

トークンイントロスペクション (Token Introspection) 本文書で定義するネットワークプロトコルを用いて、OAuth 2.0 トークンの現在の状態について問い合わせる行為。

Introspection Endpoint The OAuth 2.0 endpoint through which the token introspection operation is accomplished.

イントロスペクションエンドポイント (Introspection Endpoint) トークンイントロスペクション操作を実現する OAuth 2.0 エンドポイント。

2.Introspection Endpoint

2.イントロスペクションエンドポイント

The introspection endpoint is an OAuth 2.0 endpoint that takes a parameter representing an OAuth 2.0 token and returns a JSON [RFC7159] document representing the meta information surrounding the token, including whether this token is currently active. The definition of an active token is dependent upon the authorization server, but this is commonly a token that has been issued by this authorization server, is not expired, has not been revoked, and is valid for use at the protected resource making the introspection call.

イントロスペクションエンドポイントは、OAuth 2.0 トークンを表すパラメータを受け取り、そのトークンが現在有効であるか否かを含む、トークンに関するメタ情報を表す JSON [RFC7159] 文書を返す OAuth 2.0 エンドポイントである。有効なトークンの定義は認可サーバーに依存するが、一般的には、当該認可サーバーによって発行され、期限切れではなく、失効しておらず、イントロスペクション呼び出しを行っている保護リソースでの使用に対して有効なトークンを指す。

The introspection endpoint MUST be protected by a transport-layer security mechanism as described in Section 4. The means by which the protected resource discovers the location of the introspection endpoint are outside the scope of this specification.

イントロスペクションエンドポイントは、4 節で記述するトランスポート層セキュリティ機構によって保護されなければならない (MUST)。保護リソースがイントロスペクションエンドポイントの所在を発見する手段は、本仕様の範囲外である。

2.1.Introspection Request

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

token REQUIRED. The string value of the token. For access tokens, this is the "access_token" value returned from the token endpoint defined in OAuth 2.0 [RFC6749], Section 5.1. For refresh tokens, this is the "refresh_token" value returned from the token endpoint as defined in OAuth 2.0 [RFC6749], Section 5.1. Other token types are outside the scope of this specification.

token REQUIRED。トークンの文字列値。アクセストークンの場合、これは OAuth 2.0 [RFC6749] の 5.1 節で定義されるトークンエンドポイントから返される "access_token" の値である。リフレッシュトークンの場合、これは OAuth 2.0 [RFC6749] の 5.1 節で定義されるトークンエンドポイントから返される "refresh_token" の値である。その他のトークン種別は本仕様の範囲外である。

token_type_hint OPTIONAL. A hint about the type of the token submitted for introspection. The protected resource MAY pass this parameter to help the authorization server optimize the token lookup. If the server is unable to locate the token using the given hint, it MUST extend its search across all of its supported token types. An authorization server MAY ignore this parameter, particularly if it is able to detect the token type automatically. Values for this field are defined in the "OAuth Token Type Hints" registry defined in OAuth Token Revocation [RFC7009].

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

The introspection endpoint MAY accept other OPTIONAL parameters to provide further context to the query. For instance, an authorization server may desire to know the IP address of the client accessing the protected resource to determine if the correct client is likely to be presenting the token. The definition of this or any other parameters are outside the scope of this specification, to be defined by service documentation or extensions to this specification. If the authorization server is unable to determine the state of the token without additional information, it SHOULD return an introspection response indicating the token is not active as described in Section 2.2.

イントロスペクションエンドポイントは、問い合わせにさらなるコンテキストを与えるため、他の任意 (OPTIONAL) のパラメータを受け付けてもよい (MAY)。例えば、認可サーバーは、正しいクライアントがトークンを提示している可能性が高いかを判断するために、保護リソースにアクセスしているクライアントの IP アドレスを知りたい場合がある。このパラメータやその他のパラメータの定義は本仕様の範囲外であり、サービスのドキュメントまたは本仕様の拡張によって定義される。追加情報なしにトークンの状態を判定できない場合、認可サーバーは 2.2 節に記述するとおり、トークンが有効でないことを示すイントロスペクションレスポンスを返すべきである (SHOULD)。

To prevent token scanning attacks, the endpoint MUST also require some form of authorization to access this endpoint, such as client authentication as described in OAuth 2.0 [RFC6749] or a separate OAuth 2.0 access token such as the bearer token described in OAuth 2.0 Bearer Token Usage [RFC6750]. The methods of managing and validating these authentication credentials are out of scope of this specification.

トークンスキャン攻撃を防ぐため、エンドポイントはさらに、このエンドポイントへのアクセスに対して何らかの形の認可を要求しなければならない (MUST)。たとえば、OAuth 2.0 [RFC6749] で記述されるクライアント認証や、OAuth 2.0 Bearer Token Usage [RFC6750] で記述されるベアラートークンのような別個の OAuth 2.0 アクセストークンである。これらの認証クレデンシャルを管理し検証する方法は、本仕様の範囲外である。

For example, the following shows a protected resource calling the token introspection endpoint to query about an OAuth 2.0 bearer token. The protected resource is using a separate OAuth 2.0 bearer token to authorize this call.

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

The following is a non-normative example request:

The following is a non-normative example request:

In this example, the protected resource uses a client identifier and client secret to authenticate itself to the introspection endpoint. The protected resource also sends a token type hint indicating that it is inquiring about an access token.

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

The following is a non-normative example request:

以下は非規範的なリクエスト例である:

2.2.Introspection Response

2.2.イントロスペクションレスポンス

The server responds with a JSON object [RFC7159] in "application/ json" format with the following top-level members.

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

active REQUIRED. Boolean indicator of whether or not the presented token is currently active. The specifics of a token's "active" state will vary depending on the implementation of the authorization server and the information it keeps about its tokens, but a "true" value return for the "active" property will generally indicate that a given token has been issued by this authorization server, has not been revoked by the resource owner, and is within its given time window of validity (e.g., after its issuance time and before its expiration time). See Section 4 for information on implementation of such checks.

active REQUIRED。提示されたトークンが現在有効であるかどうかを示す真偽値。トークンの「有効」状態の詳細は、認可サーバーの実装およびトークンについて保持している情報によって異なるが、"active" プロパティに "true" が返される場合、一般的には、そのトークンがこの認可サーバーによって発行され、リソースオーナーによって失効されておらず、与えられた有効期間内 (たとえば発行時刻より後で、かつ有効期限より前) にあることを示す。このような検査の実装に関する情報は 4 節を参照のこと。

scope OPTIONAL. A JSON string containing a space-separated list of scopes associated with this token, in the format described in Section 3.3 of OAuth 2.0 [RFC6749].

scope OPTIONAL。OAuth 2.0 [RFC6749] の 3.3 節で記述される形式で、このトークンに関連付けられたスコープのスペース区切りリストを含む JSON 文字列。

client_id OPTIONAL. Client identifier for the OAuth 2.0 client that requested this token.

client_id OPTIONAL。このトークンを要求した OAuth 2.0 クライアントのクライアント識別子。

username OPTIONAL. Human-readable identifier for the resource owner who authorized this token.

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

token_type OPTIONAL. Type of the token as defined in Section 5.1 of OAuth 2.0 [RFC6749].

token_type OPTIONAL。OAuth 2.0 [RFC6749] の 5.1 節で定義されるトークンの種別。

exp OPTIONAL. Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token will expire, as defined in JWT [RFC7519].

exp OPTIONAL。JWT [RFC7519] で定義されるとおり、このトークンがいつ期限切れになるかを示す、1970 年 1 月 1 日 UTC からの秒数で測った整数のタイムスタンプ。

iat OPTIONAL. Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token was originally issued, as defined in JWT [RFC7519].

iat OPTIONAL。JWT [RFC7519] で定義されるとおり、このトークンが最初に発行された時刻を示す、1970 年 1 月 1 日 UTC からの秒数で測った整数のタイムスタンプ。

nbf OPTIONAL. Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token is not to be used before, as defined in JWT [RFC7519].

nbf OPTIONAL。JWT [RFC7519] で定義されるとおり、このトークンをそれより前に使用してはならない時刻を示す、1970 年 1 月 1 日 UTC からの秒数で測った整数のタイムスタンプ。

sub OPTIONAL. Subject of the token, as defined in JWT [RFC7519]. Usually a machine-readable identifier of the resource owner who authorized this token.

sub OPTIONAL。JWT [RFC7519] で定義されるトークンの主体 (subject)。通常は、このトークンを認可したリソースオーナーの機械可読な識別子。

aud OPTIONAL. Service-specific string identifier or list of string identifiers representing the intended audience for this token, as defined in JWT [RFC7519].

aud OPTIONAL。JWT [RFC7519] で定義されるとおり、このトークンの意図されたオーディエンスを表す、サービス固有の文字列識別子または文字列識別子のリスト。

iss OPTIONAL. String representing the issuer of this token, as defined in JWT [RFC7519].

iss OPTIONAL。JWT [RFC7519] で定義されるとおり、このトークンの発行者を表す文字列。

jti OPTIONAL. String identifier for the token, as defined in JWT [RFC7519].

jti OPTIONAL。JWT [RFC7519] で定義されるとおり、トークンの文字列識別子。

Specific implementations MAY extend this structure with their own service-specific response names as top-level members of this JSON object. Response names intended to be used across domains MUST be registered in the "OAuth Token Introspection Response" registry defined in Section 3.1.

個別の実装は、この JSON オブジェクトのトップレベルメンバーとして、独自のサービス固有のレスポンス名でこの構造を拡張してもよい (MAY)。ドメインをまたいで使用することを意図したレスポンス名は、3.1 節で定義する "OAuth Token Introspection Response" レジストリに登録されなければならない (MUST)。

The authorization server MAY respond differently to different protected resources making the same request. For instance, an authorization server MAY limit which scopes from a given token are returned for each protected resource to prevent a protected resource from learning more about the larger network than is necessary for its operation.

認可サーバーは、同じリクエストを行う異なる保護リソースに対して、異なる応答をしてもよい (MAY)。たとえば、認可サーバーは、保護リソースがその運用に必要な範囲を超えてより広いネットワークについて知ることを防ぐために、あるトークンのどのスコープを各保護リソースに返すかを制限してもよい (MAY)。

The response MAY be cached by the protected resource to improve performance and reduce load on the introspection endpoint, but at the cost of liveness of the information used by the protected resource to make authorization decisions. See Section 4 for more information regarding the trade off when the response is cached.

レスポンスは、性能を向上させイントロスペクションエンドポイントの負荷を減らすために保護リソースによってキャッシュされてもよい (MAY) が、その代償として、保護リソースが認可判断に用いる情報の鮮度 (liveness) が犠牲になる。レスポンスをキャッシュする場合のトレードオフに関する詳細は 4 節を参照のこと。

For example, the following response contains a set of information about an active token:

たとえば、次のレスポンスは有効なトークンに関する一連の情報を含んでいる:

The following is a non-normative example response:

以下は非規範的なレスポンス例である:

If the introspection call is properly authorized but the token is not active, does not exist on this server, or the protected resource is not allowed to introspect this particular token, then the authorization server MUST return an introspection response with the "active" field set to "false". Note that to avoid disclosing too much of the authorization server's state to a third party, the authorization server SHOULD NOT include any additional information about an inactive token, including why the token is inactive.

イントロスペクション呼び出しが適切に認可されているものの、トークンが有効でない、このサーバー上に存在しない、または保護リソースがその特定のトークンをイントロスペクトすることを許可されていない場合、認可サーバーは "active" フィールドを "false" に設定したイントロスペクションレスポンスを返さなければならない (MUST)。認可サーバーの状態を第三者に過度に開示することを避けるため、認可サーバーは、トークンが無効である理由を含め、無効なトークンに関する追加情報を一切含めるべきではない (SHOULD NOT) ことに注意すること。

The following is a non-normative example response for a token that has been revoked or is otherwise invalid:

以下は、失効された、またはその他の理由で無効なトークンに対する非規範的なレスポンス例である:

2.3.Error Response

2.3.エラーレスポンス

If the protected resource uses OAuth 2.0 client credentials to authenticate to the introspection endpoint and its credentials are invalid, the authorization server responds with an HTTP 401 (Unauthorized) as described in Section 5.2 of OAuth 2.0 [RFC6749].

保護リソースがイントロスペクションエンドポイントへの認証に OAuth 2.0 クライアントクレデンシャルを使用し、そのクレデンシャルが無効である場合、認可サーバーは OAuth 2.0 [RFC6749] の 5.2 節で記述されるとおり HTTP 401 (Unauthorized) で応答する。

If the protected resource uses an OAuth 2.0 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request, the authorization server responds with an HTTP 401 code as described in Section 3 of OAuth 2.0 Bearer Token Usage [RFC6750].

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

Note that a properly formed and authorized query for an inactive or otherwise invalid token (or a token the protected resource is not allowed to know about) is not considered an error response by this specification. In these cases, the authorization server MUST instead respond with an introspection response with the "active" field set to "false" as described in Section 2.2.

無効な、またはその他の理由で不正なトークン (あるいは保護リソースが知ることを許可されていないトークン) に対する、正しく構成され認可された問い合わせは、本仕様ではエラーレスポンスとはみなされないことに注意すること。これらの場合、認可サーバーは代わりに、2.2 節で記述するとおり "active" フィールドを "false" に設定したイントロスペクションレスポンスで応答しなければならない (MUST)。

3.IANA Considerations

3.IANA に関する考慮事項

3.1.OAuth Token Introspection Response Registry

3.1.OAuth Token Introspection Response レジストリ

This specification establishes the "OAuth Token Introspection Response" registry.

本仕様は "OAuth Token Introspection Response" レジストリを設立する。

OAuth registration client metadata names and descriptions are registered by Specification Required [RFC5226] after a two-week review period on the oauth-ext-review@ietf.org mailing list, on the advice of one or more Designated Experts. However, to allow for the allocation of names prior to publication, the Designated Expert(s) may approve registration once they are satisfied that such a specification will be published.

OAuth 登録クライアントメタデータの名前と説明は、oauth-ext-review@ietf.org メーリングリストにおける 2 週間のレビュー期間の後、1 名以上の指名専門家 (Designated Expert) の助言に基づき、Specification Required [RFC5226] によって登録される。ただし、公開前の名前の割り当てを可能にするため、指名専門家は、そのような仕様が公開されると確信できた時点で登録を承認してもよい。

Registration requests sent to the mailing list for review should use an appropriate subject (e.g., "Request to register OAuth Token Introspection Response name: example").

レビューのためにメーリングリストへ送られる登録リクエストは、適切な件名 (例: "Request to register OAuth Token Introspection Response name: example") を使用すべきである。

Within the review period, the Designated Expert(s) will either approve or deny the registration request, communicating this decision to the review list and IANA. Denials should include an explanation and, if applicable, suggestions as to how to make the request successful.

レビュー期間内に、指名専門家は登録リクエストを承認または却下し、その決定をレビューリストと IANA に伝える。却下する場合は、説明と、該当するならばリクエストを成功させるための提案を含めるべきである。

IANA must only accept registry updates from the Designated Expert(s) and should direct all requests for registration to the review mailing list.

IANA は指名専門家からのレジストリ更新のみを受け付けなければならず、登録に関するすべてのリクエストをレビューメーリングリストへ誘導すべきである。

3.1.1.Registration Template

3.1.1.登録テンプレート

Name: The name requested (e.g., "example"). This name is case sensitive. Names that match other registered names in a case insensitive manner SHOULD NOT be accepted. Names that match claims registered in the "JSON Web Token Claims" registry established by [RFC7519] SHOULD have comparable definitions and semantics.

Name: 要求する名前 (例: "example")。この名前は大文字・小文字を区別する。大文字・小文字を区別しない比較で他の登録済みの名前と一致する名前は、受け付けるべきではない (SHOULD NOT)。[RFC7519] によって設立された "JSON Web Token Claims" レジストリに登録されたクレームと一致する名前は、それと同等の定義と意味論を持つべきである (SHOULD)。

Description: Brief description of the metadata value (e.g., "Example description").

Description: メタデータ値の簡潔な説明 (例: "Example description")。

Change controller: For Standards Track RFCs, state "IESG". For other documents, give the name of the responsible party. Other details (e.g., postal address, email address, home page URI) may also be included.

Change controller: Standards Track の RFC については "IESG" と記す。それ以外の文書については、責任者の名前を記す。その他の詳細 (例: 郵便住所、電子メールアドレス、ホームページ URI) を含めてもよい。

Specification document(s): Reference to the document(s) that specify the token endpoint authorization method, preferably including a URI that can be used to retrieve a copy of the document(s). An indication of the relevant sections may also be included but is not required.

Specification document(s): トークンエンドポイント認可方式を規定する文書への参照。できればその文書のコピーを取得するために使える URI を含める。関連する節の指示を含めてもよいが、必須ではない。

3.1.2.Initial Registry Contents

3.1.2.レジストリの初期内容

The initial contents of the "OAuth Token Introspection Response" registry are as follows:

"OAuth Token Introspection Response" レジストリの初期内容は次のとおりである:

o Name: "active"

Name: "active"

o Description: Token active status

Description: トークンの有効状態

o Change Controller: IESG

Change Controller: IESG

o Specification Document(s): Section 2.2 of RFC 7662 (this document).

Specification Document(s): RFC 7662 (本文書) の 2.2 節

o Name: "username"

Name: "username"

o Description: User identifier of the resource owner

Description: リソースオーナーのユーザー識別子

o Change Controller: IESG

Change Controller: IESG

o Specification Document(s): Section 2.2 of RFC 7662 (this document).

Specification Document(s): RFC 7662 (本文書) の 2.2 節

o Name: "client_id"

Name: "client_id"

o Description: Client identifier of the client

Description: クライアントのクライアント識別子

o Change Controller: IESG

Change Controller: IESG

o Specification Document(s): Section 2.2 of RFC 7662 (this document).

Specification Document(s): RFC 7662 (本文書) の 2.2 節

o Name: "scope"

Name: "scope"

o Description: Authorized scopes of the token

Description: トークンの認可されたスコープ

o Change Controller: IESG

Change Controller: IESG

o Specification Document(s): Section 2.2 of RFC 7662 (this document).

Specification Document(s): RFC 7662 (本文書) の 2.2 節

o Name: "token_type"

Name: "token_type"

o Description: Type of the token

Description: トークンの種別

o Change Controller: IESG

Change Controller: IESG

o Specification Document(s): Section 2.2 of RFC 7662 (this document).

Specification Document(s): RFC 7662 (本文書) の 2.2 節

o Name: "exp"

Name: "exp"

o Description: Expiration timestamp of the token

Description: トークンの有効期限のタイムスタンプ

o Change Controller: IESG

Change Controller: IESG

o Specification Document(s): Section 2.2 of RFC 7662 (this document).

Specification Document(s): RFC 7662 (本文書) の 2.2 節

o Name: "iat"

Name: "iat"

o Description: Issuance timestamp of the token

Description: トークンの発行時刻のタイムスタンプ

o Change Controller: IESG

Change Controller: IESG

o Specification Document(s): Section 2.2 of RFC 7662 (this document).

Specification Document(s): RFC 7662 (本文書) の 2.2 節

o Name: "nbf"

Name: "nbf"

o Description: Timestamp before which the token is not valid

Description: それより前はトークンが有効でないタイムスタンプ

o Change Controller: IESG

Change Controller: IESG

o Specification Document(s): Section 2.2 of RFC 7662 (this document).

Specification Document(s): RFC 7662 (本文書) の 2.2 節

o Name: "sub"

Name: "sub"

o Description: Subject of the token

Description: トークンのサブジェクト

o Change Controller: IESG

Change Controller: IESG

o Specification Document(s): Section 2.2 of RFC 7662 (this document).

Specification Document(s): RFC 7662 (本文書) の 2.2 節

o Name: "aud"

Name: "aud"

o Description: Audience of the token

Description: トークンのオーディエンス

o Change Controller: IESG

Change Controller: IESG

o Specification Document(s): Section 2.2 of RFC 7662 (this document).

Specification Document(s): RFC 7662 (本文書) の 2.2 節

o Name: "iss"

Name: "iss"

o Description: Issuer of the token

Description: トークンの発行者

o Change Controller: IESG

Change Controller: IESG

o Specification Document(s): Section 2.2 of RFC 7662 (this document).

Specification Document(s): RFC 7662 (本文書) の 2.2 節

o Name: "jti"

Name: "jti"

o Description: Unique identifier of the token

Description: トークンの一意な識別子

o Change Controller: IESG

Change Controller: IESG

o Specification Document(s): Section 2.2 of RFC 7662 (this document).

Specification Document(s): RFC 7662 (本文書) の 2.2 節

4.Security Considerations

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

Since there are many different and valid ways to implement an OAuth 2.0 system, there are consequently many ways for an authorization server to determine whether or not a token is currently "active". However, since resource servers using token introspection rely on the authorization server to determine the state of a token, the authorization server MUST perform all applicable checks against a token's state. For instance, these tests include the following:

OAuth 2.0 システムの実装には多くの異なる正当な方法があるため、結果として、認可サーバーがトークンが現在「有効」であるかどうかを判定する方法も多数存在する。しかし、トークンイントロスペクションを使用するリソースサーバーはトークンの状態の判定を認可サーバーに依存するため、認可サーバーはトークンの状態に対して適用可能なすべての検査を実施しなければならない (MUST)。たとえば、これらの検査には次のものが含まれる:

o If the token can expire, the authorization server MUST determine whether or not the token has expired.

トークンが期限切れになりうる場合、認可サーバーはトークンが期限切れであるか否かを判定しなければならない (MUST)。

o If the token can be issued before it is able to be used, the authorization server MUST determine whether or not a token's valid period has started yet.

トークンが使用可能になる前に発行されうる場合、認可サーバーはトークンの有効期間が既に開始しているか否かを判定しなければならない (MUST)。

o If the token can be revoked after it was issued, the authorization server MUST determine whether or not such a revocation has taken place.

トークンが発行後に失効されうる場合、認可サーバーはそのような失効が行われたか否かを判定しなければならない (MUST)。

o If the token has been signed, the authorization server MUST validate the signature.

トークンが署名されている場合、認可サーバーは署名を検証しなければならない (MUST)。

o If the token can be used only at certain resource servers, the authorization server MUST determine whether or not the token can be used at the resource server making the introspection call.

トークンが特定のリソースサーバーでのみ使用できる場合、認可サーバーはイントロスペクション呼び出しを行っているリソースサーバーでそのトークンが使用できるか否かを判定しなければならない (MUST)。

If an authorization server fails to perform any applicable check, the resource server could make an erroneous security decision based on that response. Note that not all of these checks will be applicable to all OAuth 2.0 deployments and it is up to the authorization server to determine which of these checks (and any other checks) apply.

認可サーバーが適用可能な検査のいずれかを実施し損ねた場合、リソースサーバーはその応答に基づいて誤ったセキュリティ判断を下す可能性がある。これらの検査のすべてがあらゆる OAuth 2.0 デプロイメントに適用可能というわけではなく、これらの検査 (およびその他の検査) のどれを適用するかは認可サーバーが決定することに注意すること。

If left unprotected and un-throttled, the introspection endpoint could present a means for an attacker to poll a series of possible token values, fishing for a valid token. To prevent this, the authorization server MUST require authentication of protected resources that need to access the introspection endpoint and SHOULD require protected resources to be specifically authorized to call the introspection endpoint. The specifics of such authentication credentials are out of scope of this specification, but commonly these credentials could take the form of any valid client authentication mechanism used with the token endpoint, an OAuth 2.0 access token, or other HTTP authorization or authentication mechanism. A single piece of software acting as both a client and a protected resource MAY reuse the same credentials between the token endpoint and the introspection endpoint, though doing so potentially conflates the activities of the client and protected resource portions of the software and the authorization server MAY require separate credentials for each mode.

保護もスロットリングもされていない場合、イントロスペクションエンドポイントは、攻撃者が有効なトークンを探して一連の候補トークン値を試行する手段となりうる。これを防ぐため、認可サーバーはイントロスペクションエンドポイントへのアクセスを必要とする保護リソースの認証を要求しなければならず (MUST)、保護リソースがイントロスペクションエンドポイントを呼び出すことを明示的に認可されていることを要求すべきである (SHOULD)。そのような認証クレデンシャルの詳細は本仕様の範囲外であるが、一般的には、トークンエンドポイントで用いられる任意の有効なクライアント認証機構、OAuth 2.0 アクセストークン、またはその他の HTTP 認可もしくは認証機構の形をとりうる。クライアントと保護リソースの両方として動作する単一のソフトウェアは、トークンエンドポイントとイントロスペクションエンドポイントの間で同じクレデンシャルを再利用してもよい (MAY) が、そうすることはソフトウェアのクライアント部分と保護リソース部分の活動を混同させる可能性があり、認可サーバーはそれぞれのモードに対して別個のクレデンシャルを要求してもよい (MAY)。

Since the introspection endpoint takes in OAuth 2.0 tokens as parameters and responds with information used to make authorization decisions, the server MUST support Transport Layer Security (TLS) 1.2 [RFC5246] and MAY support additional transport-layer mechanisms meeting its security requirements. When using TLS, the client or protected resource MUST perform a TLS/SSL server certificate check, as specified in [RFC6125]. Implementation security considerations can be found in Recommendations for Secure Use of TLS and DTLS [BCP195].

イントロスペクションエンドポイントは OAuth 2.0 トークンをパラメータとして受け取り、認可判断に使用される情報を応答するため、サーバーは Transport Layer Security (TLS) 1.2 [RFC5246] をサポートしなければならず (MUST)、そのセキュリティ要件を満たす追加のトランスポート層機構をサポートしてもよい (MAY)。TLS を使用する場合、クライアントまたは保護リソースは、[RFC6125] で規定されるとおり TLS/SSL サーバー証明書の検査を実施しなければならない (MUST)。実装上のセキュリティに関する考慮事項は、Recommendations for Secure Use of TLS and DTLS [BCP195] にある。

To prevent the values of access tokens from leaking into server-side logs via query parameters, an authorization server offering token introspection MAY disallow the use of HTTP GET on the introspection endpoint and instead require the HTTP POST method to be used at the introspection endpoint.

アクセストークンの値がクエリパラメータを介してサーバー側のログに漏れることを防ぐため、トークンイントロスペクションを提供する認可サーバーは、イントロスペクションエンドポイントでの HTTP GET の使用を禁止し、代わりにイントロスペクションエンドポイントで HTTP POST メソッドの使用を要求してもよい (MAY)。

To avoid disclosing the internal state of the authorization server, an introspection response for an inactive token SHOULD NOT contain any additional claims beyond the required "active" claim (with its value set to "false").

認可サーバーの内部状態の開示を避けるため、無効なトークンに対するイントロスペクションレスポンスは、必須の "active" クレーム (その値を "false" に設定したもの) 以外の追加のクレームを含むべきではない (SHOULD NOT)。

Since a protected resource MAY cache the response of the introspection endpoint, designers of an OAuth 2.0 system using this protocol MUST consider the performance and security trade-offs inherent in caching security information such as this. A less aggressive cache with a short timeout will provide the protected resource with more up-to-date information (due to it needing to query the introspection endpoint more often) at the cost of increased network traffic and load on the introspection endpoint. A more aggressive cache with a longer duration will minimize network traffic and load on the introspection endpoint, but at the risk of stale information about the token. For example, the token may be revoked while the protected resource is relying on the value of the cached response to make authorization decisions. This creates a window during which a revoked token could be used at the protected resource. Consequently, an acceptable cache validity duration needs to be carefully considered given the concerns and sensitivities of the protected resource being accessed and the likelihood of a token being revoked or invalidated in the interim period. Highly sensitive environments can opt to disable caching entirely on the protected resource to eliminate the risk of stale cached information entirely, again at the cost of increased network traffic and server load. If the response contains the "exp" parameter (expiration), the response MUST NOT be cached beyond the time indicated therein.

保護リソースはイントロスペクションエンドポイントのレスポンスをキャッシュしてもよい (MAY) ため、本プロトコルを用いる OAuth 2.0 システムの設計者は、このようなセキュリティ情報のキャッシュに内在する性能とセキュリティのトレードオフを考慮しなければならない (MUST)。タイムアウトの短い控えめなキャッシュは、(イントロスペクションエンドポイントへの問い合わせ頻度が高くなるため) 保護リソースにより最新の情報を提供するが、その代償としてネットワークトラフィックとイントロスペクションエンドポイントの負荷が増加する。期間の長い積極的なキャッシュは、ネットワークトラフィックとイントロスペクションエンドポイントの負荷を最小化するが、トークンに関する情報が古くなるリスクを伴う。例えば、保護リソースがキャッシュされたレスポンスの値に依拠して認可判断を行っている間に、トークンが失効されることがある。これにより、失効したトークンが保護リソースで使用されうる時間窓が生じる。したがって、許容できるキャッシュの有効期間は、アクセスされる保護リソースの懸念や機微性、およびその間にトークンが失効または無効化される可能性を踏まえて慎重に検討する必要がある。機微性の高い環境では、古いキャッシュ情報のリスクを完全に排除するために保護リソースでのキャッシュを完全に無効化することを選べるが、これもネットワークトラフィックとサーバー負荷の増加という代償を伴う。レスポンスに "exp" パラメータ (有効期限) が含まれる場合、そこに示された時刻を超えてレスポンスをキャッシュしてはならない (MUST NOT)。

An authorization server offering token introspection must be able to understand the token values being presented to it during this call. The exact means by which this happens is an implementation detail and is outside the scope of this specification. For unstructured tokens, this could take the form of a simple server-side database query against a data store containing the context information for the token. For structured tokens, this could take the form of the server parsing the token, validating its signature or other protection mechanisms, and returning the information contained in the token back to the protected resource (allowing the protected resource to be unaware of the token's contents, much like the client). Note that for tokens carrying encrypted information that is needed during the introspection process, the authorization server must be able to decrypt and validate the token to access this information. Also note that in cases where the authorization server stores no information about the token and has no means of accessing information about the token by parsing the token itself, it cannot likely offer an introspection service.

トークンイントロスペクションを提供する認可サーバーは、この呼び出しの中で提示されるトークン値を理解できなければならない。これがどのように行われるかの正確な手段は実装の詳細であり、本仕様の範囲外である。非構造化トークンの場合、これはトークンのコンテキスト情報を含むデータストアに対する単純なサーバー側データベース問い合わせの形をとりうる。構造化トークンの場合、これはサーバーがトークンを解析し、その署名やその他の保護機構を検証し、トークンに含まれる情報を保護リソースへ返す形をとりうる (これにより、保護リソースはクライアントと同様にトークンの内容を知らずに済む)。イントロスペクション処理の中で必要となる暗号化された情報を運ぶトークンについては、認可サーバーはその情報にアクセスするためにトークンを復号し検証できなければならないことに注意すること。また、認可サーバーがトークンに関する情報を何も保持しておらず、トークン自体を解析してトークンに関する情報にアクセスする手段も持たない場合、イントロスペクションサービスを提供することはおそらくできないことにも注意すること。

5.Privacy Considerations

5.プライバシーに関する考慮事項

The introspection response may contain privacy-sensitive information such as user identifiers for resource owners. When this is the case, measures MUST be taken to prevent disclosure of this information to unintended parties. One method is to transmit user identifiers as opaque service-specific strings, potentially returning different identifiers to each protected resource.

イントロスペクションレスポンスには、リソースオーナーのユーザー識別子など、プライバシー上機微な情報が含まれうる。その場合、この情報が意図しない相手に開示されることを防ぐための措置を講じなければならない (MUST)。一つの方法は、ユーザー識別子を不透明なサービス固有の文字列として送信し、場合によっては保護リソースごとに異なる識別子を返すことである。

If the protected resource sends additional information about the client's request to the authorization server (such as the client's IP address) using an extension of this specification, such information could have additional privacy considerations that the extension should detail. However, the nature and implications of such extensions are outside the scope of this specification.

保護リソースが本仕様の拡張を用いて、クライアントのリクエストに関する追加情報 (クライアントの IP アドレスなど) を認可サーバーへ送る場合、そのような情報には追加のプライバシー上の考慮事項が生じうるため、拡張側でそれを詳述すべきである。ただし、そのような拡張の性質と影響は本仕様の範囲外である。

Omitting privacy-sensitive information from an introspection response is the simplest way of minimizing privacy issues.

プライバシー上機微な情報をイントロスペクションレスポンスから省くことが、プライバシー上の問題を最小化する最も単純な方法である。

6.References

6.参照文献

6.1.Normative References

6.1.引用規格

6.2.Informative References

6.2.参考文献

A.Use with Proof-of-Possession Tokens

A.所有証明トークンとの併用

With bearer tokens such as those defined by OAuth 2.0 Bearer Token Usage [RFC6750], the protected resource will have in its possession the entire secret portion of the token for submission to the introspection service. However, for proof-of-possession style tokens, the protected resource will have only a token identifier used during the request, along with the cryptographic signature on the request. To validate the signature on the request, the protected resource could be able to submit the token identifier to the authorization server's introspection endpoint to obtain the necessary key information needed for that token. The details of this usage are outside the scope of this specification and will be defined in an extension to this specification in concert with the definition of proof-of-possession tokens.

OAuth 2.0 Bearer Token Usage [RFC6750] で定義されるようなベアラートークンでは、保護リソースはイントロスペクションサービスへ提出するためのトークンの秘密部分全体を手元に持っている。しかし、所有証明 (proof-of-possession) 型のトークンでは、保護リソースはリクエスト中で使用されたトークン識別子と、リクエストに対する暗号学的署名だけを持つ。リクエストの署名を検証するために、保護リソースはトークン識別子を認可サーバーのイントロスペクションエンドポイントへ提出し、そのトークンに必要な鍵情報を取得できるかもしれない。この利用法の詳細は本仕様の範囲外であり、所有証明トークンの定義と連携して、本仕様の拡張で定義される予定である。

Acknowledgements

謝辞

Thanks to the OAuth Working Group and the User Managed Access Working Group for feedback and review of this document, and to the various implementors of both the client and server components of this specification. In particular, the author would like to thank Amanda Anganes, John Bradley, Thomas Broyer, Brian Campbell, George Fletcher, Paul Freemantle, Thomas Hardjono, Eve Maler, Josh Mandel, Steve Moore, Mike Schwartz, Prabath Siriwardena, Sarah Squire, and Hannes Tschofennig.

本文書へのフィードバックとレビューをいただいた OAuth Working Group および User Managed Access Working Group、ならびに本仕様のクライアントおよびサーバー両コンポーネントの様々な実装者に感謝する。特に、著者は Amanda Anganes、John Bradley、Thomas Broyer、Brian Campbell、George Fletcher、Paul Freemantle、Thomas Hardjono、Eve Maler、Josh Mandel、Steve Moore、Mike Schwartz、Prabath Siriwardena、Sarah Squire、Hannes Tschofennig に感謝したい。