持参人トークン

持参人トークン

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

[77]OAuth 2.0 を使う」 と言う場合、ほとんどは本方式を指しています。

[87] OAuth 2.0認可フローとは完全に独立した技術で、この認証方式のみを単独で用いることもできます。

仕様書

持参人トークン

[4] RFC 6750OAuth 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 である必要があります。

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

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

  1. +
    1. |
      1. ASCII英数字
      2. -
      3. .
      4. _
      5. ~
      6. +
      7. /
  2. *
    1. =
[55] Base64 を利用することが想定された構文となっているようですが、 持参人トークンはその他の方法で生成しても構いません。

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

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

[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 querypayload body の3つの方法で指定できます。 クライアントは複数の方法を同時に使ってはなりません >>6

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

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

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

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

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

認証方式 Bearer を使った要求

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

[8] 例えば、 HTTP要求

Authorization: Bearer mF_9.B5f-4.1JqM
... のようなヘッダーを指定します >>6

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

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

[91] StravaBearertitlecase にしなければならず、 小文字だと認証エラーになるようです。

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

draft-hammer-http-token-auth と同じ auth-scheme ですが、異なる方式です。

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

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

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

不適切な利用例

[100] VonageクライアントJWT を生成させて Bearer の値として使用させています。 >>99

[101] これはが生成しクライアントにとって不透明な値という持参人トークンの条件を満たさない不適切な利用例です。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[23] この方式は推奨されませんが、現在の用法を文書化するために仕様に含まれています >>6
[24] RFC はセキュリティー上の問題の他、 引数を予約するのは URI として良い慣習ではない >>6 と指摘しています。 payload body でも予約していることには何も言わず (非推奨ではありますが)、 URL query だけ敢えて良い習慣ではないと言及するのは不審です。

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

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

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

[64] SlackURL querytoken 引数アクセストークンを指定することを求めています >>63

[93] ... のですが、その後非互換変更があったようで、現在では URL query では認められないようです >>63

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

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

その他の方法 (HTTP)

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

[83] OAuth 2.0 により取得したアクセストークンを独自プロトコルに流用した (独自プロトコルのアクセストークン取得部分のみに OAuth 2.0 を流用した) と考えれば、直ちに RFC 違反と言えるものでもありません。 しかし、少なくても標準化により相互運用性を向上させる努力とは矛盾しています。

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

XOAUTH2

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

エラー応答

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

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

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

[32] その他の引数を指定しても構いません >>29

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

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

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

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

歴史

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

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

関連

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

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

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

メモ

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

[76] HTTP Headers and Query String Parameters - Cloud Storage — Google Cloud Platform ( 版) https://cloud.google.com/storage/docs/reference-headers#authorization

Valid Values

An authentication identifier ( OAuth | GOOG1 | AWS ) followed by one of the following:

A valid OAuth 2.0 token

An access key

A signature

Example

Authorization: OAuth 1/zVNpoQNsOSxZKqOZgckhpQ

[81] RFC 7628 - A Set of Simple Authentication and Security Layer (SASL) Mechanisms for OAuth ( 版) https://tools.ietf.org/html/rfc7628

[85] dev:web_api:v3:basics [Zotero Documentation] ( 版) https://www.zotero.org/support/dev/web_api/v3/basics

API keys can be included in requests in one of two ways:

As an HTTP header, in the form Authorization: Bearer P9NiFoyLeZu2bZNvvuQPDWsd

As a URL query parameter, in the form key=P9NiFoyLeZu2bZNvvuQPDWsd

Use of the Authorization header is recommended, as it will allow use of URLs returned from the API (e.g., for pagination) without modification.

OAuth 2.0

[86] cURL - How To Use ( ()) https://curl.haxx.se/docs/manpage.html#--oauth2-bearer

--oauth2-bearer

(IMAP, POP3, SMTP) Specify the Bearer Token for OAUTH 2.0 server authentication. The Bearer Token is used in conjunction with the user name which can be specified as part of the --url or -u, --user options.

[90] DOCKER-627: 'docker login quay.io' is failing () https://smartos.org/bugview/DOCKER-627

Www-Authenticate: Bearer realm="https://auth.docker.io/token",service="registry.docker.io"

[96] Authentication | Twitch Developers (, ) https://dev.twitch.tv/docs/authentication#sending-user-access-and-app-access-tokens

In the Twitch API:

curl -H "Authorization: Bearer <access token>" https://api.twitch.tv/helix/

In Twitch API v5 (deprecated ):

curl -H "Authorization: OAuth <access token>" https://api.twitch.tv/kraken/