OAuth 2.0 Token Revocation

Abstract

このドキュメントは、OAuth 認可サーバのための追加エンドポイントを提案する。 そのエンドポイントは事前に取得されているリフレッシュトークンあるいはアクセストークンが不要になったことを認可サーバへ通知することをクライアントに許可する。 これは認可サーバにセキュリティクレデンシャルを削除させる。 無効化リクエストは実際のトークンと、もし該当するものがあれば同じ認可に基づく他のトークンを無効にする。

Status of this Memo

This is an Internet Standards Track document.

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741.

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7009.

Copyright Notice

Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

1.  はじめに
2.  表記規約
3.  Token Revocation
    3.1.  Revocation Request
    3.2.  Revocation Response
        3.2.1.  Error Response
    3.3.  Cross-Origin Support
4.  Implementation Note
5.  IANA Considerations
    5.1.  OAuth Extensions Error Registration
        5.1.1.  The "unsupported_token_type" Error Value
        5.1.2.  OAuth Token Type Hint Registry
            5.1.2.1.  Registration Template
            5.1.2.2.  Initial Registry Contents
6.  Security Considerations
7.  Acknowledgements
8.  翻訳者
9.  References
    9.1.  Normative References
    9.2.  Informative References
    9.3.  翻訳プロジェクト
§  Authors' Addresses

1.  はじめに

OAuth 2.0 core specification [RFC6749] (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) はクライアントがリフレッシュトークンとアクセストークンを取得するためにいくつかの方法が定義している。 この仕様書は両タイプのトークンを取り消すための仕組みによって core specification を補足する。 トークンはリソースオーナーによってクライアントに発行された認可を表している文字列である。 無効化リクエストは、実際のトークンと、もし該当するものがあれば同じ認可に基づくその他のトークンとその認可自体を無効にする。

エンドユーザの視点から、OAuth はしばしばあるサイトやアプリケーションへのログインのために用いられる。 この無効化の仕組みは、エンドユーザがログアウト、アイデンティティの切り替え、あるいは各アプリケーションがアンインストールされた場合に、クライアントにそのトークンを無効にさせる。 トークンが不要になったという認可サーバへの通知は、認可サーバにトークン（例えば、セッションデータ）と認可に関連したデータを取り消させる。 この振る舞いは、エンドユーザが気づいていない特定のクライアントのまだ有効な認可があるという状況を防ぐ。 この方法で、トークンの無効化は放棄されているトークンの乱用を防ぎ、認可サーバがエンドユーザに送ったかもしれない認可の一覧で、無効になった認可をみつける必要がないので、より良いエンドユーザの体験を促進する。

2.  表記規約

このドキュメントで用いられているキーワード「MUST（しなければならない）」、「MUST NOT（してはいけない）」、「REQUIRED（必須である）」、「SHALL（するものとする）」、「SHALL NOT（しないものとする）」、「SHOULD（すべきである）」、「SHOULD NOT（すべきではない）」、「RECOMMENDED（推奨される）」、「MAY（してもよい）」、「OPTIONAL（任意である）」は RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119] に述べられている通りに解釈する。

3.  Token Revocation

実装はリフレッシュトークンの無効化はサポートしなければならなく（MUST）、アクセストークンの無効化はサポートすべきである（SHOULD）(Implementation Note (Implementation Note) を参照)。

クライアントは、トークン無効化エンドポイント URL に HTTP POST リクエストすることによって特定のトークンを取り消しを要請する。 この URL は Section 3.1 [RFC6749] (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) に与えられた規則に従わなければならない（SHOULD）。クライアントはその URL が HTTPS URL であることを検証しなければならない（MUST）。

無効化エンドポイントの場所を得るための方法はこの仕様書の範囲外である。 例えば、クライアント開発者はサーバのドキュメントを調べてもよく、もしくは自動検出を使ってもよい。 このエンドポイントはセキュリティクレデンシャルを取り扱っている際には、エンドポイントの場所は信頼できる資料から得られる必要がある。

トークン無効化エンドポイントへのリクエストは、HTTP リクエスト中に平文クレデンシャルの伝達を生じるため、トークン無効化エンドポイントのための URL は HTTPS でなければならない（MUST）。 認可サーバは、Section 1.6 [RFC6749] (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) のバージョンに準拠した Transport Layer Security（TLS）を利用しなければならない（MUST）。 実装のセキュリティ要求に合った追加の transport-layer security 機構もサポートしてもよい（MAY）。

トークン無効化エンドポイントのホストが HTTP 経由で到達可能ならば、HTTP でも無効化サービスも提供すべきである（SHOULD）が、トークン無効化エンドポイントとしてこの URI を明示してはいけない（MUST NOT）。 HTTP 経由でのトークン無効化エンドポイントの提供は、誤って HTTP 経由で送信されたトークンも期待通り無効化されることを保証する。

3.1.  Revocation Request

クライアントは HTTP リクエストエンティティボディに "application/x-www-form-urlencoded" 形式を使った以下のパラメータを含んでいるリクエストを構成する：

token

必須（REQUIRED）。クライアントが無効化したいトークン。

token_type_hint

任意である（OPTIONAL）。無効化のために送信されるトークンのタイプについてのヒント。 クライアントは認可サーバがトークンを効率的に発見するための補助としてこのパラメータを送ってもよい（MAY）。 サーバが与えられたヒントを使っているトークンが特定できない場合、サポートしているトークンタイプ全てにおける検索を施さなければならない（MUST）。 認可サーバが自動的にトークンタイプをみつけることができるならば、このパラメータを無視してもよい（MAY）。 この仕様は2つの値を定義している：

• access_token： Section 1.4 の [RFC6749] (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) にアクセストークンとして定義されている。
• refresh_token： Section 1.5 の [RFC6749] (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) にリフレッシュトークンとして定義されている。

特定の実装、プロファイル、この仕様の拡張機能は Section 5.1.2 (OAuth Token Type Hint Registry) で定義されているレジストリを利用してこのパラメータの他の値を定義してもよい（MAY）。

クライアントは [RFC6749] (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) の Section 2.3 に説明されている認証クレデンシャルも含んでもよい。

例えば、クライアントは以下のようなリクエストでリフレッシュトークンの無効化を要求してもよい。

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

  token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token

認可サーバは始めに（非公開なクライアントの場合）クライアントクレデンシャルの有効性を確認してから無効化を要求したクライアントに発行されたトークンかどうかを検証する。 この有効性の確認に失敗した場合、そのリクエストは拒否され、そのクライアントは後述の認可サーバによってエラーが通知される。

次に、認可サーバはそのトークを無効にする。その無効はただちにおこなわれ、そのトークンは無効化後は再び利用できなくなる。 実際には、例えば、数台のサーバがその無効化について認知しているが、他のサーバが認知してない間、実際には通信遅延してもよい。 実装者は受け口を最小限にすべきであり、クライアントはサーバから HTTP 200 レスポンスの受信後にトークンを利用しようとしてはいけない。

認可サーバの無効化ポリシーによって、特定のトークンの無効化は関連したトークンとその元となる認可の無効化を行ってもよい。 特定のトークンがリフレッシュトークンで認可サーバがアクセストークンの無効化をサポートする場合には、認可サーバはその同じ認可のもととなる全てのアクセストークンを無効にすべきでる（SHOULD）（ Implementation Note (Implementation Note) を参照）。 要求を満たしたトークンがアクセストークンであった場合には、サーバは同様に各リフレッシュトークンを無効化してもよい（MAY）。

参考：[RFC6749] (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) に遵守したクライアントは随時予期せぬトークンの無効化を扱うための準備をしなければならない。 このドキュメントに明記されている無効化の仕組みとは別に、リソースオーナーは認可を無効化してもよく、あるいは認可サーバはセキュリティ上の脅威を軽減するためにトークンを無効にしてもよい。 このようなトークンの無効化を段階的に行うことに関して異なるサーバポリシーを持つことによって互換性の問題を提起すべきではない。

3.2.  Revocation Response

トークンが正常に無効化されるもしくはクライアントが無効なトークンを送信した場合、認可サーバは HTTP ステータスコード 200 を返却する。

参考：エラーを返してもクライアントは特に適切はエラー処理はできないため、無効なトークンが送られてきてもエラーレスポンスを返してはいけない。 さらに、無効化リクエストの目的は、当該トークンが無効であれば、成功しているといえる。

レスポンスコードが必要な情報を全て示しているため、クライアントはレスポンスボディーの内容を無視すること。

無効なトークンタイプのヒントの値は認可サーバによって無視され、無効化レポンスに影響してはいけない。

3.2.1.  Error Response

エラーの説明は [RFC6749] (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) の Section 5.2 の定義に従う。 以下の追加エラーコードはトークン無効化エンドポイントのために定義されている。

unsupported_token_type

: 認可サーバは提示されたトークンタイプの無効化はサポートしてはいけない。 つまり、クライアントはこの機能をサポートしていないサーバ上でアクセストークンの無効化を試したということである。

サーバが HTTP ステータスコード 503 で応答した場合、クライアントはそのトークンがまだ存在しているとみなし、適切な遅延の後再び試してもよい。 サーバは、サービスがどのくらいの間利用できないと想定されているかを示す "Retry-After" ヘッダーを含んでもよい。

3.3.  Cross-Origin Support

ユーザエージェントベースアプリケーションとの組み合わせで使用することを目的とする場合、無効化エンドポイントは Cross-Origin Resource Sharing(CORS) (Kesteren, A., “Cross-Origin Resource Sharing,” April 2012.) をサポートしてもよい。（MAY）。

加えて、レガシーなユーザエージェントとの互換性のために、以下のパラメータをつかった GET リクエストを許可することによって JSONP (Ippolito, B., “Remote JSON - JSONP,” December 2005.) をサポートしてもよい（MAY）:

callback

任意である（OPTIONAL）。JavaScript 関数の修飾名。

例えば、クライアントは以下のリクエスト（改行は表記のためである）でアクセストークンの無効化をリクエストできる:

  https://example.com/revoke?token=agabcdefddddafdd&
  callback=package.myCallback

Successful response:

  package.myCallback();

Error response:

  package.myCallback({"error":"unsupported_token_type"});

クライアントは、JSONP を利用する場合、悪意のある無効化エンドポイントがクライアントへ悪意あるコードの注入を試みるかもしれないということを認識すべきである。

4.  Implementation Note

OAuth 2.0 はアクセストークンの形式を柔軟に実装可能にしている。 アクセストークンは、リソースサーバが認可サーバとのインタラクションなしにトークンの有効性を検証できるよう、self-contained であってもよい。 また、アクセストークンを参照 (handle) として、アクセストークンに紐づく認可情報を認可サーバーに問い合わせるように設計することもできる。 この結果リソースサーバは、クライアントがアクセストークンを提供するたびにアクセストークンの内容を取り出すためそれぞれの認可サーバへのリクエストを発行する必要がある。

選択肢はこれらに限ったものではないが、この2つの違いはトークン無効化の仕組みにも影響する。 後者の場合、認可サーバは、リソースサーバが当該トークンを認可サーバに問い合わせたタイミングで、発行済トークンが無効であることを伝えることができる。 前者はの場合、即時のアクセストークンの無効化が望まれるとき、認可サーバとリソースサーバとの間でいくつかの（現在は標準化されていない）エンドポイントのインタラクションが使用されるかもしれない。 また、そういったインタラクションを行う代わりに、有効期限の短いアクセストークンを発行し、適宜リフレッシュトークンを用いてリフレッシュさせるようにすることもできる。 そうすることで、認可サーバはトークンが無効化された際に発行済アクセストークンの残り有効期限が切れた時点でトークン無効化を完了することができるようになる。

どういったトークン無効化手法を採用するかは、全体のシステム設計とアプリケーションサーバ提供者のリスク分析に依存するだろう。 ステート管理とコミュニケーションオーバーヘッドといったトークン無効化にかかるコストは、結局のところ必要なセキュリティプロパティの結果である。

5.  IANA Considerations

この仕様は "OAuth Extensions Error Registry" にエラー値を登録し、 "OAuth Token Type Hints" レジストリを確立する。

5.1.  OAuth Extensions Error Registration

この仕様は [RFC6749] (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) に定義されている "OAuth Extensions Error Registry" に以下のエラー値を登録する。

5.1.1.  The "unsupported_token_type" Error Value

Error name

: unsupported_token_type

Error Usage Location

: Revocation エンドポイントエラーレスポンス

Related Protocol Extension

: Token Revocation エンドポイント

Change controller

: IETF

Specification document(s)

[RFC7009]

5.1.2.  OAuth Token Type Hint Registry

この仕様は "OAuth Token Type Hints" レジストリを確立する。 パラメーター "token_type_hint" (Section 2.1 を参照) の値の候補は 1名以上の Designated Experts の勧告に従い、 oauth-ext-review@ietf.org のメーリングリストで2週間の審査を経て、 Specification Required [RFC5226] (Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs,” May 2008.) な状態で登録される。しかしながら、発行に先立ってそれらの値を用いることができるように、Designated Experts はそれらの値が公開できる状態になった時点で登録を許可することもありうる。登録要請は審査とコメントのために、適切な件名 (例: "Request for parameter: example") で oauth-ext-review@ietf.org メーリングリストに通知しなければならない。審査期間内に、 Designated Expert(s) は登録を承認または拒否し、レビューが行われるメーリングリストおよび IANA へその決定を告げる。要請が拒否された場合は、その理由が通知され、可能な場合は承認に向けた提案が行われるべきである。 IANA は Designated Expert(s) からのレジストリ更新のみを受け付けなければならず、すべての登録要請をレビューメーリングリストに送信しなければならない。

5.1.2.1.  Registration Template

Hint Value:

追加する値、認可サーバーへ信頼のあるトークンタイプを指し示すために使用できる。

Change controller:

Standards Track RFCs に従う際には、 "IETF" と記載する。それ以外の場合には、責任ある団体の名称を記載する。その他の詳細 (例えば, 郵便番号, メールアドレス, ホームページの URL) も記載してもよい。

Specification document(s):

タイプ仕様を記載したドキュメントへの参照を記載する。ドキュメントを取得することのできる URI が記載されていることがことが望ましい。明確な記載箇所への参照が含まれることが望ましいが必須ではない。

5.1.2.2.  Initial Registry Contents

OAuth Token Type Hint レジストリの初期の項目は以下の通りである。

Table 1: OAuth Token Type Hints initial registry contents

6.  Security Considerations

認可サーバーがアクセストークンの無効化をサポートしない場合、関連するリフレッシュトークンを無効化してもアクセストークンは直ちに無効化されないであろう。それらのセキュリティリスクの分析を行う際、実装はこのことを考慮しなければならない。

トークンを適切に無効化すると、不要になったトークンの乱用の可能性を低減させ、全般的なセキュリティとプライバシーの向上につながる。一般的にこの仕様は、トークンの窃取と乱用に対する対策を提供するわけではない。それぞれの脅威と対策の議論について、 OAuth core specification [RFC6749] (Hardt, D., Ed., “The OAuth 2.0 Authorization Framework,” October 2012.) の Section 10 と OAuth threat model document [RFC6819] (Lodderstedt, T., Ed., McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations,” January 2013.) で与えられているセキュリティ考慮事項を参照すること。

悪意のあるクライアントは認可サーバー上で DoS 攻撃を目的としてこの新しいエンドポイントを使用する可能性がある。DoS 攻撃に対する適切な対策 (これはトークンエンドポイントにも適用されるべき (SHOULD) であり) が、無効化エンドポイントに適用されなければいけない (MUST) ([RFC6819] (Lodderstedt, T., Ed., McGloin, M., and P. Hunt, “OAuth 2.0 Threat Model and Security Considerations,” January 2013.) の Section 4.4.1.11 を参照) 。特に、無効なトークンタイプのヒントは認可サーバーを誤認させ、余計なデータベース検索を引き起こす。悪意のあるクライアントが DoS 攻撃を起動するためにこの機能を使用することを防がなければならない。(MUST)

悪意のあるクライアントは任意のトークン文字列に対して無効化を要求することによって、このエンドポイントで有効なトークンを推測しようとするかもしれない。この仕様によると、パブリッククライアントの場合、クライアントは有効な client_id を、あるいはコンフィデンシャルクライアントの場合、有効なクライアントクレデンシャルを含まなければいけない。また、無効化されているトークンは要求しているクライアントに属していなければならない。攻撃者が公開されているクライアントの client_id とそれらのトークンのひとつ、あるいは非公開のクライアントクレデンシャルとそれらのトークンのひとつを正常に推測できる場合、トークンを無効化することより他の場所でトークンを使用することによってはるかに悪い損害を与える可能性がある。彼らがトークンを無効化する選択をする場合、正当なクライアントはその認可を失い、ユーザー認証を再び必要とするだろう。それ以上の損害は行われず、推測されたトークンはその時点で価値はない。

無効化エンドポイントはセキュリティクレデンシャルを取り扱っているため、クライアントは信頼できるリソースのみから位置を取得する必要がある。そうしなければ、攻撃者が偽の無効化エンドポイントを利用することによって有効なセキュリティトークンを読み取れてしまう。さらに、偽の無効化エンドポイントを見つけるために、クライアントはその無効化エンドポイントを認証しなければならない (証明書の検証など) 。

7.  Acknowledgements

We would like to thank Peter Mauritius, Amanda Anganes, Mark Wubben, Hannes Tschofenig, Michiel de Jong, Doug Foiles, Paul Madsen, George Fletcher, Sebastian Ebling, Christian Stübner, Brian Campbell, Igor Faynberg, Lukas Rosenstock, and Justin Richer for their valuable feedback.

8.  翻訳者

本仕様の翻訳は, OpenIDファウンデーションジャパン (OpenIDファウンデーションジャパン, “OpenIDファウンデーションジャパン,” .) [oidfj] 翻訳・教育ワーキンググループ (OpenIDファウンデーションジャパン, “翻訳・教育ワーキンググループ,” .) [oidfj‑trans]を主体として, 有志のメンバーによって行われました. 質問や修正依頼などについては, Githubレポジトリー (OpenIDファウンデーションジャパン, “Githubレポジトリー,” .) [oidfj‑github] にご連絡ください.

• Masaru Kurahayashi (Yahoo! Japan)
• Nov Matake (YAuth.jp)

9.  References

9.1. Normative References

9.2. Informative References

9.3. 翻訳プロジェクト

Authors' Addresses