[42] 持参人 (Bearer
) トークンは、
不透明な文字列をアクセストークンとして使用する OAuth 2.0
の認証方式の1つです。いわゆる APIトークンによる Web API
の認証を OAuth 2.0 と HTTP の枠組みの上で実装したものとなっています。
[77] 「OAuth 2.0 を使う」 と言う場合、ほとんどは本方式を指しています。
[87] OAuth 2.0 の認可フローとは完全に独立した技術で、この認証方式のみを単独で用いることもできます。
[4] RFC 6750 は OAuth 2.0 アクセストークン型として
Bearer
を定義しています。 Bearer
ではアクセストークンのことを持参人トークン >>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。
[44] クライアントは OAuth 2.0 の認可承諾フローによって予め持参人トークン (アクセストークン) を得ておく必要があります。
[48] クライアントは持参人トークンを送信する際は常にTLS で機密性と一貫性を保護できる ciphersuite を使わなければなりません。 クライアントは TLS 証明書鎖を検証しなければなりません (CRL の検査も含みます)。 そうしなければ DNSハイジャック攻撃の危険があります。 クライアントは HTTPS の規定に従い資源鯖の identity を検証しなければなりません。 >>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。
[9] Authorization:
ヘッダーの値である credentials
は、認証方式である Bearer
と区切りの U+0020
の後に、 b64token
を指定するものです >>6。
[26] 認証方式 Bearer
を Webブラウザー自身が使うことはないので、
特段の CSRF 対策は不要です。
[91]
Strava は Bearer
と titlecase にしなければならず、
小文字だと認証エラーになるようです。
[70] GitHub の認証方式は本方式に近いですが、 auth-scheme
が Bearer
ではなく token
となっています >>61。
auth-scheme
ですが、異なる方式です。[62] ヤマレコの認証方式は本方式に近いですが、 auth-scheme
が Bearer
ではなく OAuth
となっています >>61。
[73] StatusPage.io も OAuth
を使っていますが、
大文字と小文字を区別するようで注意を促しています >>72。
[98]
Discord API には通常の利用者の Bearer
の他にボット用の Bot
があります。
>>97
種別を auth-scheme
で区別していますが、構文的には同じです。
[100]
Vonage はクライアントに JWT を生成させて Bearer
の値として使用させています。 >>99
[101] これは鯖が生成しクライアントにとって不透明な値という持参人トークンの条件を満たさない不適切な利用例です。
[12] HTTP要求の payload body の access_token
引数を使ってアクセストークンを指定できます >>6。
[13] この方法を使う場合、 Content-Type:
は application/x-www-form-urlencoded
で、
payload body もそれに従い符号化されていなければなりません >>6。
[14] payload body 中で符号化されている内容は ASCII文字のみで構成されなければなりません >>6。
application/x-www-form-urlencoded
のデータのことなのか、
その名前と値の組が表しているもののことなのか、
access_token
引数の値のことなのか。[16] HTTP 要求メソッドは、 payload body の意味が定義されているものでなければなりません。特に GET
では使ってはなりません。 >>6
[94]
Slack
は
token
という名前の引数で指定するよう求めています
>>63。
[27] 副作用のある操作の場合は、 CSRF 対策が必要です。
[57] HTTPキャッシュを考慮して、クライアントは
Cache-Control: no-store
を、
資源鯖の 2xx
応答は
Cache-Control: private
を指定するべきです >>56。
[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。
[64] Slack は URL query の token
引数にアクセストークンを指定することを求めています >>63。
[93] ... のですが、その後非互換変更があったようで、現在では URL query では認められないようです >>63。
[68] foursquare >>67 や SoundCloud >>75
は URL query の oauth_token
引数にアクセストークンを指定することを求めています。
[74] StatusPage.io >>72 など >>78
は api_key
引数にアクセストークンを指定することを求めています。
[82] RFC は認めていませんが、その他の方法が使われることがあります。
[84] IIJmioクーポンスイッチAPIは、独自のヘッダーにアクセストークンを指定させます。
HTTP認証ではないので、エラーは 401
ではなく 403
で報告することになっています。
[95] POP, IMAP, SMTP のようなインターネットメール系プロトコルでは、 SASL の XOAUTH2 で持参人トークンが使われます。
[30] 資源鯖は、被保護資源に対する要求に適切なアクセストークンが含まれていなければ、
WWW-Authenticate:
ヘッダーを含めなければなりません。
資源鯖は他の場面でも含めることができます。 >>29
[31] ベアラートークンを実装する資源鯖は、
auth-scheme
として Bearer
を使わなければなりません >>29。
[33] 次の引数があります。
[34] 引数のいずれも必須とはなっていませんが
(error
のみ推奨)、
1つ以上の引数を指定することが必須となっています >>29。
(error
を含めるべきではないとされている状況があり、
その場合 realm
しか適当なものがありませんから、
空であっても realm
を指定するしかありません。)
[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
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
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.
--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.
Www-Authenticate: Bearer realm="https://auth.docker.io/token",service="registry.docker.io"
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/