547.txt

[2] [DFN[[RUBYB[revoke エンドポイント]@en[revocation endpoint]]]]は、[[アクセストークン]]や[[更新トークン]]を取り消し ([[revoke]]) するための[[エンドポイント]]です。

* 仕様書

[REFS[
- [1] '''[CITE@en[RFC 7009 - OAuth 2.0 Token Revocation]] ([TIME[2014-12-21 18:10:21 +09:00]] 版) <http://tools.ietf.org/html/rfc7009>'''
- [10] [CITE@en[RFC 6749 - The OAuth 2.0 Authorization Framework]] ([TIME[2014-12-15 14:15:35 +09:00]] 版) <http://tools.ietf.org/html/rfc6749#section-3.1>
- [30] [CITE@en[RFC 6749 - The OAuth 2.0 Authorization Framework]] ([TIME[2014-12-15 14:15:35 +09:00]] 版) <http://tools.ietf.org/html/rfc6749#section-5.2>
]REFS]

* 意味

[3] [RUBYB[取り消し要求]@en[revocation request]]は、
[[クライアント]]が自身の保持する[[アクセストークン]]や[[更新トークン]]を無効化することを[[認可鯖]]に求めるものです。 [SRC[>>1]]

[41] [[認可鯖]]は、求められた[[トークン]]を無効にすると共に、
関係する他の[[トークン]]や、セッションデータ等関係するデータを消去できます [SRC[>>1]]。

[6] 実装は、[[更新トークン]]の [[revoke]] に対応しなければ[['''なりません''']] [SRC[>>1]]。

[7] 実装は、[[アクセストークン]]の [[revoke]] に対応する[['''べき''']]です [SRC[>>1]]。

;; [8] しかしながら、実装が [[revoke]] に対応すること自体は必須とはなっていません。
[[OAuth]] 本体に対応していても、 [[revoke]] には対応していない可能性があります。
また[[更新トークン]]を使わない実装は[[更新トークン]]の [[revoke]]
にも対応していない (できない) かもしれません。

;; [39] [[更新トークン]]の [[revoke]] により[[アクセストークン]]が [[revoke]]
されることは保証されませんし、されたかどうか直接知ることもできません。
[[クライアント]]は確実に [[revoke]] したければ両方を明示的に [[revoke]]
する必要があります。

[EG[
[4] [[OAuth]] はしばしば [[Webアプリケーション]]の[[ログイン]]の仕組みとして使われます。
そのような[[Webアプリケーション]] ([[クライアント]]) は、
[[末端利用者]] ([[資源所有者]]) が[[ログアウト]]したり[[アンインストール]]したりした時に、
[[トークン]]を [[revoke]] することができます。 [SRC[>>1]]
]EG]

[5] [[トークン]]を [[revoke]] することで、[[ログアウト]]等の後[[末端利用者]]が気づかないまま[[トークン]]が残ってしまうことを防げますし、
乱用されることも防げます。 [SRC[>>1]]

;; [42] [[クライアント]]が [[revoke]] するのは任意であり、[[末端利用者]]は [[revoke]]
したかどうか直接知ることができないので、[[クライアント]]が悪意を持っている場合の対策にはならず、
せいぜい流出した時の被害を抑えるくらいの役目しか果たしませんが...

[43] [[認可鯖]]が[[末端利用者]]に対して[[認可承諾]]の一覧を提示している場合には、
そこからも消去されるでしょう。 [SRC[>>1]] 使わなくなった[[クライアント]]が一覧に残り続けるよりは良さそうです。

[24] [[クライアント]]は、 [[revokeエンドポイント]]が [CODE(HTTP)[[[200]]]]
を返した後その[[トークン]]を使おうと試みてはなりません [SRC[>>1]]。

[26] なお、[[トークン]]はこの仕組み以外でも無効になることがあります。
[[クライアント]]は、いつでも[[トークン]]が無効にされる可能性を考慮しておかなければなりません
[SRC[>>1]]。例えば[[資源所有者]]が [[revoke]] するかもしれませんし、
[[認可鯖]]が自身の判断で無効化するかもしれません。

* クライアントの要求

[9] [[クライアント]]は、 [CODE(HTTP)@en[[[POST]]]] [[要求]]を使います [SRC[>>1]]。
[[JSONP]] を使う場合には [CODE(HTTP)@en[[[GET]]]] [[要求]]でも構いません [SRC[>>1]]。

;; [46] [[Google]] は [CODE(HTTP)@en[[[GET]]]] を使っています [SRC[>>45]]。
[[JSONP]] では無いようです。 [[RFC]] 以前からある独自の [[API]] かもしれません。
[REFS[
- [45] [CITE@ja[Using OAuth 2.0 for Web Server Applications - Google Accounts Authentication and Authorization — Google Developers]] ([TIME[2014-12-05 11:52:25 +09:00]] 版) <https://developers.google.com/accounts/docs/OAuth2WebServer#tokenrevoke>
]REFS]

[13] [[クライアント]]が [[revokeエンドポイント]]の [[URL]]
を得る方法は、 [[OAuth]] 仕様の範囲外です。[[鯖]]のドキュメントから調べても構いませんし、
自動的な[[発見]]の仕組みを使っても構いません。いずれにせよ信頼できる情報源に拠る必要があります。
[SRC[>>1]]

[14] [[revokeエンドポイント]]の [[URL]] は、 [[HTTPS]] でなければ[['''なりません''']]。
[[認可鯖]]は [[TLS]] を使わなければ[['''なりません''']]。
[[クライアント]]は [[HTTPS]] の [[URL]] であることを[RUBYB[検証]@en[verify]]しなければ[['''なりません''']]。
[[クライアント]]は偽の[[revokeエンドポイント]]を検出するため、[[証明書]]の検証などにより[[認証]]しなければ[['''なりません''']]。
[SRC[>>1]]

[15] [[revokeエンドポイント]]が素の [[HTTP]] でも利用できるなら、
そちらでの [[revoke]] にも対応する[['''べき''']]ですが、
これを [[revokeエンドポイント]]の [[URL]] として出版しては[['''なりません''']]。 [SRC[>>1]]

;; [16] こうすることにより、誤って [[HTTP]] で送信してしまったトークンも [[revoke]]
できます [SRC[>>1]]。

[11] [[revokeエンドポイント]]の [[URL]] は、
[CODE(MIME)@en[[[application/x-www-form-urlencoded]]]]
形式の [[query]] を含んでいても構いません [SRC[>>1, >>10]]。

[12] [[URL]] に[[引数]]を追加する時は、元の [[query]] を残さなければ[['''なりません''']]
[SRC[>>1, >>10]]。

[17] [[クライアント]]は [CODE(HTTP)@en[[[POST]]]] [[要求]]の [[payload body]] または
[[JSONP]] [CODE(HTTP)@en[[[GET]]]] [[要求]]の [[URL query]] に
[CODE(MIME)@en[[[application/x-www-form-urlencoded]]]] 
形式で次の[[引数]]を指定します [SRC[>>1]]。
[FIG(list members)[
[FIGCAPTION[
[[payload body]] または [[URL query]] ([CODE(MIME)@en[[[application/x-www-form-urlencoded]]]])
]FIGCAPTION]
:[18] [CODE(URI)@en[[[token]]]]:[[revoke]] したい[[トークン]]を指定しなければ[['''なりません''']] [SRC[>>1]]。
:[19] [CODE(URI)@en[[[token_type_hint]]]]:[CODE(URI)@en[[[token]]]] の種別のヒントです。
[[クライアント]]はこれを指定しても構いません。 [SRC[>>1]]
:[33] [CODE(URI)@en[[[callback]]]]:[[JSONP]] の場合に、 [[JavaScript]] [[関数]]の[[修飾名]]を指定します [SRC[>>1]]。
]FIG]

[20] [[クライアント]]は、[[クライアント認証]] (または認証できない場合には
[CODE(URI)@en[[[client_id]]]] [[引数]]) も含めます [SRC[>>1]]。


* 認可鯖の処理

[32] [[認可鯖]]は、 [[利用者エージェントベースのアプリケーション]]で使われるかもしれない場合には、
[[CORS]] に対応して構いません [SRC[>>1]]。

;; [44] 特別な [[CSRF]] 対策は必要無さそうです。

[21] [[認可鯖]]は、まず ([[機密]]の[[クライアント]]なら)
[[クライアントcredentials]]を[RUBYB[検証]@en[validate]]します [SRC[>>1]]。

;; [[クライアント認証]]参照。[[RFC]] には明記されていませんが、
整合性を考えると[[機密]]でなくても[[クライアントcredentials]]が発行されている場合には検証するべきと思われます。

[22] [[認可鯖]]は、次に[[トークン]]が当該[[クライアント]]に発行されたものか[RUBYB[検証]@en[verify]]します。
失敗した場合は、エラーを返して終わります。 [SRC[>>1]]

[37] [[RFC]] には明記されていませんが、[[引数]]の重複や欠落などがあれば、
エラーを返して終わるべきと思われます。

[23] [[認可鯖]]は、その後[[トークン]]を非妥当化します。非妥当化は直ちに行われ、
以後[[トークン]]は使えなくなります。実際には伝播遅延があるかもしれませんが、
できるだけ短期間で反映されるようにするべきです。 [SRC[>>1]]

[29] [CODE(URI)@en[[[token_type_hint]]]] の指定は、あまり意味がありません。

;; [CODE(URI)@en[[[token_type_hint]]]] 参照。

[25] [[認可鯖]]は、 [[revoke]] に関する方針次第で、
関連するトークンや元になった[[認可承諾]]をも [[revoke]]
して構いません。 [[更新トークン]]の [[revoke]] においては、
[[認可鯖]]が[[アクセストークン]]の [[revoke]]
にも対応しているなら、同じ[[認可承諾]]に基づくすべての[[アクセストークン]]をも
[[revoke]] する[['''べき''']]です。
[[アクセストークン]]の [[revoke]] においては、
対応する[[更新トークン]]も [[revoke]] して構いません。 [SRC[>>1]]

[27] [[認可鯖]]は、 [[revoke]] に成功したい場合や、
非妥当な[[トークン]]が指定されていた場合は、 [CODE(HTTP)[[[200]]]]
[[応答]]を返します [SRC[>>1]]。

[88] [[認可鯖]]は、誤りの場合には、 [CODE(HTTP)[[[400]]]] [[応答]]で次の[[引数]]を
[[JSON]] ([CODE(MIME)@en[[[application/json]]]]) [[payload body]] の 
[[JSONオブジェクト]]の名前と値 ([[文字列]]なら [[JSON文字列]]、
[[数値]]なら [[JSON数値]]) に含めます [SRC[>>1, >>30]]。
[FIG(list members)[
[FIGCAPTION[
[[payload body]] ([[JSONオブジェクト]])
]FIGCAPTION]
:[84] [CODE(URI)@en[[[error]]]]:[[誤り符号]]を指定しなければ[['''なりません''']] [SRC[>>30]]。
:[85] [CODE(URI)@en[[[error_description]]]]:[[人間可読]]な[[誤り]]の説明を指定して構いません
[SRC[>>30]]。
:[86] [CODE(URI)@en[[[error_uri]]]]:[[人間可読]]な[[誤り]]の説明を含む[[Webページ]]の [[URL]]
を指定して構いません [SRC[>>30]]。
]FIG]

[40] [[認可鯖]]は、 [[DoS攻撃]]に注意しなければ[['''なりません''']] [SRC[>>1]]。

[28] [[クライアント]]は、 [CODE(HTTP)[[[200]]]] [[応答]]の [[payload body]] を無視します 
[SRC[>>1]]。

[31] [[クライアント]]は、 [CODE(HTTP)[[[503]]]] [[応答]]を受信したらトークンはまだ有効と判断しなければならず、
適当な間を置いて再試行して構いません。[[鯖]]は [CODE(HTTP)@en[[[Retry-After:]]]]
で利用できないと思われる期間を示すことができます。 [SRC[>>1]]

[34] [[クライアント]]は、 [[JSONP]] の場合不正な [[revokeエンドポイント]]が不正なコードを注入する危険性があることに注意するべきです [SRC[>>1]]。

;; [35] そんなレベルで[[認可鯖]]が信用できない状況では [[OAuth]] 関連の処理がすべて危険そうですが...

* 歴史

[49] [[OAuth 1.0]] 本体には [[revoke]] [[API]] はありませんでした。

[53] [[OAuth Session Extension]] は [[revoke]] [[API]] を規定していました [SRC[>>52]]。

[47] [[Google]] は [[OAuth 1.0]] [[アクセストークン]]について、
[[AuthSub]] の [[revokeエンドポイント]]を使って [[revoke]] できる [SRC[>>48]]
としていました。

[51] [[Twitter]] は [[OAuth 2.0]] 向けに独自仕様の [[revokeエンドポイント]]を実装しています
[SRC[>>50]]。

[REFS[
- [52] [CITE@en[Implementers' Draft: OAuth Session 1.0 Draft 1]] ([TIME[2008-08-22 09:10:13 +09:00]] 版) <http://oauth.googlecode.com/svn/spec/ext/session/1.0/drafts/1/spec.html#rfc.section.7>
- [48] [CITE@ja[OAuth 1.0 API Reference - Google Accounts Authentication and Authorization — Google Developers]] ([TIME[2014-12-05 11:52:26 +09:00]] 版) <https://developers.google.com/accounts/docs/OAuth_ref#RevokeToken>
- [50] [CITE[POST oauth2/invalidate_token | Twitter Developers]] ([TIME[2015-03-05 11:07:26 +09:00]] 版) <https://dev.twitter.com/oauth/reference/post/oauth2/invalidate/token>
]REFS]

* メモ

[36] [[RFC 7009]] は [[OAuth]] 関連仕様の中でも特に品質が低いようです。
他の [[RFC]] を参照している箇所は章番号だけでどの規定が引用されているのか自明ではなかったりしますし、
[[事実の文]]による状況の説明ばかりで[[助動詞]]が含まれる規定の文は少なく、
前世紀レベルです。 [[JSONP]] に関する部分に至っては規定がほとんどなく例示に頼っています。

[38] [[RFC]] は未だに [[JSONP]] を考慮しているようですが、出版された2013年の時点ではぎりぎりまだ必要があったかもしれません。
現在では最早何の意味もなく、危険なだけなので [[CORS]] を使うべきでしょう。

[54] [CITE@en[OAuth2 · reddit/reddit Wiki]]
([TIME[2015-03-05 16:30:32 +09:00]] 版)
<https://github.com/reddit/reddit/wiki/OAuth2#user-content-manually-revoking-a-token>

[FIG(quote)[
[FIGCAPTION[
[55] [CITE@en-US[OAuth 2.0 Authentication | Viadeo API]]
([TIME[2015-03-05 17:54:09 +09:00]] 版)
<http://dev.viadeo.com/documentation/authentication/oauth-authentication/>
]FIGCAPTION]

> In order to revoke a token (i.e. remove the bridge between your application and Viadeo) use  https://secure.viadeo.com/oauth-provider/revoke_access_token2 with access token as parameter
> https://secure.viadeo.com/oauth-provider/revoke_access_token2?
> client_id=<YOUR_API_KEY>&
> client_secret=<YOUR_API_SECRET>&
> redirect_uri=http://www.example.com/oauth_redirect&
> access_token=<ACCESS_TOKEN_TO_REVOKE>
>  
> In response, you will get the following json response:
> {"token_revoked"}

]FIG]


[FIG(quote)[
[FIGCAPTION[
[56] [CITE@en[OAuth | Heroku Dev Center]]
([TIME[2015-03-06 08:08:09 +09:00]] 版)
<https://devcenter.heroku.com/articles/oauth#revoking-authorization>
]FIGCAPTION]

> Revoking an authorization will block associated tokens from making further requests.
> DELETE /oauth/authorizations/{authorization-id}

]FIG]


[FIG(quote)[
[FIGCAPTION[
[57] [CITE@en[Dropbox - Core API - endpoint reference]]
([TIME[2015-03-06 09:23:18 +09:00]] 版)
<https://www.dropbox.com/developers/core/docs>
]FIGCAPTION]

> /disable_access_tokenPythonJavaRubyPHP
> DESCRIPTION
> Disables the access token used to authenticate the call. This method works for OAuth 1 and OAuth 2 tokens.
> URL STRUCTURE
> https://api.dropbox.com/1/disable_access_token
> METHOD
> POST
> RETURNS
> An empty JSON dictionary, which indicates success.

]FIG]