OAuth授权验证说明
OAuth授权验证说明
1.1. OAuth介绍
OAuth (开放授权) 是一个开放标准，允许用户授权第三方网站访问他们存储在另外的服务提供者上的信息，而不需要将用户名和密码提供给第三方网站或分享他们数据的所有内容。为了保护凡客用户的数据，所有第三方应用都需要通过OAuth认证机制来获得用户的授权。本文档提供了凡客开放平台OAuth认证的相关信息。
凡客开放平台API采用OAuth协议为第三方提供接入服务，有关OAuth认证的详细说明，请阅读官方OAuth规范。
－OAuth标准（英文） http://oauth.net/
－OAuth维基百科（中文） http://zh.wikipedia.org/zh/OAuth
凡客开放平台API使用OAuth 1.0a版本。
Web应用、桌面应用和手机应用如何通过凡客开放平台服务器认证这一过程就是OAuth协议的主要内容。这一过程中可以抽象出三个角色：Server(Service Provider)，Client(Consumer)， User(Resource Owner)。在凡客开放平台中，这三个的角色(实例化后)是: 凡客开放平台服务端，第三方应用，凡客用户。
1.2. 使用说明
为了使用凡客开放平台提供的API(应用程序接口)，我们会给每一个应用一个专属的oauth_consumer_key和oauth_consumer_ Secret。
OAuth的登录认证流程及访问资源流程
OAuth的注册认证流程及访问资源流程
OAuth定义的认证过程分三步：
1. Client从server获取未授权的RequestToken
2. User授权Client获取的RequestToken，client获取oauth_verifier (授权码)
3. Client以RequestToken和oauth_verifier从server获取AccessToken，AccessTokenSecret,UserId，UserToken 在此过程中RequestToken是一个临时性的东西。完成这三步后，RequestToken就失去价值了。另外RequestToken在一段时间内没有使用，也会过期从而失效。而AccessToken是一个持久性的东西，它是user对client的授权凭证，会一直有效。Client只需要保存UserId，AccessToken(即oauth_token)，AccessTokenSecret(即oauth_token_secret)，其中UserId，AccessToken两个参数是访问需要用户登录授权API所需要传入的参数值，而AccessTokenSecret是访问需要用户登录授权API签名时需要的值。
4、使用UserId，AccessToken访问或修改受保护,需要用户登录授权的API。
认证过程中第一步和第三步发送的请求是需要签名的。
请求签名说明
所有请求和受保护的资源请求必须被签名。签名算法使用Signature Base String和密钥（Secret）生成签名。
说明
Signature Base String由以下三部分组成，各项之间使用&符号分隔。
1、Http Method
请求方法，GET/POST
2、URL Encode之后的请求URL（URL要小写）
例如：
请求URL：http://oapi.vancl.com/oauthnew/request-token.ashx
经URL Encode之后的请求URL为：
http%3A%2F%2F oapi.vancl.com%2Foauthnew%2Frequest-token.ashx
3、URL Encode并排序之后的请求参数
例如： URL请求参数为：
oauth_callback=http%3A%2F%2Flocalhost%3A60001%2FDemoWeb%2Fdemo.aspx&oauth_consumer_key=de47ea4337b847e09a9489b43373c845&oauth_nonce=3c7fa628eb92441c8e8a2f8147a72193&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1321580558&oauth_version=1.0
经URL Encode并排序(如果参数名有重复则再按参数值进行重复项目排序)之后的请求参数格式如下（使用%3D替代=号，参数间使用%26(即&符号)分隔）：
oauth_callback%3Dhttp%253A%252F%252Flocalhost%253A60001%252FDemoWeb%252Fdemo.aspx%26oauth_consumer_key%3Dde47ea4337b847e09a9489b43373c845%26oauth_nonce%3D3c7fa628eb92441c8e8a2f8147a72193%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1321580558%26oauth_version%3D1.0
三部分拼接后即为Signature Base String的值,如下:
GET&http%3A%2F%2Foapi.vancl.com%2Foauthnew%2Frequest-token.ashx&oauth_callback%3Dhttp%253A%252F%252Flocalhost%253A60001%252FDemoWeb%252Fdemo.aspx%26oauth_consumer_key%3Dde47ea4337b847e09a9489b43373c845%26oauth_nonce%3D3c7fa628eb92441c8e8a2f8147a72193%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1321580558%26oauth_version%3D1.0
密钥由oauth_consumer_secret和Request Token Secret组成（中间使用&符号分隔）。
第一步签名密钥为:oauth_consumer_secret;
第三步签名密钥为：oauth_consumer_secret &Request Token Secret;
1.3. OAuth认证流程简介
1.3.1. 获取未授权的request token
获取request token是进行用户认证的第一步。这一步主要有两个目的：
第一，告诉凡客开放平台你将要做什么
第二，告诉凡客开放平台你在callback里要做什么
app发送HTTP GET请求到http://oapi.vancl.com/oauthnew/request-token.ashx获取request_token 此时，app所拥有的信息只有: oauth_consumer_key和oauth_consumer_secret。oauth_consumer_key是app的唯一标识。要想去凡客开放平台服务器请求token，必须告诉它是谁在请求，所以这个参数必须传递给服务器。oauth_consumer_secret是凡客开放平台为每个app分配的用以进行机密数据交换的密钥。(这是一个保密项,不要公开否则别人可能会冒你的名去发送请求)，oauth_consumer_secret主要用来进行数据签名。
请求参数
| 参数 | 意义 |
| oauth_consumer_key | 凡客开放平台分配的应用的唯一KEY标记 |
| oauth_signature_method | 签名方法， HMAC-SHA1 (固定) |
| oauth_signature | 签名值，密钥为：oauth_consumer_secret。计算说明。 |
| oauth_timestamp | 时间戳, 其值是距1970 00:00:00 GMT的秒数，必须是大于0的整数 |
| oauth_nonce | 单次值，随机生成的32位字符串，防止重放攻击（每次请求必须不同） |
| oauth_callback | 认证成功后浏览器会被重定向到这个url中 |
| oauth_version | 版本号， “1.0” (固定) |
返回参数
| 参数 | 意义 |
| oauth_token | 未授权的Request Token |
| oauth_token_secret | 对应的Request Token Secret |
| oauth_callback_confirmed | 对oauth_callback的确认信号, 为true表示回调地址生效 |
说明：
用户授权后web应用将会重定向到oauth_callback，此url必须以http://开头。
时间戳与标准时间偏差不得大于8分钟。
假如有一款应用:
oauth_consumer_key = “873786fd712936a3a1f3cc9b8b1a6b94”
oauth_consumer_secret = “3a58dd9023cf1adec08f0656acc5bf95”
示例
请求参数:
返回参数
| 参数名称 | 参数值 |
| oauth_consumer_key | 873786fd712936a3a1f3cc9b8b1a6b94 |
| oauth_signature | oauth_signature为"7M1b9CG32KsclajAVXrHzPdE238="URI编码后为"7M1b9CG32KsclajAVXrHzPdE238%3d |
| oauth_nonce | 774d4d2fb95a49628bbd109a79139117 |
| oauth_timestamp | 1321582909 |
| oauth_signature_method | HMAC-SHA1 |
| oauth_version | 1.0 |
| oauth_callback | http%3A%2F%2Flocalhost%3A60001%2FDemoWeb%2Fdemo.aspx |
Base string的生成
| Base String | GET&http%3A%2F%2Foapi.vancl.com%2Foauthnew%2Frequest-token.ashx&oauth_callback%3Dhttp%253A%252F%252Flocalhost%253A60001%252FDemoWeb%252Fdemo.aspx%26oauth_consumer_key%3D873786fd712936a3a1f3cc9b8b1a6b94%26oauth_nonce%3D774d4d2fb95a49628bbd109a79139117%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1321582909%26oauth_version%3D1.0 |
使用signing key(oauth_consumer_secret后加一个&符)生成oauth_signature：
| signature | 7M1b9CG32KsclajAVXrHzPdE238%3d |
返回结果
| 参数名称 | 参数值 |
| oauth_token | 1a6b213f81ef48b4b94524c2cfff50d0 |
| oauth_token_secret | 2c52bae787544992b20f21e01635ab67 |
| oauth_callback_confirmed | true |
请求格式如下：
http://oapi.vancl.com/oauthnew/request-token.ashx?oauth_callback=http%3A%2F%2Flocalhost%3A60001%2FDemoWeb%2Fdemo.aspx&oauth_consumer_key=873786fd712936a3a1f3cc9b8b1a6b94&oauth_nonce=774d4d2fb95a49628bbd109a79139117&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1321582909&oauth_version=1.0&oauth_signature=7M1b9CG32KsclajAVXrHzPdE238%3d
当服务器端接到请求之后，会返回包含oauth_token,oauth_token_secret,oauth_callback_confirmed等内容，另外oauth_callback_confirmed字段如果为true就表示callback生效。
服务器端的响应如下:
oauth_token=1a6b213f81ef48b4b94524c2cfff50d0&oauth_token_secret=2c52bae787544992b20f21e01635ab67&oauth_callback_confirmed=true
此时返回的oauth_token即为RequestToken, oauth_token_secret即为RequestTokenSecret。这时需要将oauth_token和oauth_token_secret记下，我们需要用这个参数来获取access token。
1.3.2. 用户授权认证
app发送HTTP GET请求到http://oapi.vancl.com/oauthnew/authorize.aspx获取授权码(oauth_verifier)。(说明：如果是注册，则请求地址为http://oapi.vancl.com/oauthnew/UserRegister.aspx,其他与oauth登录认证方式完全一样)要求必须以oauth_token作为参数,一般来说请求格式如下:
http://oapi.vancl.com/oauthnew/authorize.aspx?oauth_token=1a6b213f81ef48b4b94524c2cfff50d0
请求参数:
| 参数名称 | 说明 |
| oauth_token | 上一步中获得的未授权的Request Token |
返回参数:
| 参数名称 | 说明 |
| oauth_token | 用户授权之后的Token值, 与未授权Token值相同 |
| oauth_verifier | 签名值，方便第三方来验证来源的可靠性 |
示例
请求参数:
| 参数名称 | 说明 |
| oauth_token | 1a6b213f81ef48b4b94524c2cfff50d0 |
返回结果:
| 参数名称 | 说明 |
| oauth_token | 1a6b213f81ef48b4b94524c2cfff50d0 |
| oauth_verifier | NlbRvOzRqxWzarCpdq8xgA== |
说明：
①此页面中会要求用户登陆凡客，然后选择同意或者拒绝对应用授权。
②授权成功后：
web应用会重定向到oauth_callback所指定的URL（其中包含oauth_token和oauth_verifier）。 客户端应用(oauth_callback=null)会在网页中给出授权码，用户需要手工将验证码输入到应用中才能完成授权流程。
oauth_callback用来登录成功后，回调到第三方应用的页面。回调后, oauth_callback应该已经接到返回的信息,其中包含oauth_token和oauth_verifier。样例如下： oauth_token=1a6b213f81ef48b4b94524c2cfff50d0&oauth_verifier=NlbRvOzRqxWzarCpdq8xgA==
1.3.3. 获取access token
app发送HTTP GET请求到http://oapi.vancl.com/oauthnew/access-token.ashx获取access_token
请求参数:
| 参数 | 说明 |
| oauth_consumer_key | 应用的唯一KEY标记 |
| oauth_token | 第一步中获得的Request Token |
| oauth_signature_method | 签名方法，暂只支持HMAC-SHA1 |
| oauth_signature | 签名值，密钥为：oauth_consumer_secret &Request Token Secret。 |
| oauth_timestamp | 时间戳, 其值是距1970 00:00:00 GMT的秒数，必须是大于0的整数 |
| oauth_nonce | 单次值，随机生成的32位字符串，防止重放攻击（每次请求必须不同） |
| oauth_verifier | 上一步请求授权request token时返回的授权码 |
| oauth_version | 版本号，必须为“1.0” |
返回参数：
| 参数 | 说明 |
| oauth_token | 具有访问权限的token(Access token) |
| oauth_token_secret | Access token的密钥 |
| user_id | 用户ID |
| UserToken | 用户token |
示例
请求参数：
| 参数 | 参数值 |
| oauth_consumer_key | 873786fd712936a3a1f3cc9b8b1a6b94 |
| oauth_token | 1a6b213f81ef48b4b94524c2cfff50d0 |
| oauth_signature | BhZMohRRgjFrWBRi6qL993XuGXQ%3d |
| oauth_nonce | 9ae3a3b8051b466c85c8d0107c8423c3 |
| oauth_timestamp | 1321584266 |
| oauth_signature_method | HMAC-SHA1 |
| oauth_version | 1.0 |
| oauth_verifier | NlbRvOzRqxWzarCpdq8xgA== |
Base string的生成
| Base String | GET&http%3A%2F%2Foapi.vancl.com%2Foauthnew%2Faccess-token.ashx&oauth_consumer_key%3D873786fd712936a3a1f3cc9b8b1a6b94%26oauth_nonce%3D9ae3a3b8051b466c85c8d0107c8423c3%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1321584266%26oauth_token%3D1a6b213f81ef48b4b94524c2cfff50d0%26oauth_verifier%3DNLBRVOZRQXWZARCPDQ8XGA%253D%253D%26oauth_version%3D1.0 |
使用signing key(Consumer Secret和Request Token Secret中间使用&分隔)生成oauth_signature：
| signing key | 3a58dd9023cf1adec08f0656acc5bf95&2c52bae787544992b20f21e01635ab67 |
| signature | BhZMohRRgjFrWBRi6qL993XuGXQ%3d |
返回结果
| 参数名称 | 参数值 |
| oauth_token | 22d9af8dadd445128b2f7e4c3092470c |
| oauth_token_secret | a01f08a98c734e4488a5b8b6c8a42d20 |
| user_id | 31347780 |
| UserToken | e8f45c004264e721adbb78bc369cbdbb |
请求格式为：
http://oapi.vancl.com/oauthnew/access-token.ashx?oauth_consumer_key=873786fd712936a3a1f3cc9b8b1a6b94&oauth_nonce=9ae3a3b8051b466c85c8d0107c8423c3&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1321584266&oauth_token=1a6b213f81ef48b4b94524c2cfff50d0&oauth_verifier=NLBRVOZRQXWZARCPDQ8XGA%3D%3D&oauth_version=1.0&oauth_signature=BhZMohRRgjFrWBRi6qL993XuGXQ%3d
凡客开放平台会返回应用需要的信息，包括 UserId,UserToken，oauth_token，oauth_token_secret(当然这里就是AccessToken与AccessTokenSecret了)。 response内容如下：
oauth_token=22d9af8dadd445128b2f7e4c3092470c&oauth_token_secret=a01f08a98c734e4488a5b8b6c8a42d20&user_id=31347780& UserToken=e8f45c004264e721adbb78bc369cbdbb
现在就可以使用UserId,oauth_token,oauth_token_secret来访问服务端API啦。
