• 如果您的应用和当当对接后,需要获取一些与用户紧密相关的信息(如用户偏好、用户订单、配送信息等),为保证用户数据的安全性与隐私性,您的应用需要取得用户的同意,即引导用户去授权。在这种情况下,您的应用需要使用“用户使用当帐号登录并授权”流程。

    当当采用国际通用的OAuth2.0协议,作为用户身份验证与授权协议。支持对网站、手机客户端、桌面客户端等不同类型的应用的授权。若要了解更多关于 OAuth2.0 的技术说明文档,可参看官方网站(http://oauth.net/2/) 。目前当当OAuth2.0服务支持采用以下3种获取Access Token(授权令牌)的方式:

    Server-side flow:此流程要求ISV应用有Web Server应用,能够保存应用本身的密钥以及状态,可以通过http直接访问当当的授权服务器。

    Client-side flow:此流程适用于没有独立服务器的应用,但是能够借助浏览器或者JS脚本访问授权服务器。

    Refreshing an Access Token:用户如果在获取访问令牌时,同时获取到了刷新令牌,当访问令牌过期时,用户可以用刷新令牌刷新,从而延长访问令牌的时间。


  • 1. 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)在不可预知错误的情况下,返回到默认错误页面。

    2. scope定义规则

    scope指的是应用发起请求时,所请求的API调用权限范围。

    为空表示所有权限。

    3. View参数

    可选值:web

    Web对应普通的PC端(当当logo)浏览器页面样式。

    4.Access Token

    Access Token即用户授权后颁发的session key

  • 此流程需要您有自己的web服务器,能够保存应用本身的密钥以及状态,可以通过http直接访问当当的授权服务器。

    授权过程分为两个步骤:

    (1) 通过用户授权获取授权码Code; (获取授权码 :http://oauth.dangdang.com/authorize)

    (2) 用上一步获取的Code和应用密钥(AppSecret)通过Http Post方式换取Token。(获取访问令牌: http://oauth.dangdang.com/token)

    1. 参数说明

    1.1 获取授权码参数

    参数名字 

    参数选项

    参数值

    参数释义

     appId

     必选


     应用ID

     responseType

     必选

     code

     响应类型

     redirectUrl

     必选



     state

     可选


     维持应用的状态,传入值与返回值保持一致

     view

     可选

     默认为web


     

    1.2 返回值说明

    参数名字 参数选项 示例 参数释义

     code

     正常结果

     4A868CF11F142DC7663F90DBF9C37077

     授权码

     error

     异常时返回


     错误码

     error_description

     异常时返回


     错误描述

     

    1.3 获取访问令牌参数

    参数名字 参数选项 参数值 参数释义

     appId

     必选


     应用ID

     grantType

     必选

     code

     换取方式

     code

     必选


     授权码

     appSecret

     必选


     应用密钥

    refreshToken

     可选


     刷新令牌码

     redirectUrl

     必选



     view

     可选

     默认为web


     state

     可选


     维持应用的状态,传入值与返回值保持一致


    1.4  获取访问令牌的返回值以redirect_uri中的参数形式返回

    Key  选项 示例 说明

     accessToken

     必选

     4A868CF11F142DC7663F90

     访问令牌

     expires_in

     必选

     yyyy-MM-dd hh:mm:ss

     令牌到期时间

     refresh_token

     必选

     4A868CF11F142DC7663F90

     刷新令牌

     re_expires_in

     必选

     

     刷新令牌过期时间

     re_expires_time

     必选

     

     刷新令牌到期时间

     shop_id

     必选

     

     商店ID

     shop_name

     必选

     

     商店名称

    edition_id

     必选

     

    版本ID

     edition_name

     必选

     

     版本名称

    edition_end_date

     必选

    yyyy-MM-dd hh:mm:ss 

    版本服务到期时间

    edition_status

     必选

     

     版本状态:1是试用,2是购买

     sign

     必选

     

    shop_idapp_idedition_idedition_end_date经过加密生成的签名

    2. 应用示例

    2.1 请求授权用户登录

    http://oauth.dangdang.com/authorize?appId=123&redirectUrl=http://www.clientserver.com&responseType=code&state=yourstate&view=web

     

    2.2 请求授权用户授权(用户登录后)

    出现授权页面后,用户可以选择“授权”。

    若用户选择“授权”,则页面跳转至应用的回调地址,同时返回授权码code以及state参数。

    返回URL如下图所示:

    2.3获取访问令牌

    http://oauth.dangdang.com/token?appId=123&shopId=121&code=53226E0D5C4FFAA2E353B41824FA5307&appSecret=

    5FDD35D3A94D73514CD6F1A5B58AED53&redirectUrl=http://www.clientserver.com/process_code.do&grantType=code&view=web&state=yourstate

    然后把responseJson 转化为对象,或者直接从里面提取:accessToken字段。

    返回结果内容示例:

    {

    "shop_id":"121",

    "accessToken":"0A8A014439F745224352C0D44B4AD8EC",

    "re_expires_time":"2013-08-26 17:46:49",

    "re_expires_in":"5183998",

    "state":"yourstate",

    "expires_in":"2013-07-27 18:07:52",

    "refresh_token":"89C7AB20DF3EACFC06446AF9732907B6",

    "view":web,

    "shop_name":"北京阳光智达数码专营店",

    "edition_id":"1001",

    "edition_name":"基础服务版",

    "edition_end_date":"2013-07-26 17:30:29",

    "edition_status":"2",

    "sign":"DF318625F4CBB6696180008E2F7E41E4"

    }

  • 适合ISV应用没有独立的web Server.但是能够借助浏览器或者JS脚本访问授权服务器。

    获取授权码:http://oauth.dangdang.com/authorize

    1. 参数说明

    1.1 获取授权码参数


    参数名字 参数选项 参数值 参数释义

     appId

     必选

     

     应用ID

     responseType

     必选

     token|persistentToken

     响应类型

     redirectUrl

     必选

     

     

     state

     可选

     

     维持应用的状态,传入值与返回值保持一致

     view

     可选

     默认为web

     

     appId

     必选

     

     

    1.2 返回值说明


    Key 选项 示例 说明

     accessToken

     必选

     4A868CF11F142DC7663F90

     访问令牌

     expires_in

     必选

     yyyy-MM-dd hh:mm:ss

     令牌到期时间

     refresh_token

     必选

     4A868CF11F142DC7663F90

     刷新令牌

     re_expires_in

     必选

     

     刷新令牌过期时间

     re_expires_time

     必选

     

     刷新令牌到期时间

     shop_id

     必选

     

     商店ID

     shop_name

     必选

     

     商店名称

    edition_id

     必选

     

    版本ID

     edition_name

     必选

     

     版本名称

    edition_end_date

     必选

    yyyy-MM-dd hh:mm:ss 

    版本服务到期时间

    edition_status

     必选

     

     版本状态:1是试用,2是购买

     sign

     必选

     

    shop_idapp_idedition_idedition_end_date经过加密生成的签名

    2. 应用示例

    2.1 请求授权用户登录

    http://oauth.dangdang.com/authorize?appId=123&redirectUrl=http://www.clientserver.com/process_token.do&responseType=token&state=yourstate

    2.2 请求授权用户授权(用户登录后)

    2.3获取访问令牌

    对于传入了redirect_uri的,回调到redirect_uri上面,对于没有传入redirect_uri,回调到当当默认页面。

    解析当当默认页面信息获取访问令牌

    2.4 获取短token和长token

    短token:当使用上面方法获取token时,我们发现accessToken的过期时间固定为30天,refresh_token固定为60天。这种token为称为短token。短token不能了解用户购买的应用是否快过期,需要调用openapi接口查询用户订购应用的信息来延长token使用期限。

    长token:当在上面方法responseType的值改为persistentToken时,可以得到与用户订购此应用结束时间一样长的过期时间的accessToken,这种token更方便应用的一次授权长期使用的特征。注:即便获取长token应用依然要判断accessToken是否可用或过期,因为用户可以在后台界面手动关闭对应用的授权或取消订购关系。

     

  • 通过前三种流程,获取了Access token以及Refresh token(对于具有“获取Refresh token权限”的应用),但是一般来讲,access token都有一定的时效性,在刷新有效时长内必须通过Refresh token 来延迟Access token的时长。

    请求的流程有:

    http://oauth.dangdang.com/token

    通过http post请求发送刷新。

    1. 参数说明


    参数名字  参数选项 参数值 参数说明

     appId

     必选

     

     应用ID

     grantType

     必选

     token

     换取方式

     code

     可选

     

     授权码

     appSecret

     可选

     

     应用密钥

     refreshToken

     必选

     

     刷新令牌码

     redirectUrl

     可选

     

     

     view

     可选

     

     

     state

     可选

     

     维持应用的状态,传入值与返回值保持一致

    2. 应用示例

    http://oauth.dangdang.com/token?appId=123&refreshToken=89C7AB20DF3EACFC06446AF9732907B6&appSecret=5FDD35D3A94D73514CD6F1A5B58AED53&redirectUrl=http://www.clientserver.com&grantType=token&view=web&state=1212

    然后把responseJson 转化为对象,或者直接从里面提取:accessToken字段。

    返回结果内容示例:

    {

    "shop_id":"121",

    "accessToken":"0A8A014439F745224352C0D44B4AD8EC",

    "re_expires_time":"2013-08-26 17:46:49",

    "re_expires_in":"5183998",

    "state":"1212",

    "expires_in":"2013-07-27 19:46:09",

    "refresh_token":"89C7AB20DF3EACFC06446AF9732907B6",

    "view":"web",

    "shop_name":"北京阳光智达数码专营店",

    "edition_id":"1001",

    "edition_name":"基础服务版",

    "edition_end_date":"2013-07-26 17:30:29",

    "edition_status":"2",

    "sign":"DF318625F4CBB6696180008E2F7E41E4"

    }

     

  • 用户授权成功后,跳到回调地址,并携带shop_id,app_id,edition_id,edition_end_date,sign等参数信息,其中sign为生成的签名。签名生成规则如下:

    取参数:shop_id,app_id,edition_id,edition_end_date,按此顺序拼接参数名+参数值:shop_idXXX app_id XXX edition_id XXX edition_end_date XXX。

    注意:其中每个参数的值需要做UTF-8编码;如果回调地址无某一参数,则此参数不参与拼接;如果回调地址中某一参数值为空,则拿空字符串作为此参数值来拼接。

    在上述拼接后得到的字符串两端,加上app_secret,得到最后的字符串后做一次MD5加密并专为大写,最后得到的即为签名sign。

    举例:

    App Secret=5FDD35D3A94D73514CD6F1A5B58AED53

    shop_id=0001

    app_id=21000000515

    edition_id=2000

    edition_end_date=2014-04-28+16%3A38%3A17

     

    参数名和参数值链接后,得到拼装字符串:
    5FDD35D3A94D73514CD6F1A5B58AED53shop_id0001app_id21000000515edition_id2000edition_end_date2014-04-28+16%3A38%3A175FDD35D3A94D73514CD6F1A5B58AED53

     

    32位MD5大写后得到签名:

    CCA90CC052432EDE4422498D14DAAA10

  • JAVA版:sdk下载


  • 错误信息 错误原因

     appId can not be empty

     appId不能为空

     redirectUrl can not be empty

     redirectUrl不能为空

     responseType can not be empty

     responseType不能为空

     appSecret can not be empty

     appSecret不能为空

     code can not be empty

     code不能为空

     grantType can not be empty

     grantType不能为空

     refreshToken can not be empty

     refreshToken不能为空

     OAUTH SERVER ERROR:xxxxx

     系统内部错误,请重试