仕様書

持参人トークン

[4] RFC 6750 は OAuth 2.0 アクセストークン型として Bearer を定義しています。 Bearer ではアクセストークンのことを持参人トークン (bearer token) >>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] 持参人トークンは、クライアントにとって不透明な値です。 長さの制約は特に無いようです。しかし攻撃者が推測したり、改変したりできない値としなければなりません >>46。

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

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

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

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

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

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

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

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

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

プロトコル

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

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

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

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

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

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

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

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

認証方式 Bearer を使った要求

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

Authorization: Bearer mF_9.B5f-4.1JqM

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

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

[91] Strava は Bearer と titlecase にしなければならず、 小文字だと認証エラーになるようです。 2018-10-26T11:43:04.400Z

[70] GitHub の認証方式は本方式に近いですが、 auth-scheme が Bearer ではなく token となっています >>61。

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

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

[98] Discord API には通常の利用者の Bearer の他にボット用の Bot があります。 >>97 種別を auth-scheme で区別していますが、構文的には同じです。

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

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

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

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

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

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

[94] Slack は token という名前の引数で指定するよう求めています >>63。

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

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

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

[19] HTTP要求の query の access_token 引数を使ってアクセストークンを指定できます >>6。 capability URL の一種といえます。

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

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

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

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

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

[80] Facebook は本方式を採用しています >79。

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

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

その他の方法 (HTTP)

[82] RFC は認めていませんが、その他の方法が使われることがあります。

[84] IIJmioクーポンスイッチAPIは、独自のヘッダーにアクセストークンを指定させます。 HTTP認証ではないので、エラーは 401 ではなく 403 で報告することになっています。

XOAUTH2

[95] POP, IMAP, SMTP のようなインターネットメール系プロトコルでは、 SASL の XOAUTH2 で持参人トークンが使われます。

エラー応答

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

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

[33] 次の引数があります。

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

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

歴史

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

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

関連

[88] 「持参人 (ベアラー)」とは、特定の者に権限を与えるのではなく、 証書を持つ者に対して権限を与えることをいいます。 小切手の持参人払い (小切手所有者に支払うもの) や、 持参人式定期券 (定期券を現に所有していれば誰であっても使えるもの) のような形で使われています。

[89] 認証方式としては、利用者名などの識別情報を持たず、 予め発行された不透明な識別子を保持することを承認された者とみなすことから持参人と呼ぶものと思われます。

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

メモ

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

[81] RFC 7628 - A Set of Simple Authentication and Security Layer (SASL) Mechanisms for OAuth (2015-09-01 15:39:29 +09:00 版) https://tools.ietf.org/html/rfc7628