OAuth 2.0: Bearer Token Usage

　　Bearer Token (RFC 6750) 用於OAuth 2.0受權訪問資源，任何Bearer持有者均可以無差異地用它來訪問相關的資源，而無需證實持有加密key。一個Bearer表明受權範圍、有效期，以及其餘受權事項；一個Bearer在存儲和傳輸過程當中應當防止泄露，需實現Transport Layer Security (TLS)；一個Bearer有效期不能過長，過時後可用Refresh Token申請更新。

 

一. 資源請求

　　Bearer實現資源請求有三種方式：Authorization Header、Form-Encoded Body Parameter、URI Query Parameter，這三種方式優先級依次遞減

• Authorization Header：該頭部定義與Basic方案相似

  GET /resource HTTP/1.1
  Host: server.example.com
  Authorization: Bearer mF_9.B5f-4.1JqM

• Form-Encoded Body Parameter： 下面是用法實例

  POST /resource HTTP/1.1
  Host: server.example.com
  Content-Type: application/x-www-form-urlencoded
  
  access_token=mF_9.B5f-4.1JqM

  使用該方法發送Bearer須知足以下條件：

  1.頭部必須包含"Content-Type: application/x-www-form-urlencoded"
  2.entity-body必須遵循application/x-www-form-urlencoded編碼(RFC 6749)
  3.若是entity-body除了access_token以外，還包含其餘參數，須以"&"分隔開
  4.entity-body只包含ASCII字符
  5.要使用request-body已經定義的請求方法，不能使用GET

  若是客戶端沒法使用Authorization請求頭，才應該使用該方法發送Bearer

• URI Query Parameter：

  GET /resource?access_token=mF_9.B5f-4.1JqM HTTP/1.1
  Host: server.example.com
  Cache-Control: no-store

  服務端應在響應中使用 Cache-Control: private

 

二. WWW-Authenticate頭

　　在客戶端未發送有效Bearer的狀況下，即錯誤發生時，資源服務器鬚髮送WWW-Authenticate頭，下爲示例：

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example", error="invalid_token", error_description="The access token expired"

　　下面將就WWW-Authenticate字段的用法進行詳細描述(下列這些屬性/指令不該重複使用)：

• Bearer：Beare做爲一種認證類型(基於OAuth 2.0)，使用"Bearer"關鍵詞進行定義
• realm：與Basic、Digest同樣，Bearer也使用相同含義的域定義reaml
• scope：受權範圍，可選的，大小寫敏感的，空格分隔的列表(%x21 / %x23-5B / %x5D-7E)，能夠是受權服務器定義的任何值，不該展現給終端用戶。OAuth 2.0還規定客戶端發送scope請求參數以指定受權訪問範圍，而在實際受權範圍與客戶端請求受權範圍不一致時，受權服務器可發送scope響應參數以告知客戶端下發的token實際的受權範圍。下爲兩個scope用法實例：

  scope="openid profile email"
  scope="urn:example:channel=HBO&urn:example:rating=G,PG-13"

• error：描述訪問請求被拒絕的緣由，字符%x20-21 / %x23-5B / %x5D-7E以內
• error_description：向開發者提供一個可讀的解釋，字符%x20-21 / %x23-5B / %x5D-7E以內
• error_uri：absolute URI，標識人工可讀解釋錯誤的頁面，字符%x21 / %x23-5B / %x5D-7E以內

　　當錯誤發生時，資源服務器將發送的HTTP Status Code(一般是400, 401, 403, 或405)及Error Code以下：

• invalid_request：請求丟失參數，或包含無效參數、值，參數重複，多種方法發送access token，畸形等。資源服務器將發送HTTP 400 (Bad Request)
• invalid_token：access token過時、廢除、畸形，或存在其餘無效理由的狀況。資源服務器將發送HTTP 401 (Unauthorized)，而客戶端則須要申請一個新的access token，而後才能從新發送該資源請求
• insufficient_scope：客戶端提供的access token的享有的權限過低。資源服務器將發送HTTP 403 (Forbidden)，同時WWW-Authenticate頭包含scope屬性，以指明須要的權限範圍

　　若是客戶端發送的資源請求缺少任何認證信息(如缺乏access token，或者使用 RFC 6750 所規定的三種資源請求方式以外的任何method)，資源服務器不該該在響應中包含錯誤碼或者其餘錯誤信息，以下便可：

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example"

  

三. Bearer Token Response

　　下爲示例：

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "access_token":"mF_9.B5f-4.1JqM",
   "token_type":"Bearer",
   "expires_in":3600,
   "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}

 

四. 安全威脅

• Token 僞造/修改(Token manufacture/modification)：攻擊者僞造或修改已有的token，致使資源服務器受權經過非法訪問的客戶端。所以須要對token使用數字簽名或消息認證碼來保證其完整性
• Token 泄露(Token disclosure)：Token自己可能包含認證、有效期等敏感信息。所以實現TLS並驗證證書是必選項，加密token可用於防止客戶端觀察token的內容，加密token還可防止token在前端服務器和後端服務器(若是他們沒有啓用TLS)之間發生泄露
• Token 改寄(Token redirect)：攻擊者用一個訪問A資源服務器的token去請求B資源服務器的資源。所以一般token中能夠包含表明資源服務器的標識來防止這種狀況的發生
• Token 重放(Token replay)：攻擊者企圖使用曾經使用過的token來請求資源。所以token需包含有效期(好比少於1小時)

 　　另外cookie不能包含token，關於cookie的安全弱點，RFC 6265 中有以下描述：

　　A server that uses cookies to authenticate users can suffer security
   vulnerabilities because some user agents let remote parties issue
   HTTP requests from the user agent (e.g., via HTTP redirects or HTML
   forms).  When issuing those requests, user agents attach cookies even
   if the remote party does not know the contents of the cookies,
   potentially letting the remote party exercise authority at an unwary
   server.

可見即便服務端實現了TLS，攻擊者依舊能夠利用cookie來獲取機密信息，若是cookie中包含機密信息的話；對此，不得已可將機密信息包含於URLs(前提是已實現了TLS)，但儘可能使用更安全的辦法，由於瀏覽器歷史記錄、服務器日誌等可能泄露URLs機密信息。

 

五. Transport Layer Security (TLS)

　　TLS (SSL / TLS)源於NetScape設計的SSL(Secure Sockets Layer，1994 / SSL 1.0、1995 / SSL 2.0、1996 / SSL 3.0)；1999年，IETF接替NetScape，發佈了SSL的升級版TLS 1.0，最新爲TLS 1.3(draft)，TLS 用於在兩個通訊應用程序之間提供保密性和數據完整性。目前，應用最普遍的是TLS 1.0，接下來是SSL 3.0，主流瀏覽器都已經實現了TLS 1.2的支持。TLS 1.0一般被標示爲SSL 3.1，TLS 1.1爲SSL 3.2，TLS 1.2爲SSL 3.3。獲取更多信息可參考 TLS 1.2 / RFC 5246 。

　　TLS是一種位於傳輸層(TCP)和應用層之間的協議層，由記錄協議(Record Layer)和握手協議(Handshake Layer)兩層構成：

 　　

　　TLS算法套件由三個部分組成：瞭解更多可參考 http://www.rfcreader.com/#rfc5246_line3649

　　

1. 密鑰交換算法：  RSA或Diffie-Hellman算法的各類變種
2. 加密算法：  AES, DES, Triple-DES, RC4, RC2, IDEA 或 none
3. 摘要算法：  MD5, SHA

 

六. application/x-www-form-urlencoded Media Type

　　首先application/x-www-form-urlencoded這種編碼類型未考慮非US ASCII字符的狀況，所以待編碼的內容(包括名稱、值)可先經UTF-8編碼，而後再按字節序列進行字符轉義操做；而接收這種數據類型則需進行逆向處理。一般各類web編程語言已經提供原生URL編碼/URL解碼接口(可能不一樣語言版本的URL編碼/解碼會有差別)，使用起來也極爲方便，所以這裏不作詳細介紹。

 

七. MAC Token

　　MAC Token與Bearer Token同樣，可做爲OAuth 2.0的一種Access Token類型，但Bearer Token纔是RFC建議的標準；MAC Token是在MAC Access Authentication中被定義的，採用Message Authentication Code(MAC)算法來提供完整性校驗。

　　MAC Access Authentication 是一種HTTP認證方案，具體內容可參考： HTTP Authentication: MAC Access Authentication draft-hammer-oauth-v2-mac-token-05 。