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 。