当开放平台的应用需要获取商家或者用户数据(商品、订单信息等),需要引导用户先使用淘宝帐号登录并授权您的应用,用户授权成功平台会返回用户授权码 Sessionkey(即access_token),之后调用接口时传入对应用户的授权码就可以获取到该用户的数据。
1)对于开发阶段sessionkey的快速获取,可以使用官方工具获取sessionkey,
点击使用
;通过授权工具重新授权会刷新授权有效时间。
2)授权以后的sessionkey是有有效时间的,可以通过
授权Sessionkey解析
查询该次授权的有效时间,更多授权工具可以使用
授权常用工具
。
3)文档描述的用户授权操作仅适用于web应用授权使用,如果是手机淘宝/天猫客户端小程序开发,请参考《
授权场景
》。
4) sessionkey是根据应用appkey与授权账号生成的,使用哪个商家的淘宝账号授权,就仅能获取该商家的数据。
以下是关于授权的具体技术实现方案,开发者可以根据需要选择合适的授权方式。
二、web网站授权模式
此流程需要您有自己的web服务器,能够保存应用本身的密钥以及状态,可以通过https直接访问淘宝的授权服务器。适用于服务多商家或多用户频繁使用软件的场景。
授权过程分为两个步骤:
1)获取授权码:
通过用户授权获取授权码code。
正式环境:拼接以
https://oauth.taobao.com/authorize
开头的url。
2)获取访问令牌:
用上一步获取的 code 和应用密钥(AppSecret)通过POST方式换取accesstoken(即sessionkey)。
正式环境:拼接以
https://oauth.taobao.com/token
开头的url。
第三方应用授权的流程如下所示:
第一步:创建应用
要在您的应用中使用淘宝开放产品的接口能力,您需要先去淘宝开放平台(
https://open.taobao.com/
),创建登记您的应用,这里不再详细展开介绍,请参考《
新手指南
》。
第二步:拼接授权URL
拼接规则示例:
https://oauth.taobao.com/authorize?response_type=code&client_id=11111111&redirect_uri=http://www.taobao.com&state=1212&view=web
示例中的 client_id 和 redirect_uri 需要替换成您创建应用的实际数据。
client_id :
传入appkey,查找路径:【
控制台
】-【开发】-【我的应用】-【应用管理】-【概览】-【AppKey】,AppSecret 也在此处;
redirect_uri :
传入回调地址, 查找路径:【
控制台
】-【开发】-【我的应用】-【应用管理】-【应用设置】-【基本信息】-【回调URL】。(
仅适合非小程序式应用,即一站式电商后台
)
填写应用注册时回调地址域名
redirect_uri 指的是应用发起请求时,所传的回调地址参数,在用户授权后应用会跳转至redirect_uri。要求与应用注册时填写的回调地址域名一致或顶级域名一致 。
state
可自定义
,如1212等
维持应用的状态,传入值与返回值保持一致。
可选web / tmall / wap其中一种,
默认为web
Web 对应PC端(淘宝logo)浏览器页面样式;Tmall 对应天猫的浏览器页面样式;Wap 对应无线端的浏览器页面样式。
force_auth
true,如force_auth=true
在授权url中加 force_auth=true,不管授权是否有效都会弹授权页面,用户登陆授权以后有效时间会刷新。
from_site
fuwu,如from_site=fuwu
在授权url加from_site=fuwu,用户已登录且授权有效情况下会直接跳转回调,不会弹授权页面,授权时间不刷新。
第三步:引导用户登录授权
引导用户通过浏览器访问以上授权url,将弹出如下登录页面。用户输入淘宝帐号、密码,点“授权并登录”按钮,即可进入授权页面;若已是登录状态,点“授权并登录'按钮,即可登录授权页面。
此步骤,用哪个商家的淘宝账号登录授权,那获取的 sessionkey只能用来获取该商家的数据,不能获取其他商家数据。
对于品牌旗下多个淘宝店铺场景,可以参考
多店铺管理
场景, 每个店铺账号也必须分别进行登录授权,获取自己店铺的sessionkey。
第五步:换取access_token
方式1 调用API接口获取(推荐)
通过
taobao.top.auth.token.create
API接口获取 access_token(授权令牌).
授权有效期通过 expires_in 返回,请自行保存该数据,授权到期前,重新授权获取新的sessionkey
,避免使用过期的sessionkey调用接口导致isv报错。(详细介绍见下文名词解释中“授权时长”) ,也可以通过
授权session解析工具
,查询sessionkey有效期和授权用户信息,提前判断。
API调用服务请参考《
API调用方法详解
》,返回参数结果示例如下。
换取access_token
返回参数
说明:
(以下参数,调用接口
taobao.top.auth.token.create
时会返回,
请自行保存数据
,避免使用过期的token导致报错)
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
taobao_open_uid
string
SDJFKLSJFlJSDKF
淘宝账号对应openUid加密
sub_taobao_user_id
string
2343535
淘宝子账号对应id
sub_taobao_user_nick
string
测试账号test:123
淘宝子账号
方式2 拼装服务端请求。
如果你对 linux 比较熟悉,可以利用 curl 命令体验一下如何获取访问令牌。注意替换一下 "code="后面的授权码,其他参数也根据实际情况进行替换。
curl -i -d
"code=OxlukWofLrB1Db1M6aJGF8x2332458&grant_type=authorization_code&client_id=11111111&client_secret=69a1a2a3a469a1469a14a9bf269a14&redirect_uri=http://www.oauth.net/2/"https://oauth.taobao.com/token
填写应用注册时回调地址域名。redirect_uri指的是应用发起请求时,所传的回调地址参数,在用户授权后应用会跳转至redirect_uri。要求与应用注册时填写的回调地址域名一致或顶级域名一致 。
state
可自定义,如1212等;维持应用的状态,传入值与返回值保持一致。
可选web、tmall或wap其中一种,Web对应PC端(淘宝logo)浏览器页面样式;Tmall对应天猫的浏览器页面样式;Wap对应无线端的浏览器页面样式。
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);
>
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();}
} }
C#
示例:
string url = "https://oauth.taobao.com/token";
Dictionary<string, string> props = new Dictionary<string, string>();
props.Add("grant_type", "authorization_code");
props.Add("code","code");
props.Add("client_id","test");
props.Add("client_secret", "test");
props.Add("redirect_uri", "test");
props.Add("view", "web");
string s = "";
try
{
WebUtils webUtils = new WebUtils();
s = webUtils.DoPost(url, props, 30000, 30000);
}
catch (IOException e)
{
{
"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
}
三、客户端授权模式
客户端应用授权方式,适合ISV应用没有独立的web Server,需要借助浏览器或者JS脚本访问授权服务器,或者用户手动复制页面上的sessionkey输入到客户端。一般适用于自研应用或者低频使用的场景。
第三方应用授权的流程如下所示。
第一步:创建应用
同上第一步,详情参考上文。
第二步:拼接授权url
获取授权码: 拼接以
https://oauth.taobao.com/authorize
开头的url 。
拼接规则样例:
https://oauth.taobao.com/authorize?response_type=token&client_id=11111111&state=1212&view=web
相关参数位置及说明,同上第二步。
第三步:引导用户登录授权
这一步同上授权方式,引导用户访问授权URL进行授权,如下。
第四步:获取access_token
此处上图页面点授权后,
TO
P会直接将access_token 返回到淘宝默认页面(和 Server-side flow 先返回code 再换access_token方式不同)
需要用户手动复制sessionkey,或者使用JS脚本(if(window.location.hash!=""){alert(window.location.hash)})可以获取回调页面#后面的字段,从而获取到授权码。返回参数示例如下图。
注意:
此处参数返回除 top_sign 外,同Server-side flow授权返回参数相同,这里不再详细描述,具体可参考 Server-side flow 里面的说明。
返回参数中的top_sign 是系统生成签名参数,使用 Client-side flow 方式授权需要对该参数进行一致性验证。
第五步:验证授权签名
可选,即验证返回参数和 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 一致。
四、刷新授权
目前只有
订购类服务商应用可以刷新授权时间,
其他的固定授权时长的应用类型(如,
商家后台系统和新业务这类自研型应用无法使用
),必须重新登陆授权生成新sessionkey延长授权
时间,非订购类应用不支持刷新授权。
通过授权获取的refresh_token(前置条件:re_expires_in>0),可用来
刷新access token 的 r2 时长
。由于r1 或w1 通常同订购时长一致,一般不需刷新,
w2必须通过重新授权给予延长
,故 refresh_token 一般仅用于r2 有效时长的延长。
查看API对应的安全等级,请点击
《API安全等级》
。
通过
taobao.top.auth.token.refresh
API接口刷新token,每次
刷新后原来refresh_token作废
,都要更新成最新返回的refresh_token用于下次刷新。(api服务参考《
API调用方法详解
》)
以下为基于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();
}
}
{
"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. Access Token / Session Key
AccessToken即用户授权后颁发的SessionKey,也称为数据加密密钥或者工作密钥,当您调用淘宝开放平台涉及用户隐私数据的API接口时,需要传递TOP颁发给应用的授权信息(session_key参数),才能成功调用。
例如,调用
taobao.user.buyer.get
API获取买家信息,要求ISV应用必须先得到商家用户授权,获取相关session_key,传递相关参数,才能查询到买家信息。如下图所示。
2. 安全等级
为了更加灵活地对淘宝开放平台开放的数据进行安全管控, 降低用户数据泄露或者被恶意修改的风险。淘宝开放平台对API或者API字段打了R1,R2,W1,W2四类安全级别的标记,和对开发者的应用打了0,1,2,3 四种安全级别的标记。
与R1,R2,W1,W2对应的是在session key(access token)颁发时增加了4个过期时间:r1_expires_in、r2_expires_in、w1_expires_in、w2_expires_in。
这4个值分别用来表示此session key调用各级别API或字段的有效期。
受安全等级限制的应用有:在线订购应用、第三方IT工具、服务商后台系统、店铺模块后台这4类应用;
商
家后台系统和新业务这类卖家自用型应用暂不受影响
。
第三方IT工具包括但不限于以下发布到服务市场应用标签
(订单付费,互动应用,电商财务,图片/视频工具,快递运输应用,行业/店铺分析,商品管理,阿里妈妈营销工具,客服应用,促销管理,千牛插件,客户关系管理,ERP/进销存软件,订单管理,DMP人群营销,协同办公)
3. 授权时长
授权获得的access_token有效时长(expires_in )和标签类型(如IT工具、商家后台系统等)、状态(如正式环境、上线等)有关。
1)实际api调用时,对应用授权时长做了更精确的控制,具体可参考(
API安全等级
);
2)像“
第三方IT工具
” 类应用开发上线后都是发布在
服务市场
上,卖家需要订购使用,
相应授权时长会和订购时长相同
,如购买1个月,则取得的access_token有效时长1个月。
例如一个安全等级为2级的应用,在用户授权后颁发一个session key(access token),同时会返回4个过期时间:r1_expires_in=2160000(单位秒,下同)、r2_expires_in=259200、w1_expires_in=2160000、w2_expires_in=1800。
这些授权时长的含义如下:
(1)session key颁发后1800秒内,APP可以使用这个session key调用w2级别的API或字段。另外3个过期时间含义相同。
(2)session key颁发后超过1800秒,APP不可以再使用这个session key调用w2级别的API或字段。另外3个过期时间含义相同。
(3)对于本例来说如果R2级别的授权过期了,可以使用
refresh token
刷新一下R2的授权时长(
仅
限第三方订购类应用
)。刷新后使用新返回的sessionkey(access token)又可以重新调用R2级别的API或字段。
(4)对于本例来说如果w2级别的授权过期了,如上表格所示
w
2级别的授权是不能刷新的
。所以APP需要引导用户到授权页面重新授权 。
4. 应用授权个数
在【开发者控制台后台-开发-我的应用-应用管理-应用设置-授权管理】 界面查看,一般非第三方IT工具应用都无法选择 “所有人都可以使用”。
1)商家后台系统默认授权个数为1个,如果商家有多个店铺需要绑定,可以进行
多店铺管理
,进行授权报备;
2)注:第三方IT工具包括但不限于以下发布到服务市场应用标签(订单付费,互动应用,电商财务,图片/视频工具,快递运输应用,行业/店铺分析,商品管理,阿里妈妈营销工具,客服应用,促销管理,千牛插件,客户关系管理,ERP/进销存软件,订单管理,DMP人群营销,协同办公)
5. redirect_uri及callback定义规则
redirect_uri指的是应用发起请求时,所传的回调地址参数,在用户授权后应用会跳转至redirect_uri。
callback指的是应用注册时填写的回调地址链接,或者网站接入时所验证的域名地址。
相关的规则是:
1)Server-side flow,redirect_uri是
必选
参数,并且
要求
redirect_uri与callback的。
2)Client-side flow,redirect_uri是
可选
参数,如果传了redirect_uri,则相应的中间参数会返回到redirect_uri,并且要求redirect_ur与callback的顶级域名一致,如果没有传redirect_uri,则不做校验,返回相应的中间参数到淘宝默认授权返回页面。
3)在不可预知错误的情况下,返回到默认错误页面。
六、错误码排查
unsupported response type,the response type must code or token
response type的值必须为code或者token
redirect_uri is invalidate
redirect_uri校验失败,请检查你在开发者中心注册的回调地址和redirect_uri是否一致
the grant type unsupported
grant type值无效
authorize reject
用户拒绝授权
authorize code expire
authorize code失效,请重新授权
authorize code xxxx invalidate,please authorize again.
authorize code失效,请重新授权
client_secret is invalidate
app secret校验失败
xss chars included in params, such as <, >, ', "
请求参数中带有以下字符:<, >, ', "
The Application already Bind with user ids:xxx
APP已经绑定了用户xxx。请到开发者中心“授权管理”页面设置绑定的用户nick
Can not find the client_id:xxxxx
client_id(即appkey)不存在
Application need publish
只有状态为“正式环境测试”和“上线运行中”的应用才允许授权
Application xxx need purchase
必须先订购才能使用
app call back is invalidate
应用的回调地址不合法
application callback can not match the redirect_uri
redirect_uri和事先配置的回调地址不匹配
only support http or https
回调URL只支持https或http协议
application in black list,access forbidden.
app存在黑名单中
application session type must be common
session key类型不正确(只支持现有的常规sessionkey和订购类型sessionkey)
The application don't need session
此应用不需要sessionkey,不用刷新sessionkey
session key num is larger than xx
有效sessionkey个数超过上限
userid is invalidate
userId 不存在
login failure
用户登录失败
login sign failure
无线登录签名校验失败
taobao staff can't accredit
淘宝小二不允许访问
subuser can't access
应用不支持子账号访问
parent account forbid this sub account to access app.
父账号未授权此子账号访问应用
parent account forbidden
父账号未授权或授权已过期
refresh token is empty
refresh token为空
refresh token is error:xxxx
refresh token内容有误,解析失败
refresh token is invalid
refresh token已经失效
refresh times limit exceed
刷新次数超过上限,一个sessionkey一天最多可刷新60次
session expire
当前会话已经过期,可能用户浏览器暂停太久已经超时
OAUTH SERVER ERROR:xxxxx
系统内部错误,请重试
Iossdk params is lack
缺少ios sdk协议参数
iossdk track_id is invalid
ios sdk协议参数track id校验失败。建议核对一下appsecret
iossdk params check failed
ios sdk协议参数校验失败
七、常见问题
1.Q:授权获取token时,appkey已传入,仍报:client_id is empty 错误?
A:授权另一关键参数client_secret错误,会导报该错误,请重点检查。
2.Q:淘宝子账号授权报错问题?
A:淘宝子账号授权应用,必须先用店铺主账号授权,主账号再给子账号开通应用使用权限(参考《
子账号授权流程介绍
》),然后才可以进行子账号授权。
可能还会出现报错:parent account forbid this sub account to access app , 这个是主账号没有给相应子账号开通 应用使用的权限,需要在子账号管理后台给相应账号开通权限,参考《
子账号授权流程介绍
》。
3.Q:C2B定制自研应用如何授权?
A:获取session_key 需要先通过
my.authorize
授权,授权后使用云服务获取,云开发通过云函数
context
参数获取(context.accessToken), 云应用通过
http param
获取access_token。
4.Q:每次同步淘宝用户数据都要网页进行用户授权,怎么实现自动同步?
A: 不同的接口授权有效时长不一样,过期授权无法同步信息。如果同步淘宝用户数据时要求重新授权,说明原授权已过期,必须重新授权。可以考虑提升ISV应用等级,延长授权时效,减少反复授权,参考《
应用授权规则
》。
5.Q:授权相关常用文档有那些?
A:
多店铺管理
、
快速授权工具
、
安全保障、安全等级介绍及安全等级提升方法
。
怎样在淘宝帐号里授权API转链