OAuth文档

1 开心网OAuth1.0a简介

开心网已采用OAuth1.0a协议为第三方网站/客户端提供连接服务,遵循[RFC-5849]规范。OAuth协议为用户资源的授权提供了一个安全的、开放而又简易的标准。有关OAuth认证的详细说明,请到OAuth官网阅读官方OAuth规范说明。

使用开心网的OAuth1.0a API,需要先申请一个组件(开发类型务必选择“连接开心网”),我们会给每个组件一个专属的API Key和Secret Key。Key跟Secret的使用方式跟其他一些协议中的公钥私钥的方案相类似,你可以使用你所熟悉的编程语言将key和secret结合,为你发出的每个请求添加签名。

2 OAuth1.0a流程

OAuth1.0a基本流程如下图所示:

2.1 请求签名

所有的OAuth请求使用同样的算法来生成(signature base string)签名字符基串和签名。 base string是把http方法名、请求URL以及请求参数用&字符连起来后做URL Encode编码。具体来讲,base string由http方法名,之后是&,接着是过url编码(url-encoded)之后的url和访问路径及&。接下来,把所有的 请求参数包括POST方法体中的参数,经过排序(按参数名进行文本排序,如果参数名有重复则再安参数值进行重复项目排序),使用%3D替代=号,并且使 用%26作为每个参数之间的分隔符,拼接成一个字符串。 这个算法可以简单表示为:

httpMethod + "&" +
          url_encode(  base_uri ) + "&" +
          sorted_query_params.each  { | k, v |
              url_encode ( k ) + "%3D" +
              url_encode ( v )
          }.join("%26")

无论生成何种OAuth1.0请求,生成BASE STRING的规则始终不变。

2.2 获取未授权的Request Token

接口地址:http://api.kaixin001.com/oauth/request_token

支持格式:OAuth HTTP 标准认证返回格式

HTTP请求方式:GET

是否需要登录:否

请求参数:

参数名 必选介绍
oauth_consumer_key trueAPI Key(组件信息中的API Key值)
oauth_signature_method true签名方法,暂只支持HMAC-SHA1
oauth_signature true签名值,密钥为:API Secret&
oauth_timestamp true时间戳,其值是距1970 00:00:00 GMT的秒数,必须是大于0的整数
oauth_nonce true单次值,随机生成的32位字符串(每次请求必须不同)
oauth_callback true认证成功后浏览器会被重定向到这个url中
oauth_version false版本号,如果填写必须为1.0
scopefalse以空格分隔的权限列表,若不传递此参数,代表请求默认的basic权限。
如需调用扩展权限,必需传递此参数,详细请参考权限列表

返回参数:

参数名 必选意义
oauth_token true未授权的Request Token
oauth_token_secret true对应的Request Token Secret
oauth_callback_confirmed true对oauth_callback的确认信号 (true/false)

返回示例:

oauth_token=db3286aeb8e3e71ff023&oauth_token_secret=ff628b09b4b6c68572cc7c7f15ed757e&oauth_callback_confirmed=true

说明:

① 用户授权后web应用将会重定向到oauth_callback。当应用为pc客户端或手机客户端应用时,没有回调
url(oauth_callback)的概念,此时设置为字符串”oob”即可,字符串“oob”必须是小写。
② 时间戳与标准时间偏差不得大于10分钟。

2.3 请求用户授权Request Token

接口地址:http://api.kaixin001.com/oauth/authorize

支持格式:OAuth HTTP 标准认证返回格式

HTTP请求方式:GET

是否需要登录:否

请求参数:

参数名 必选意义
oauth_token true上一步中获得的未授权的Request Token
forcelogin false是否强制登录。强制登录:forcelogin=1;不强制登录,无需此参数

返回参数:

参数名 必选意义
oauth_token true用户授权之后的Token值,与未授权Token值相同
oauth_verifier true验证码

说明:

①此页面中会要求用户登录,然后选择同意或者拒绝对应用授权。
②授权成功后:
 A: web应用会重定向到oauth_callback所指定的URL(含返回参数) 
 B: 客户端应用(oauth_callback=oob)会在网页中给出授权码,用户需要手工将验证码输入到应用中才能完成授权流程

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

接口地址:http://api.kaixin001.com/oauth/access_token

支持格式:OAuth HTTP 标准认证返回格式

HTTP请求方式:GET

是否需要登录:否

请求参数:

参数名 必选意义
oauth_consumer_key trueAPI Key
oauth_token true第一步中获得的Request Token
oauth_signature_method true签名方法,暂只支持HMAC-SHA1
oauth_signature true签名值,(密钥为:API Secret&Request Token Secret)
oauth_timestamp true时间戳, 其值是距1970 00:00:00 GMT的秒数,必须是大于0的整数
oauth_nonce true单次值,随机生成的32位字符串,防止重放攻击(每次请求必须不同)
oauth_verifier true上一步请求授权request token时返回的验证码
oauth_version flase版本号,如果填写必须为1.0

返回参数:

参数名 必选意义
oauth_token trueAccess Token
oauth_token_secret trueAccess Token Secre

返回示例:

oauth_token=db3286aeb8e3e71ff023&oauth_token_secret=ff628b09b4b6c68572cc7c7f15ed757e

说明:

①本步骤用于签名的密钥为App Secret和Request Token Secret(中间使用&分隔) 
②获得返回值后就可以使用Access Token来访问资源了
③Access Token和Access Token Secret永远不会过期,直到用户撤销授权或开心网回收app访问权限才会失效

2.5 使用Access Token访问或修改受保护资源

获取access_token以后,就可以调用API2.0各功能接口了,详情请参考API2.0说明,如需查看示例请点击API2.0调用示例。使用Access Token无法调用1.2版本的API。

3 注意事项

1) OAuth提供两种认证方式:query-string和http headers。我们推荐使用http header进行认证。

2) 目前开心网开放平台只支持使用HMAC-SHA1 签名方法。

3) 在第一步获取Request Token时,需要使用API Key和API Key Secret进行签名。对应到OAuth规范中,API Key对应Consumer Key, Secret key对应Consumer Key Secret。该步不需要使用Token和Token Secret——设为空字符串即可。

4) 推荐始终使用显式oauth_callback。应用程序申请时可能指定了callback地址,但是我们建议每次请求都显式声明callback(在请求中指定callback)。通过动态设定callback,你可以获取一些有用的附加的信息。如果是使用PIN码的话,callback应该是”oob”。
 
备注:有关OAuth2.0的开发说明,请参考OAuth2.0文档