豆瓣 API OAuth认证

豆瓣 API OAuth认证

本文档提供豆瓣API OAuth认证的相关信息，如果你的应用需要访问或修改受保护的用户数据，请详细阅读本文档。

为了保护豆瓣用户的数据，当第三方应用需要通过API访问或修改受保护的用户数据（例如增删用户收藏）时，需要通过OAuth认证机制来获得用户的授权。

为了方便开发人员进行豆瓣 OAuth认证，我们在豆瓣OAuth认证示例项目中提供了常见语言环境下进行豆瓣 OAuth认证的示例代码。如果你使用或参考示例项目中的代码，而你对OAuth一无所知，那么你需要阅读我们在下面提供的认证及访问资源流程这部分内容。它可以帮助你理解OAuth的认证流程，这对于理解示例项目中的代码是必须的。同时你也需要阅读常见问题部分。

如果你不打算参考我们提供的示例代码，或者你所使用的语言不在我们提供的示例代码中。那么在开始尝试进行OAuth认证之前，你通常必须阅读整个OAuth规范。

无论你是何种开发人员——比如你也许已经是OAuth专家，我们都建议你阅读常见问题部分，以避免不必要的麻烦。

如果你发现本文档的某些部分难以理解，建议你阅读OAuth规范以获取更多信息。

另外一些可能有用的资源：

1. 关于豆瓣API Key的更多信息请点击这里
2. 中文翻译的OAuth文档可以在这里找到
3. Google-OAuth项目提供各种语言的OAuth库

目录

• 认证流程及访问资源流程
  • 获取未授权的 Request Token
  • 请求用户授权 Request Token
  • 使用授权后的 Request Token 换取 Access Token
  • 使用Access Token访问或修改受保护资源
• 常见问题

认证流程及访问资源流程

豆瓣API通过以下四个步骤来完成认证授权并访问或修改受限资源的流程

1. 获取未授权的Request Token
2. 请求用户授权Request Token
3. 使用授权后的Request Token换取Access Token
4. 使用 Access Token 访问或修改受保护资源

获取未授权的Request Token

通过访问以下 URL 获取未授权的 Request Token

http://www.douban.com/service/auth/request_token

包含的主要参数

参数	意义
oauth_consumer_key	API Key
oauth_signature_method	签名方法，建议使用HMAC-SHA1
oauth_signature	签名值
oauth_timestamp	时间戳
oauth_nonce	单次值，随机字符串，防止重放攻击

本步骤用于签名的secret是API Key Secret

返回值包括未授权的Request Token和对应的Request Token Secret

请求用户授权Request Token

获得Request Token之后，需要请求用户授权该Request Token

你需要将浏览器跳转到如下URL（如果无法自动跳转，则需要提示用户手工跳转）。这会是一个豆瓣上的页面，提示用户授权给你的应用，以允许你的应用访问该用户在豆瓣上的信息

http://www.douban.com/service/auth/authorize

跳转后用户会看到请求授权的页面，用户可以选择同意或者拒绝授权

该请求包含如下两个参数

参数	意义
oauth_token	上一步中获得的Request Token
oauth_callback（可选）	如果包含这个参数，认证成功后浏览器会被重定向到形如http://callback?oauth_token=ab3cd9j4ks73hf7g的url，其中oauth_token为Request Token 否则需要用户手工通知第三方应用以完成授权

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

用户完成授权后，第三方应用可以通过访问如下url，将已授权的Request Token换取Access Token。Access Token将被用于访问或修改受限资源

http://www.douban.com/service/auth/access_token

包含的主要参数

参数	意义
oauth_consumer_key	API Key
oauth_token	第一步中获得的Request Token
oauth_signature_method	签名方法
oauth_signature	签名值
oauth_timestamp	时间戳
oauth_nonce	单次值

本步骤用于签名的secret和token secret分别为，API Key Secret和Request Token Secret

返回值包括授权的Access Token，对应的Access Token Secret

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

获得Access Token之后，你的应用就可以使用该Access Token访问或修改受保护的资源

在每次操作受保护资源时，请求都必须包含以下参数

参数	意义
oauth_consumer_key	API Key
oauth_token	Access Token
oauth_signature_method	签名方法
oauth_signature	签名值
oauth_timestamp	时间戳
oauth_nonce	单次值

本步骤用于签名的secret和token secret分别为，API Key Secret和Access Token Secret

常见问题

关于用于签名的Secret

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

在第三步换取Access Token时，需要使用API Key、API Key Secret、Request Token和Request Token Secret进行签名。其中API Key和API Key Secret的对应不变。而Request Token和Request Token Secret对应签名中的Token和Token Secret

而在第四步访问修改受限资源时，需要使用API Key、API Key Secret、Access Token和Access Token Secret进行签名。

请注意区分三次签名中用到的Key、Token和Secret，这是签名不匹配的一个常见原因。

关于用户签名的url

签名时需要用到将要访问的url。例如:

    http://api.douban.com/people/sakinijino/collection

豆瓣OAuth认证，要求对这个url进行转义再计算签名，例如:

    http://api.douban.com/people/@me

需要被转义为

    http://api.douban.com/people/%40me

再计算签名。某些OAuth库默认不对url进行转义，你需要在传入url之前手工进行转义。这是签名不匹配的另一个原因。

关于在修改删除受限资源时传递OAuth参数

OAuth规范定义了三种传递OAuth参数方式

1. header中
2. url中
3. post form中

然而进行POST、PUT、DELETE请求时，豆瓣暂时不支持使用在url中或者post form中传递OAuth参数。因此你只能选择在header中传递OAuth参数。格式如下：

Authorization: OAuth realm="http://sp./",
    oauth_consumer_key="0685bd9184jfhq22",
    oauth_token="ad180jjd733klru7",
    oauth_signature_method="HMAC-SHA1",
    oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
    oauth_timestamp="137131200",
    oauth_nonce="4572616e48616d6d65724c61686176",
    oauth_version="1.0"

如果你发现豆瓣提示你没有传递OAuth参数（no auth错误），那么请检查一下你是否在POST、PUT、DELETE请求中使用了url或post form传递OAuth参数。