文档中心 > 基础技术

用户授权介绍

更新时间:2018/04/17 访问次数:3668474

登录授权

      如果您的应用和淘宝开放平台对接时需要获取用户隐私数据(如商品、订单等),为保证用户数据的安全与隐私,您的应用需要取得用户的授权,即获取访问用户数据的授权令牌 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
 沙箱环境: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

参数说明
名称 是否必选 参数值 参数释义
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服务地址参考//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)并访问即可,退出后跳转到淘宝首页 。

刷新授权

通过授权获取的refresh_token,可用来刷新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小时 同订购时长 申请参考这里
店铺模块前台 无session 无session 已停止接入
店铺模块后台 24小时 同订购时长 已停止接入
新业务 24小时 固定时长1个月 不开放
无线买家应用 24小时 24小时 已停止接入
xTao合作网站 24小时 24小时 已停止接入

二、安全等级说明

为了更加灵活的对淘宝开放平台开放的数据进行安全管控, 降低用户数据泄露或者被恶意修改的风险,推出了安全等级的概念。
淘宝开放平台对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服务地址参考//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、授权更多问题及错误码参考:查看

FAQ

怎样在淘宝帐号里授权API转链

返回
顶部