平台技术-用户授权介绍
登录授权
如果您的应用和淘宝开放平台对接时需要获取用户隐私数据（如商品、订单等），为保证用户数据的安全与隐私，您的应用需要取得用户的授权，即获取访问用户数据的授权令牌 Access Token （即原来的SessionKey）。这种情况下，您的应用需要引导用户完成使用淘宝帐号“登录授权”的流程。该流程采用国际通用的OAuth2.0标准协议作为用户身份验证与授权协议，支持网站、手机客户端、桌面客户端。
目前淘宝OAuth2.0服务支持采用两种方式获取Access Token（授权令牌），即 Server-side flow 和 Client-side flow ，详见如下说明。
注：Taobao ID（淘帐号）产品不得用于阿里巴巴集团非官方渠道为淘宝买家提供淘宝会员类服务（如：订单查询、物流追踪 等），一旦发现违规使用，开放平台将立即收回该appkey的Taobao ID使用权限。
特别注意
此文档描述的授权页面仅适用于PC端，如果您的页面是在手机淘宝/天猫客户端中被访问，请参考这里。如果您的页面是在H5手机浏览器中被访问，请参考这里。
一、Server-side flow
此流程要求ISV应用有Web Server应用，能够保存应用本身的密钥以及状态，可以通过https直接访问淘宝的授权服务器。
1、请求入口地址
1）获取授权码（code）
正式环境：https://oauth.taobao.com/authorize
沙箱环境：https://oauth.tbsandbox.com/authorize
2）获取访问令牌（access_token）
正式环境：https://oauth.taobao.com/token
沙箱环境：https://oauth.tbsandbox.com/token
2、授权操作步骤
此处以正式环境获取acccess_token为例说明，如果是沙箱环境测试，需将请求入口地址等相关数据换成沙箱对应入口地址，操作流程则同正式环境一致。
实际进行授权操作时，测试的数据 client_id、client_secret、redirect_uri 均需要根据自己创建的应用实际数据给予替换，不能拿示例中给出的值直接进行测试，以免影响实际测试效果。下图为Server-side flow 授权方式流程图，以下按流程图逐步说明。
1）拼接授权url
拼接用户授权需访问url ，示例及参数说明如下：
https://oauth.taobao.com/authorize?response_type=code&client_id=23075594&redirect_uri=http://www.oauth.net/2/&state=1212&view=web
3）获取code2）引导用户登录授权
引导用户通过浏览器访问以上授权url，将弹出如下登录页面。用户输入账号、密码点“登录”按钮，即可进入授权页面。
上图页面，若用户点“授权”按钮后，TOP会将授权码code 返回到了回调地址上，应用可以获取并使用该code去换取access_token；
若用户未点授权而是点了“取消”按钮，则返回如下结果，其中error为错误码，error_description为错误描述。分别如下图所示：
说明：
可发布服务市场（fuwu.taobao.com）的应用，在应用上线后，如购买应用的用户，通过"我的服务--立即使用”访问（下图)，系统会自动跳到授权页面（因此这种方式访问应用的，不需要拼接url），只需注意获取code即可。同时返回code时，还会返回通过state传递订购服务相关的信息，类似：
state=versionNo:1;itemCode:xxxxx （versionNo 为应用版本号、itemCode为应用收费代码）
4）换取access_token
利用linux 的curl 命令 获取access_token（授权令牌），如下；对于应用程序，可以参考文档**示例**这里的示例代码。
curl -i -d "code=OxlukWofLrB1Db1M6aJGF8x2332458&grant_type=authorization_code&client_id=23075594&
client_secret=69a1469a1469a1469a14a9bf269a14&redirect_uri=http://www.oauth.net/2/ "https://oauth.taobao.com/token
| { "w2_expires_in": 0, "taobao_user_id": "263685215", "taobao_user_nick": "%E5%95%86%E5%AE%B6%E6%B5%8B%E8%AF%95%E5%B8%90%E5%8F%B752", "w1_expires_in": 1800, "re_expires_in": 0, "r2_expires_in": 0, "expires_in": 86400, "token_type": "Bearer", "refresh_token": "6200e1909ca29b04685c49d67f5ZZ3675347c0c6d5abccd263685215", "access_token": "6200819d9366af1383023a19907ZZf9048e4c14fd56333b263685215", "r1_expires_in": 1800 } |
换取access_token返回值示例
二、Client-side flow
客户端应用授权方式，适合ISV没有独立的web Server，但是能够借助浏览器或者JS脚本访问授权服务器的应用。
1、请求入口地址
正式环境：https://oauth.taobao.com/authorize
沙箱环境：https://oauth.tbsandbox.com/authorize
2、授权操作步骤
以正式环境获取acccess_token为例说明，如果是沙箱环境请使用沙箱数据。
同时在授权过程中client_id等参数需要根据自己创建应用的实际数据给予替换，否则无法完成授权。
下图为Client-side flow 授权方式流程图，以下按流程图逐步详细说明
1）拼接授权url
https://oauth.taobao.com/authorize?response_type=token&client_id=23075594&state=1212&view=web
2）导用户登录授权
这一步同Server-side flow授权方式，引导用户访问授权url 进行授权，如下。
3）获取access_token
此处上图页面点授权后，TOP会直接将access_token 返回到淘宝默认页面（和 Server-side flow 先返回code 再换access_token方式不同）此时可使用JS脚本（if(window.location.hash!=""){alert(window.location.hash)}）可以获取回调页面#后面的字段，从而获取到访问令牌。
返回参数示例：
https://oauth.taobao.com/oauth2?view=web#access_token=6101227f5e8c230696ac93a77b3de7daacb154c6ad98106263664221&token_type=Bearer&expires_in=86400&refresh_token=6100627e3f9202c0960a6ab5bfd704939c91635892c70dd263664221&re_expires_in=86400&r1_expires_in=86400&r2_expires_in=86400&taobao_user_id=263664221&taobao_user_nick=%E5%95%86%E5%AE%B6%E6%B5%8B%E8%AF%95%E5%B8%90%E5%8F%B717&w1_expires_in=86400&w2_expires_in=86400&state=1212&top_sign=3429C556FCD3F3FC52547DD31021592F
注：
此处参数返回除 top_sign 外，同Server-side flow授权返回参数相同，这里不再详细描述，具体可参考 Server-side flow 里面的说明。
top_sign 是系统生成签名参数，使用 Client-side flow 方式授权需要对该参数进行一致性验证。
4） 验证授权签名
即验证返回参数和 top_sign 是否一致。如上返回参数中，把井号之后除 top_sign外所有key和value按照参数的首字母顺序排列，以 key1+value+key2+value....的方式拼接在一起，再在其前后加上的AppSecret（假设AppSecret=69a1469a1469a1469a14a9bf269a14），然后转成utf-8编码，接着进行md5加密，最后全部转大写即可。
md5(utf-8:AppSecret+k1+v1+k2+v2+...+kn+vn + AppSecret)。
如以下返回参数，取 # 号之后的参数进行拼接并首尾加上AppSecret后得到如下结果：
69a1469a1469a1469a14a9bf269a14access_token6101227f5e8c230696ac93a77b3de7daacb154c6ad98106263664221token_typeBearer
expires_in86400refresh_token6100627e3f9202c0960a6ab5bfd704939c91635892c70dd263664221re_expires_in86400r1_expires_in86400
r2expires_in86400taobao_user_id263664221taobao_user_nick%E5%95%86%E5%AE%B6%E6%B5%8B%E8%AF%95%E5%B8%90%E5%8F%B717w1_expires_in86400&w2_expires_in86400&state121269a1469a1469a1469a14a9bf269a14
进行md5加密（参考API调用示例代码）并转化成大写后得到：3429C556FCD3F3FC52547DD31021592F ，和top_sign 一致。
退出登录
退出流程目前只支持web访问，起到的作用是清除taobao.com的cookie，并不是取消用户的授权。在WAP上访问无效。
一、请求入口地址
1、正式环境：https://oauth.taobao.com/logoff
2、沙箱环境：https://oauth.tbsandbox.com/logoff
二、退出操作步骤
拼接退出url（如https://oauth.taobao.com/logoff?client_id=12304977&view=web）并访问即可，退出后跳转到淘宝首页 。
刷新授权
通过授权获取的refresh_token，可用来刷新access token 的r2时长。
由于r1 或w1 通常同订购时长一致，一般不需刷新，w2必须通过重新授权给予延长，故refresh_token 一般仅用于r2 有效时长的延长。
操作方法类似获取access token ，仅请求参数有区别，说明如下：
相关说明
一、授权时长说明
授权获得的 access_token 有效时长（expires_in ）和标签类型（如IT工具、商家后台系统等）、状态（如正式环境、上线等）相关如下。
注：实际api 调用时，对应用授权时长做了更精确的控制，具体可参考（二、安全等级说明）；另像“第三方IT工具”类应用开发上线后都是发布在 fuwu.taobao.com上，卖家需要订购使用，相应授权时长会和订购时长相同，如购买1个月，则取得的access_token有效时长1个月。
二、安全等级说明
为了更加灵活的对淘宝开放平台开放的数据进行安全管控， 降低用户数据泄露或者被恶意修改的风险，推出了安全等级的概念。
淘宝开放平台对API（或者API字段）及 应用分别打了r1、r2、w1、w2 和 0,1,2,3四种安全级别的标记。与 r1、r2、w1、w2对应的是在access token（session key）颁发时增加了4个过期时间：r1_expires_in、r2_expires_in、w1_expires_in、w2_expires_in。这4个值分别用来表示此access token 调用各级别API（或字段）的有效期,如下:(受安全等级限制的应用有：第三方IT工具、服务商后台系统、店铺模块后台这3类应用；商家后台系统和新业务这类卖家自用型应用暂不受影响。)
| 安全等级 | API级别 | 正式环境测试 | 上线运行中 | 是否可刷新 | Refresh刷新时长 |
|---|---|---|---|---|---|
| 3级 | R1 | 24小时 | 同订购时长 | 是 | 已上线应用与订购时长一致，正式环境测试24小时有效 |
| 3级 | R2 | 24小时 | 同订购时长 | 是 | 已上线应用与订购时长一致，正式环境测试24小时有效 |
| 3级 | W1 | 24小时 | 同订购时长 | 是 | 已上线应用与订购时长一致，正式环境测试24小时有效 |
| 3级 | W2 | 24小时 | 同订购时长 | 是 | 已上线应用与订购时长一致，正式环境测试24小时有效 |
| 2级 | R1 | 24小时 | 同订购时长 | 是 | 已上线应用与订购时长一致，正式环境测试24小时有效 |
| 2级 | R2 | 24小时 | 72小时 | 是 | 已上线应用与订购时长一致，正式环境测试24小时有效 |
| 2级 | W1 | 24小时 | 同订购时长 | 是 | 已上线应用与订购时长一致，正式环境测试24小时有效 |
| 2级 | W2 | 30分钟 | 30分钟 | 否 | |
| 1级 | R1 | 24小时 | 同订购时长 | 是 | 已上线应用与订购时长一致，正式环境测试24小时有效 |
| 1级 | R2 | 24小时 | 24小时 | 否 | |
| 1级 | W1 | 24小时 | 同订购时长 | 是 | 已上线应用与订购时长一致，正式环境测试24小时有效 |
| 1级 | W2 | 5分钟 | 5分钟 | 否 | |
| 0级 | R1 | 30分钟 | 30分钟 | 否 | |
| 0级 | R2 | 0分钟 | 0分钟 | 否 | |
| 0级 | W1 | 30分钟 | 30分钟 | 否 | |
| 0级 | W2 | 0分钟 | 0分钟 | 否 |
示例代码
一、获取access_token示例
示例代码均基于sdk实现，sdk下载及使用参考 说明。
1、JAVA 示例
import java.io.IOException; import java.util.HashMap; import java.util.Map; import com.taobao.api.internal.util.WebUtils; //引用top sdk public class open_oauth { public static void main(String[] args) { String url="https://oauth.taobao.com/token"; Map props=new HashMap(); props.put("grant_type","authorization_code"); /*测试时，需把test参数换成自己应用对应的值*/ props.put("code","test"); props.put("client_id","test"); props.put("client_secret","test"); props.put("redirect_uri","http://www.test.com"); props.put("view","web"); String s=""; try{s=WebUtils.doPost(url, props, 30000, 30000); System.out.println(s); }catch(IOException e){ e.printStackTrace();} } }
2、PHP 示例
'authorization_code', 'client_id'=>'test', 'client_secret'=>'test', 'code'=>'test', 'redirect_uri'=>'http://www.test.com'); $post_data = ''; foreach($postfields as $key=>$value){ $post_data .="$key=".urlencode($value)."&";} $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0); //指定post数据 curl_setopt($ch, CURLOPT_POST, true); //添加变量 curl_setopt($ch, CURLOPT_POSTFIELDS, substr($post_data,0,-1)); $output = curl_exec($ch); $httpStatusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); echo $httpStatusCode; curl_close($ch); var_dump($output); ?>
3、.NET 示例
namespace Oauth2._0 { class Program { static void Main(string[] args) { WebUtils webUtils = new WebUtils(); IDictionary pout = new Dictionary(); pout.Add("grant_type", "authorization_code"); pout.Add("client_id", "test"); pout.Add("client_secret", "test"); pout.Add("code", "test"); pout.Add("redirect_uri", "http://www.test.com"); string output = webUtils.DoPost("https://oauth.taobao.com/token", pout); Console.Write(output); Console.ReadLine(); } } }
二、refresh_token刷新示例
以下为基于sdk的java示例，其它语言可参考token获取方法，是类似的,同时测试时，需把test参数换成自己应用实际对应的值。
import java.io.IOException; import java.util.HashMap; import java.util.Map; import com.taobao.api.internal.util.WebUtils; public class test_refresh { public static void main(String[] args) { String url="https://oauth.taobao.com/token"; Map props=new HashMap(); props.put("grant_type","refresh_token"); props.put("refresh_token","test"); props.put("client_id","test"); props.put("client_secret","test"); String s=""; try{s=WebUtils.doPost(url, props, 30000, 30000); System.out.println(s); }catch(IOException e){ e.printStackTrace(); } }
以上把responseJson 转化为对象，或者直接从里面提取access_token字段以及新的刷新令牌
refresh_token返回结果内容示例
|
{
"w2_expires_in": 0, "taobao_user_id": "263685215", "taobao_user_nick": "%E5%95%86%E5%AE%B6%E6%B5%8B%E8%AF%95%E5%B8%90%E5%8F%B752", "w1_expires_in": 1800, "re_expires_in": 0, "r2_expires_in": 0, "expires_in": 86400, "token_type": "Bearer", "refresh_token": "6200e1909ca29b04685c49d67f5ZZ3675347c0c6d5abccd263685215", "access_token": "6200819d9366af1383023a19907ZZf9048e4c14fd56333b263685215", "r1_expires_in": 1800 } |
常见问题
1、授权获取token时，appkey是已传入，仍报：client_id is empty 错误？
授权另一关键参数client_secret错误，会导报该错误，重点检查
2、是否一定需要沙箱先进行授权测试？
并不做这样要求，可以是“先沙箱测试授权，再正式环境”的方式；也可以直接“正式环境测试授权”的方式
3、授权相关常用文档有那些？
- 多店铺管理：查看
- 快速授权工具：查看
- 提高安全等级办法：查看
- 安全等级详细说明：查看
4、授权更多问题及错误码参考：查看
FAQ
- 关于此文档暂时还没有FAQ