用户授权介绍

登录授权

如果您的应用和淘宝开放平台对接时需要获取用户隐私数据（如商品、订单等），为保证用户数据的安全与隐私，您的应用需要取得用户的授权，即获取访问用户数据的授权令牌 Access Token （也叫SessionKey）。这种情况下，您的应用需要引导用户完成使用淘宝帐号“登录授权”的流程。该流程采用国际通用的OAuth2.0标准协议作为用户身份验证与授权协议，支持网站、手机客户端、桌面客户端。

目前淘宝OAuth2.0服务支持采用两种方式获取Access Token（授权令牌），即 Server-side flow 和 Client-side flow ，详见如下说明。

特别注意

此文档描述的授权页面仅适用于PC端，如果您的页面是在手机淘宝/天猫客户端中被访问，请参考这里。如果您的页面是在H5手机浏览器中被访问，请参考这里。

如果是要快速生成一个授权sessionkey， 可以直接通过 授权工具 生成，登陆需要授权的账号，输入需要授权的appkey。

一、Server-side flow

此流程要求ISV应用有Web Server应用，能够保存应用本身的密钥以及状态，可以通过https直接访问淘宝的授权服务器。

1、请求入口地址

1）获取授权码（code）

正式环境：https://oauth.taobao.com/authorize

沙箱环境：http://oauth.daily.taobao.net/authorize

备注：访问沙箱环境需要安装chrome插件，查看安装步骤

2）获取访问令牌（access_token）

正式环境：https://oauth.taobao.com/token

沙箱环境：https://gw.api.tbsandbox.com/router/rest

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

参数说明

名称 是否必选 参数值 参数释义

client_id 必选 等同于appkey，创建应用时获得。

response_type 必选 code 授权类型 ，值为code。

redirect_uri 必选 可填写应用注册时回调地址域名。 redirect_uri指的是应用发起请求时，所传的回调地址参数，在用户授权后应用会跳转至redirect_uri。要求与应用注册时填写的回调地址域名一致或顶级域名一致 。

state 可选 可自定义，如1212等； 维持应用的状态，传入值与返回值保持一致。

view 可选 web,可选web、tmall或wap其中一种，默认为web。 Web对应PC端（淘宝logo）浏览器页面样式；Tmall对应天猫的浏览器页面样式；Wap对应无线端的浏览器页面样式。

2）引导用户登录授权

引导用户通过浏览器访问以上授权url，将弹出如下登录页面。用户输入账号、密码点“登录”按钮，即可进入授权页面。

授权

3）获取code

上图页面，若用户点“授权”按钮后，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

方式1（推荐）：

通过taobao.top.auth.token.create api接口获取access_token（授权令牌）。api服务地址参考http://open.taobao.com/docs/doc.htm?docType=1&articleId=101617&treeId=1

方式2：

利用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

换取access_token请求参数说明

名称 是否必选 参数值 参数释义

client_id 必选 等同于AppKey，创建应用时获得。

client_secret 必选 等同于AppSecret，创建应用时获得。

grant_type 必选 authorization_code 授权类型 ，值为authorization_code

code 必选 上一步获取code得到

redirect_uri 必选 可填写应用注册时回调地址域名。redirect_uri指的是应用发起请求时，所传的回调地址参数，在用户授权后应用会跳转至redirect_uri。要求与应用注册时填写的回调地址域名一致或顶级域名一致 。

state 可选 可自定义，如1212等；维持应用的状态，传入值与返回值保持一致。

view 可选 可选web、tmall或wap其中一种，Web对应PC端（淘宝logo）浏览器页面样式；Tmall对应天猫的浏览器页面样式；Wap对应无线端的浏览器页面样式。

换取access_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返回参数说明

Key 类型 示例 说明

access_token string 2YotnFZFEjr1zCsicMWpAA Access token

token_type string Bearer Access token的类型目前只支持bearer

expires_in number 10（表示10秒后过期） Access token过期时间

refresh_token string 2YotnFZFEjr1zCsicMWpAA Refresh token，可用来刷新access_token

re_expires_in number 10（表示10秒后过期） Refresh token过期时间

r1_expires_in number 10（表示10秒后过期） r1级别API或字段的访问过期时间；

r2_expires_in number 10（表示10秒后过期） r2级别API或字段的访问过期时间；

w1_expires_in number 10（表示10秒后过期） w1级别API或字段的访问过期时间；

w2_expires_in number 10（表示10秒后过期） w2级别API或字段的访问过期时间；

taobao_user_nick string 测试账号 淘宝账号

taobao_user_id string 706388888 淘宝帐号对应id

sub_taobao_user_id string 2343535 淘宝子账号对应id

sub_taobao_user_nick string 测试账号test:123 淘宝子账号

注意：应用回调地址需要在控制台中维护在应用基本信息中

二、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 授权方式流程图，以下按流程图逐步详细说明cs flow

1）拼接授权url

https://oauth.taobao.com/authorize?response_type=token&client_id=23075594&state=1212&view=web

参数说明

名称 是否必选 参数值 参数释义

client_id 必选 等同于appkey，创建应用时获得。

response_type 必选 token 授权类型 ，值为token。

state 可选 可自定义，如1212等； 维持应用的状态，传入值与返回值保持一致。

view 可选 web,可选web、tmall或wap其中一种，默认为web。 Web对应PC端（淘宝logo）浏览器页面样式；Tmall对应天猫的浏览器页面样式；Wap对应无线端的浏览器页面样式。

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）并访问即可，退出后跳转到淘宝首页 。

刷新授权

注意：目前只有订购类应用可以刷新授权时间， 其他的固定授权时长的应用类型，只能让用户重新登陆授权生成新sessionkey，延长授权时间。

通过授权获取的refresh_token（前置条件：re_expires_in>0），可用来刷新access token 的r2时长。

由于r1 或w1 通常同订购时长一致，一般不需刷新，w2必须通过重新授权给予延长，故refresh_token 一般仅用于r2 有效时长的延长。

操作方法类似获取access token ，仅请求参数有区别，说明如下：

换取access_token请求参数说明

名称 是否必选 参数值 参数释义

client_id 必选 等同于AppKey，创建应用时获得。

client_secret 必选 等同于AppSecret，创建应用时获得。

grant_type 必选 refresh_token 授权类型 ，值为refresh_token

state 可选 可自定义，如1212等；维持应用的状态，传入值与返回值保持一致。

view 可选 可选web、tmall或wap其中一种，Web对应PC端（淘宝logo）浏览器页面样式；Tmall对应天猫的浏览器页面样式；Wap对应无线端的浏览器页面样式。

相关说明

一、授权时长说明

授权获得的 access_token 有效时长（expires_in ）和标签类型（如IT工具、商家后台系统等）、状态（如正式环境、上线等）相关如下。

注：实际api 调用时，对应用授权时长做了更精确的控制，具体可参考（二、安全等级说明）；另像“第三方IT工具”类应用开发上线后都是发布在 fuwu.taobao.com上，卖家需要订购使用，相应授权时长会和订购时长相同，如购买1个月，则取得的access_token有效时长1个月。

标签名称 正式环境测试 上线运行中 备注

第三方IT工具 24小时 同订购时长 申请参考这里

商家后台系统 24小时 固定时长1年 申请参考这里

服务商后台系统 24小时 同订购时长 申请参考这里

新业务 24小时 固定时长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<String,String> props=new HashMap<String,String>();
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 示例

<?php /*测试时，需把test参数换成自己应用对应的值*/ $url = 'https://oauth.taobao.com/token'; $postfields= array('grant_type'=>'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<string, string> pout = new Dictionary<string, string>();
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刷新示例

方式1（推荐）：

通过taobao.top.auth.token.refresh api接口刷新token。每次刷新后原来refresh_token作废，都要更新成最新返回的refresh_token用于下次刷新。api服务地址参考http://open.taobao.com/docs/doc.htm?docType=1&articleId=101617&treeId=1

方式2：

以下为基于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<String,String> props=new HashMap<String,String>();
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、授权更多问题及错误码参考：查看