366.txt

[42] [DFN[[RUBYB[持参人]@en[bearer]]]] ([DFN[[CODE(HTTP)@en[[[Bearer]]]]]]) [[トークン]]は、
不透明な文字列を[[アクセストークン]]として使用する [[OAuth 2.0]]
の[[認証]]方式の1つです。いわゆる [[APIトークン]]による [[Web API]]
の[[認証]]を [[OAuth 2.0]] と [[HTTP]] の枠組みの上で実装したものとなっています。

* 仕様書

[REFS[
- [3] [CITE@en[RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage]] ([TIME[2015-02-11 06:22:47 +09:00]] 版) <http://tools.ietf.org/html/rfc6750>
-- [6] [CITE@en[RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage]] ([TIME[2015-02-11 06:22:47 +09:00]] 版) <http://tools.ietf.org/html/rfc6750#section-2>
-- [29] [CITE@en[RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage]] ([TIME[2015-02-11 06:22:47 +09:00]] 版) <http://tools.ietf.org/html/rfc6750#section-3>
-- [46] [CITE@en[RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage]] ([TIME[2015-02-11 06:22:47 +09:00]] 版) <http://tools.ietf.org/html/rfc6750#section-5>
- [56] [CITE@en[RFC 6819 - OAuth 2.0 Threat Model and Security Considerations]] ([TIME[2015-02-10 06:43:00 +09:00]] 版) <http://tools.ietf.org/html/rfc6819#section-4.6.6>
- [58] [CITE@en[RFC 6819 - OAuth 2.0 Threat Model and Security Considerations]] ([TIME[2015-02-10 06:43:00 +09:00]] 版) <http://tools.ietf.org/html/rfc6819#section-4.6.7>
- [60] [CITE@en[Errors from Secured Resources]] ([TIME[2015-03-05 10:50:36 +09:00]] 版) <https://msdn.microsoft.com/en-us/library/azure/dn645539.aspx>
]REFS]

* 持参人トークン

[4] [[RFC 6750]] は [[OAuth 2.0]] [[アクセストークン型]]として
[DFN[[CODE(HTTP)@en[[[Bearer]]]]]] を定義しています。 [CODE(HTTP)@en[[[Bearer]]]]
では[[アクセストークン]]のことを[DFN[[RUBYB[持参人トークン]@en[bearer token]]]] [SRC[>>3]]
と呼んでいます。

> A security token with the property that any party in possession of
the token (a "bearer") can use the token in any way that any other
party in possession of it can.  Using a bearer token does not
require a bearer to prove possession of cryptographic key material
(proof-of-possession).

[43] [[持参人トークン]]は、[[クライアント]]にとって[[不透明]]な値です。
長さの制約は特に無いようです。しかし攻撃者が推測したり、改変したりできない値としなければ[['''なりません''']] [SRC[>>46]]。

;; [[アクセストークン]]の項も参照。

[38] [[ベアラートークン]]の構文は明記されていませんが、 [[credentials]]
の構文上の制約から、 [CODE(ABNF)@en[[[b64token]]]] である必要があります。

;; [[URL query]] や [[payload body]] における指定方法にはこの制約が適用されません。
しかしそれらの方法は非推奨なので、[[行間を読む]]なら、
それらの方式のみで認められる[[アクセストークン]]の発行を認める意図があったとは思い難いです。

[10] [DFN[[CODE(ABNF)@en[[[b64token]]]]]] は、1つ以上の
[[ASCII英数字]]、[CODE[[[-]]]]、[CODE[[[.]]]]、[CODE[[[_]]]]、
[CODE[[[~]]]]、[CODE[[[+]]]]、[CODE[[[/]]]] の後に、
0個以上の [CODE[[[=]]]] を続けたものです [SRC[>>6]]。

[FIG(railroad)[
= +
== |
=== [[ASCII英数字]]
=== [CODE[[[-]]]]
=== [CODE[[[.]]]]
=== [CODE[[[_]]]]
=== [CODE[[[~]]]]
=== [CODE[[[+]]]]
=== [CODE[[[/]]]]
= *
== [CODE[[[=]]]]
]FIG]

;; [55] [[Base64]] を利用することが想定された構文となっているようですが、
[[持参人トークン]]はその他の方法で生成しても構いません。

[50] [[持参人トークン]]の[[寿命]]は制限しなければ[['''なりません''']]。
[[鯖]]は、 [[Webブラウザー]]その他情報漏洩の可能性のある環境の[[クライアント]]には、
[[寿命]]の短い (1時間[[以下]]の) [[持参人トークン]]を発行する[['''べき''']]です。
[SRC[>>46]]

;; [51] おおよそどの環境でも多かれ少なかれ情報漏洩の危険性はありそうですが、
この条件に該当するかどうかはどう判断したら良いのでしょう?

[37] [[RFC 6750]] が規定する[[資源鯖]]の[[認証]]のために[[ベアラートークン]]を使う方式は、
[[OAuth 2.0]] [[認可鯖]]から取得した[[アクセストークン]]を[[ベアラートークン]]として指定するものです。
ただし [[OAuth]] 以外の方法で取得した[[アクセストークン]]を使うことも認めています。
また一般的な[[資源鯖]]だけでなく、[[串]]の[[認証]]のために本方式を使うことも認めています。

[47] [[クライアント]]は、[[持参人トークン]]が無関係の者に漏洩しないようしなければ[['''なりません''']] [SRC[>>46]]。

[49] [[持参人トークン]]を[[クッキー]]に含める場合には、 [[CSRF]]
に警戒しなければ[['''なりません''']]。[[持参人トークン]]を[[平文]]で送信される[[クッキー]]に含めては[['''なりません''']]。
[SRC[>>46]] ([CODE(HTTP)@en[[[Secure]]]] [[属性]]のない[[クッキー]]は[[平文]]で送信されます。)

[53] [[持参人トークン]]は [[URL]] に含める[['''べきではありません''']]。
[[URL]] は[[履歴]]や[[ログ]]などで漏洩しやすいためです。 [SRC[>>46]]

[54] [[逆串]]で [[TLS]] を終端してその裏側の[[アプリケーション鯖]]とは[[平文]]で通信するような場合には、
[[持参人トークン]]の[[機密性]]に注意しなければ[['''なりません''']] [SRC[>>46]]。

[52] [[鯖]]は、適用可能な[[資源鯖]]を必要な範囲に限定した[[持参人トークン]]を発行する[['''べきです''']] [SRC[>>46]]。

* プロトコル

[44] [[クライアント]]は [[OAuth 2.0]] の[[認可承諾]]フローによって予め[[持参人トークン]]
([[アクセストークン]]) を得ておく必要があります。

[48] [[クライアント]]は[[持参人トークン]]を送信する際は常に[[TLS]]
で[[機密性]]と[[一貫性]]を保護できる [[ciphersuite]]
を使わなければ[['''なりません''']]。
[[クライアント]]は [[TLS]] [[証明書鎖]]を[RUBYB[検証]@en[validate]]しなければ[['''なりません''']]
([[CRL]] の検査も含みます)。
そうしなければ [[DNSハイジャック攻撃]]の危険があります。
[[クライアント]]は [[HTTPS]] の規定に従い[[資源鯖]]の [[identity]]
を[RUBYB[検証]@en[verify]]しなければ[['''なりません''']]。 [SRC[>>46]]

;; [[HTTPS鯖認証]]参照。

[5] [[持参人トークン]]は、[CODE(HTTP)@en[[[Authorization:]]]] [[ヘッダー]]、
[[URL query]]、[[payload body]] の3つの方法で指定できます。
[[クライアント]]は複数の方法を同時に使っては[['''なりません''']] [SRC[>>6]]。

[11] [[クライアント]]は [CODE(ABNF)@en[[[Authorization:]]]]
[[ヘッダー]]の方法を使う[['''べき''']]です。[[資源鯖]]はこれに対応しなければ[['''なりません''']]。
[SRC[>>6]]

[18] [[クライアント]]は [CODE(HTTP)@en[[[Authorization:]]]] を使えない場合を除き、
[[payload body]] による指定を使う[['''べきではありません''']]。
[[資源鯖]]はこの方法に対応しても構いません。 [SRC[>>6]]

[22] [[クライアント]]は他の方法を使えない場合を除き、
[[URL query]] による指定を使う[['''べきではありません''']]。
[[資源鯖]]はこの方法に対応しても構いません。 [SRC[>>6]]

[66] [[Instagram]] など [SRC[>>65, >>67, >>71]] は[[ドキュメント]]を見る限り
[[URL query]] による指定のみ、または [[URL query]] と [[payload body]]
のみにしか対応していないようです。

[REFS[
- [65] [CITE@ja[Instagram API Endpoints • Instagram Developer Documentation]] ([TIME[2015-03-05 16:54:03 +09:00]] 版) <https://instagram.com/developer/endpoints/#instagram-api-endpoints>
- [71] [CITE[Bitly API Documentation]] ([TIME[2014-11-01 00:33:47 +09:00]] 版) <http://dev.bitly.com/authentication.html>
]REFS]

[39] [[資源鯖]]は、[[要求]]に含まれる[[アクセストークン]]を調べ、
有効な[[アクセストークン]]が含まれていれば[[認証]]できたものとして処理を続行します。
そうでなければ、エラー応答を返します。

* 認証方式 [CODE(HTTP)@en[Bearer]] を使った要求

[7] [[HTTP要求]]の [CODE(HTTP)@en[[[Authorization:]]]] [[ヘッダー]]で[[認証方式]]
[CODE(HTTP)@en[[[Bearer]]]] を使って[[アクセストークン]]を指定できます [SRC[>>6]]。

[EG[
[8] 例えば、 [[HTTP要求]]に
[PRE(HTTP code)[
Authorization: Bearer mF_9.B5f-4.1JqM
]PRE]
... のような[[ヘッダー]]を指定します [SRC[>>6]]。
]EG]

[9] [CODE(HTTP)@en[[[Authorization:]]]] [[ヘッダー]]の値である [[credentials]]
は、[[認証方式]]である [CODE(HTTP)@en[[[Bearer]]]] と区切りの [CODE(char)[[[U+0020]]]]
の後に、 [CODE(ABNF)@en[[[b64token]]]] を指定するものです [SRC[>>6]]。

[26] [[認証方式]] [CODE(HTTP)@en[[[Bearer]]]] を [[Webブラウザー]]自身が使うことはないので、
特段の [[CSRF]] 対策は不要です。

[70] [[GitHub]] の認証方式は本方式に近いですが、 [CODE(ABNF)@en[[[auth-scheme]]]]
が [CODE(HTTP)@en[[[Bearer]]]] ではなく [DFN[[CODE(HTTP)@en[[[token]]]]]]
となっています [SRC[>>61]]。

;; [[draft-hammer-http-token-auth]] と同じ [CODE(ABNF)@en[[[auth-scheme]]]]
ですが、異なる方式です。

[62] [[ヤマレコ]]の認証方式は本方式に近いですが、 [CODE(ABNF)@en[[[auth-scheme]]]]
が [CODE(HTTP)@en[[[Bearer]]]] ではなく [CODE(HTTP)@en[[[OAuth]]]]
となっています [SRC[>>61]]。

[73] [[StatusPage.io]] も [CODE(HTTP)@en[[[OAuth]]]] を使っていますが、
[[大文字]]と[[小文字]]を区別するようで注意を促しています [SRC[>>72]]。

[REFS[
- [69] [CITE@en[OAuth | GitHub API]] ([TIME[2015-03-05 18:02:01 +09:00]] 版) <https://developer.github.com/v3/oauth/>
- [61] [CITE[1. OAuth認証 - ヤマレコ Web API]] ([TIME[2015-02-25 16:41:06 +09:00]] 版) <https://sites.google.com/site/apiforyamareco/api/oauth>
- [72] [CITE@en[StatusPage.io - Documentation - API Authentication]] ([[]] 著, [TIME[2014-08-28 18:57:27 +09:00]] 版) <http://doers.statuspage.io/api/authentication/>
]REFS]

* payload body によってアクセストークンを指定した要求

[12] [[HTTP要求]]の [[payload body]] の [CODE(URI)@en[[[access_token]]]]
[[引数]]を使って[[アクセストークン]]を指定できます [SRC[>>6]]。

[13] この方法を使う場合、 [CODE(HTTP)@en[[[Content-Type:]]]]
は [CODE(MIME)@en[[[application/x-www-form-urlencoded]]]] で、
[[payload body]] もそれに従い符号化されていなければ[['''なりません''']] [SRC[>>6]]。

[14] [[payload body]] 中で[[符号化]]されている内容は [[ASCII文字]]のみで構成されなければ[['''なりません''']] [SRC[>>6]]。

;; [15] [[符号化]]されている内容が何を指しているのか不明です。
[CODE(MIME)@en[[[application/x-www-form-urlencoded]]]] のデータのことなのか、
その名前と値の組が表しているもののことなのか、
[CODE(URI)@en[[[access_token]]]] [[引数]]の値のことなのか。

[16] [[HTTP]] [[要求メソッド]]は、 [[payload body]] の[[意味]]が定義されているものでなければ[['''なりません''']]。特に [CODE(HTTP)@en[[[GET]]]] では使っては[['''なりません''']]。 [SRC[>>6]]

[17] 他の[[引数]]が指定されていても構いません [SRC[>>6]]。

[27] 副作用のある操作の場合は、 [[CSRF]] 対策が必要です。

[57] [[HTTPキャッシュ]]を考慮して、[[クライアント]]は 
[CODE(HTTP)@en[[[Cache-Control:]] [[no-store]]]] を、
[[資源鯖]]の [CODE(HTTP)[[[2xx]]]] [[応答]]は
[CODE(HTTP)@en[[[Cache-Control:]] [[private]]]] を指定するべきです [SRC[>>56]]。

* URL query によってアクセストークンを指定した要求

[19] [[HTTP要求]]の [[query]] の [CODE(URI)@en[[[access_token]]]]
[[引数]]を使って[[アクセストークン]]を指定できます [SRC[>>6]]。

[25] [CODE(MIME)@en[[[application/x-www-form-urlencoded]]]]
形式と思われますが、なぜか明記されていません。

[20] 他の[[引数]]を含む場合には、それと [CODE[[[&]]]]
で区切らなければ[['''なりません''']] [SRC[>>6]]。

[21] [[クライアント]]は、[[要求]]に [CODE(HTTP)@en[[[Cache-Control:]] [[no-store]]]]
も含める[['''べき''']]です。[[鯖]]は [CODE(HTTP)[[[2xx]]]] [[応答]]に
[CODE(HTTP)@en[[[Cache-Control:]] [[private]]]] を含める[['''べき''']]です。 [SRC[>>6, >>56]]

;; [23] この方式は推奨されませんが、現在の用法を文書化するために仕様に含まれています [SRC[>>6]]。

;; [24] [[RFC]] はセキュリティー上の問題の他、 [[引数]]を予約するのは [[URI]]
として良い慣習ではない [SRC[>>6]] と指摘しています。 [[payload body]]
でも予約していることには何も言わず (非推奨ではありますが)、 [[URL query]]
だけ敢えて良い習慣ではないと言及するのは不審です。

[59] [CODE(HTTP)@en[[[Referer:]]]] や[[ログ]]ファイルなどからの漏洩に注意が必要です [SRC[>>58]]。

[28] 副作用のある操作の場合は、 [[CSRF]] 対策が必要です。

[64] [[Slack]] は [[URL query]] の [CODE[[[token]]]] [[引数]]に[[アクセストークン]]を指定することを求めています [SRC[>>63]]。

[68] [[foursquare]] は [[URL query]] の [CODE[[[oauth_token]]]] [[引数]]に[[アクセストークン]]を指定することを求めています [SRC[>>67]]。

[74] [[StatusPage.io]] は [CODE[[[api_key]]]] [[引数]]に[[アクセストークン]]を指定することを求めています [SRC[>>72]]。

[REFS[
- [63] [CITE@en[Slack Web API | Slack]] ([[Slack]] 著, [TIME[2015-03-05 16:12:13 +09:00]] 版) <https://api.slack.com/web>
- [67] [CITE[Connecting]] ([TIME[2015-03-05 17:39:49 +09:00]] 版) <https://developer.foursquare.com/overview/auth>
]REFS]

* エラー応答

[30] [[資源鯖]]は、[[被保護資源]]に対する[[要求]]に適切な[[アクセストークン]]が含まれていなければ、
[CODE(HTTP)@en[[[WWW-Authenticate:]]]] [[ヘッダー]]を含めなければ[['''なりません''']]。
[[資源鯖]]は他の場面でも含めることができます。 [SRC[>>29]]

[31] [[ベアラートークン]]を実装する[[資源鯖]]は、
[CODE(ABNF)@en[[[auth-scheme]]]] として [CODE(HTTP)@en[[[Bearer]]]]
を使わなければ[['''なりません''']] [SRC[>>29]]。

[33] 次の[[引数]]があります。
[FIG(short list)[
- [CODE(HTTP)@en[[[authorization_uri]]]] [SRC[>>60]]
- [CODE(HTTP)@en[[[realm]]]]
- [CODE(HTTP)@en[[[scope]]]]
- [CODE(HTTP)@en[[[error]]]]
- [CODE(HTTP)@en[[[error_description]]]]
- [CODE(HTTP)@en[[[error_uri]]]]
- [CODE(HTTP)@en[[[resource_id]]]] [SRC[>>60]]
]FIG]
[32] その他の[[引数]]を指定しても構いません [SRC[>>29]]。

;; [45] 特に [[IANA登録簿]]も無いようです。本当に何でも指定して良いのでしょうか?

[34] [[引数]]のいずれも[['''必須''']]とはなっていませんが
([CODE(HTTP)@en[[[error]]]] のみ[['''推奨''']])、
1つ以上の[[引数]]を指定することが[['''必須''']]となっています [SRC[>>29]]。
([CODE(HTTP)@en[[[error]]]] を含めるべきではないとされている状況があり、
その場合 [CODE(HTTP)@en[[[realm]]]] しか適当なものがありませんから、
空であっても [CODE(HTTP)@en[[[realm]]]] を指定するしかありません。)

;; [35] [[RFC]] にありがちな、意味のあるのか無いのかわからない謎の曖昧規定ですね...

[36] [CODE(HTTP)@en[[[error]]]] の値によっては、[[状態符号]]に関する要件があります。

* 歴史

[1] [CITE@en[Bearer Tokens - Actions in the Inbox — Google Developers]]
( ([TIME[2013-09-07 00:07:39 +09:00]] 版))
<https://developers.google.com/gmail/actions/actions/verifying-bearer-tokens?hl=ja>

[2] [CITE@en[RFC 7236 - Initial Hypertext Transfer Protocol (HTTP) Authentication Scheme Registrations]]
( ([TIME[2014-09-10 00:40:16 +09:00]] 版))
<https://tools.ietf.org/html/rfc7236#section-3>

* 関連

[41] [[HTTP認証]]の中では[[基本認証]]が[[利用者名]]と[[合言葉]]の2つの値を指定するだけのものですが、
[[持参人トークン]]方式は1つの値を指定するだけの、より単純なものとなっています。

* メモ

[40] [CITE[IdM実験室: Bearer Token とは?]]
([TIME[2015-02-07 10:00:00 +09:00]] 版)
<http://idmlab.eidentity.jp/2013/09/bearer-token.html>