Oauth

superisaac edited this page Dec 14, 2011 · 5 revisions
Clone this wiki locally

饭否API OAuth认证

使用饭否OAuth需要在v2ex发帖申请一个饭否应用,获得批准后,可以在 http://fanfou.com/apps 看到应用的详细信息, 其中Consumer Key以及Consumer Secret是应用独有的,Consumer Secret只参与签名,请勿作为请求直接发出.

认证流程和访问流程

  1. 获取未授权的Request Token
  2. 请求用户授权Request Token,有回调url和pin码两种返回形式。
  3. 使用授权后的Request Token换取Access Token
  4. 使用 Access Token 访问饭否API

获取未授权的Request Token

应用向饭否服务器发出GET请求 URL http://fanfou.com/oauth/request_token

请求参数

参数 意义
oauth_consumer_key 饭否应用的API Key
oauth_signature_method 签名方法,目前只支持HMAC-SHA1
oauth_signature 签名值,签名方法见OAuthSignature
oauth_timestamp 时间戳,取当前时间
oauth_nonce 单次值,随机的字符串,防止重复请求

响应

  • 请求失败 返回HTTP code 401, 表示需要认证.
  • 请求成功 返回HTTP code 200以及经过经过urlencode的授权request token, 格式如
    oauth_token=8ldIZyxQeVrFZXFOZH5tAwj6vzJYuLQpl0WUEYtWc&oauth_token_secret=x6qpRnlEmW9JbQn4PQVVeVG8ZLPEx6A0TOebgwcuA
    
    应用需要将oauth_token和oauth_token_secret的值保存起来以备后面的签名

请求用户授权Request Token

用户得到Request Token后需要获得用户的授权,才能表示此Request Token 是合法的

应用需要将浏览器重定向至 http://fanfou.com/oauth/authorize?oauth_token=request_token&oauth_callback=callback_url 或者 http://m.fanfou.com/oauth/authorize?oauth_token=request_token&oauth_callback=callback_url

采用m.fanfou.com/oauth/authorize或者fanfou.com/oauth/authorize作为获取用户授权地址都是可行的,如果用户从手机浏览器访问,建议采用http://m.fanfou.com作为获取授权地址.

oauth_token

上一步获得的Request Token

oauth_callback

一个回调URL, 当用户同意授权给应用时,饭否服务器会使用户的浏览器再重定向到地址oauth_callbck?oauth_token=request_token 进行下一步操作。

如果应用是桌面客户端等非网站程序,则可以采用带PIN码的authorize过程,将oauth_callback的值设置为oob(out of band)即可.

使用授权后的Request Token换取Access Token

此处方法应该写在上述回调URL oauth_callback

应用获得用户授权以后,应用可以通过访问URL http://fanfou.com/oauth/access_token 用授权的Request Token换取Access Token

请求参数

参数 意义
oauth_consumer_key 饭否应用的API Key
oauth_token 通过以上步骤获得的Request Token
oauth_signature_method 签名方法,目前只支持HMAC-SHA1
oauth_signature 签名值,签名方法见OAuthSignature
oauth_timestamp 时间戳,取当前时间
oauth_verifier [可选]授权码
oauth_nonce 单次值,随机的字符串,防止重复请求

响应

  • 如果失败,返回HTTP code 401, 并附上错误的说明, 详情请见 OAuthErrors
  • 如果成功,返回HTTP code 200 以及如下格式的access_token
    oauth_token=891212-3MdIZyxPeVsFZXFOZj5tAwj6vzJYuLQplzWUmYtWd&oauth_token_secret=x6qpRnlEmW9JbQn4PQVVeVG8ZLPEx6A0TOebgwcuA
    
    应用需要保存Access Token并凭此访问饭否API

使用PIN码获得授权

如果应用是桌面程序,不方便实现oauth_callback, 则可以使用带PIN码授权的方案。基本步骤如下

  1. 程序在调用饭否服务器的/oauth/authorize时,将oauth_callback的值设置为oob(Out Of Band)传递给服务器,服务器则知道应用将采用OOB方式
  2. 当用户点击授权页面的“愿意” 按钮后,服务器将显示一个写有随机授权码的页面,用户可以copy此字串
  3. 应用应该实现一个用以输入授权码(pin)的输入框,获得用户输入的pin码,将其填入参数oauth_verifier发送/oauth/access_token请求以获得access_token, 其余过程同上一节一致。

使用Access Token访问饭否API

获得Access token后,就可以使用之访问饭否API提供的资源了

每次API请求需要包含如下参数

参数 意义
oauth_consumer_key 饭否应用的API Key
oauth_token **Access Token**
oauth_signature_method 签名方法,目前只支持HMAC-SHA1
oauth_signature 签名值,签名方法见OAuthSignature
oauth_timestamp 时间戳,取当前时间
oauth_nonce 单次值,随机的字符串,防止重复请求