首页 > 开发指南 > 授权说明

授权说明

一、前言

如果您的应用已和京东JOS对接,需要获取一些与用户紧密相关的信息(如订单、商品、促销等),为保证数据的安全性和隐私性,需要取得用户的同意,引导用户授权。JOS采用国际通用的OAuth2.0标准协议,支持网站、桌面客户端、ERP系统。如果要了解更多关于OAuth2.0的技术说明,请参考官方网站  https://oauth.net/2/  。目前,JOS的OAuth2.0支持以下方式获取Access Token。


(1)Authorization Code 此流程要求ISV或商家(自主研发应用)有web服务器,能够保持应用本身的密钥以及状态,可以通过https直接访问京东的授权服务器。
(2)Native Application 此流程适合ISV或商家(自主研发应用)没有自己的web服务器,且应用为原生程序,即客户端应用(同时应用无法与浏览器交互,但是可以外调用浏览器)。
(3)Refresh token 通过前两种流程,获取了Access token以及Rrfresh token(刷新令牌),Access token都有一定的期限,通过服务市场授权应用,Access token期限以购买周期为准。当Access token过期时,用户可以到京东服务市场重新购买应用。


正式环境授权地址:https://oauth.jd.com/oauth/authorize? (需要拼接参数,无法直接访问)

注意:如授权商家修改主账号密码则授权码(Access token)随之失效,需重新授权。

授权有效期说明:如果应用appkey状态为“在线测试”,授权token有效期只有24小时,“上线运行”状态的应用授权token有效期为一年。另如果是通用应用,需要先发布到服务市场,审核通过后方可授权获取token。

二、Authorization Code

此流程要求ISV或商家(自主研发应用)有web服务器,能够保持应用本身的密钥以及状态,可以通过https直接访问京东的授权服务器。

1. 参数说明
获取授权码code的参数

参数名称参数选项 描述
response_type 必须 此流程下,该值固定为code
client_id 必须 即创建应用时的Appkey(从JOS控制台->管理应用中获取)
redirect_uri 必须 即应用的回调地址,必须与创建应用时所填回调页面url一致
state 可选 状态参数,由ISV自定义,颁发授权后会原封不动返回
scope 可选 权限参数,API组名串。多个组名时,用","分隔,目前支持参数值:read
view 可选

移动端授权,该值固定为wap;非移动端授权,无需传值


获取访问令牌Access token的参数

参数名称参数选项 描述
grant_type 必须 授权类型,此流程下,该值固定为authorization_code
code 必须 授权请求返回的授权码
redirect_uri 必须 应用的回调地址,必须与创建应用时所填回调页面url一致
client_id 必须 即创建应用时的Appkey(从JOS控制台->管理应用中获取)
client_secret 必须 即创建应用时的Appsecret(从JOS控制台->管理应用中获取)
state 可选 状态参数,由ISV自定义,颁发授权后会原封不动返回


2. 基本流程

2.1 引导使用应用的用户登录到如下地址获取code

http请求url如下:

https://oauth.jd.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&

redirect_uri=YOUR_REGISTERED_REDIRECT_URI&state=YOUR_CUSTOM_CODE

wap版,http请求需加参数view=wap。如下:

https://oauth.jd.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&

redirect_uri=YOUR_REGISTERED_REDIRECT_URI&state=YOUR_CUSTOM_CODE&view=wap


2.2 用户登录授权




2.3 获取授权码code

用户同意授权,页面跳转至应用的回调地址,同时返回授权码code以及state参数。


如果用户取消授权,则页面跳转至应用的回调地址,同时返回如下错误信息:error=access_denied



2.4 获取访问令牌access_token

用上一步获取的code码和注册应用时分配的AppSecret,通过Http Post方式换取Token(访问令牌,即Access token),JOS会以json文本的形式返回数据。

ISV可以参考如下代码获取AccessToken:

String url ="https://oauth.jd.com/oauth/token?grant_type=authorization_code&client_id="+appKey

+"&client_secret="+ appSecret

+"&scope=read&redirect_uri=https://"+ url

+"&code="+ code

+"&state=1234";

uri = new URL(url);

HttpURLConnection conn =(HttpURLConnection) uri.openConnection();

conn.setRequestProperty("Accept-Charset","utf-8");

conn.setRequestMethod("POST");

int code = conn.getResponseCode();

InputStream is =conn.getInputStream();

String jsonStr =inputStream2String(is);

StringaccessToken = this.getAccessToken(jsonStr);

最后生成的http请求url如下(code只允许使用一次,如获取token失败,请重新授权获取code,再换取access_token)

https://oauth.jd.com/oauth/token?grant_type=authorization_code&client_id=YOUR_CLIENT_ID&

redirect_uri=YOUR_REGISTERED_REDIRECT_URI&code=GET_CODE&state=YOUR_CUSTOM_CODE&client_secret= YOUR_APP_SECRET


从http返回结果中,得到AccessToken和Refresh_token。


注释:

uid:授权用户对应的京东ID

user_nick:授权用户对应的京东昵称

expires_in:失效时间(从当前时间算起,单位:秒)
time:授权的时间点(UNIX时间戳,单位:毫秒)
token_type:token类型(暂无意义)

三、Native Application


此流程适合ISV没有自己的web服务器,且应用为原生程序,即客户端应用(同时应用无法与浏览器交互,但是可以外调用浏览器)。


1. 参数说明

1.1 获取授权码参数

参数名字

参数选项

参数值

参数释义

client_id

必选

即创建应用时的Appkey(从JOS控制台->管理应用中获取)

response_type

必选

code

此流程下,该值固定为code

redirect_uri

必选

urn:ietf:wg:oauth:2.0:oob

此流程下,该值固定为urn:ietf:wg:oauth:2.0:oob

scope

可选

权限参数,API组名串。多个组名时,用","分隔,目前支持参数值:read

state

可选

状态参数,由ISV自定义,颁发授权后会原封不动返回

view

可选


移动端授权,取值为wap;非移动端授权,无需传值

2.应用示例

2.1 请求授权用户登录

http请求url如下:

https://oauth.jd.com/oauth/authorize?response_type=code&client_id=23234SDFSDGEW23234E&redirect_uri=urn:ietf:wg:oauth:2.0:oob&state=1212


2.2 请求授权用户授权




2.3 获取访问令牌即access token

回调到授权默认页面,同时access token显示在页面上。


四、Refresh token

通过Authorization Code授权流程,获取到Access token以及Refresh token。Access token有一定的时效,在Access token的有效内可以通过Refresh token来延长Access token的时效。

Native Application授权流程,无法获取Refresh token,如果超过授权时效,需要重新授权。


请求的地址:https://oauth.jd.com/oauth/token

请求的方式:http post


1. 参数说明


参数名字 参数选项 参数值 参数释义
client_id 必选
即创建应用时的Appkey(从JOS控制台->管理应用中获取)
client_secret 必选
即创建应用时的Appsecret(从JOS控制台->管理应用中获取)
grant_type 必选 refresh_token 授权类型,此流程下,该值固定为refresh_token
refresh_token 必选
即授权时获取的刷新令牌
scope 可选
权限参数,API组名串。多个组名时,用","分隔,目前支持参数值:read
state 可选
状态参数,由ISV自定义,颁发授权后会原封不动返回

2. 应用示例


把response json转化为对象,或者直接从里面提取新的access_token等字段。access_token会重置有效时间,refresh_token则不变。


http请求url如下:

https://oauth.jd.com/oauth/token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_ID&grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN


返回结果内容示例:




注释:

uid:授权用户对应的京东ID

user_nick:授权用户对应的京东昵称

expires_in:失效时间(从当前时间算起,单位:秒)

time:授权的时间点(UNIX时间戳,单位:毫秒)

token_type:token类型(暂无意义)

五、Oauth2.0错误码

客户端异常

101 : 没找到应用(确认应用是否已“上线运行”;确认应用类型是否为“通用应用”,“无线应用”、“网站应用”无法被授权)

用户登录时,用户异常如下:

201 : 您的IP服务受限,请联系客服解决
202 : 请输入用户名
203 : 用户名不存在
204 : 请输入密码
205 : 登录信息与密码不匹配
206 : 用户名与密码不匹配,还可尝试{0}次,如失败账户将被冻结2小时
207 : 登录失败超过6次,账户已被冻结2个小时
208 : 容器检查登录用户不在应授权用户中(个人账号不能给商家应用授权)
209 : 未知异常,请联系管理员
301 : 缺少responsetype参数 或者为空
302 : 缺少clientId 参数 或者为空
303 : 缺少redirectUri 参数 或者为空
304 : 防止session伪造(在授权过程中点击了回退按钮)
305 : 拼写的redirect_uri和注册应用的“回调页面URL”不一致

用户登录时,系统异常如下:


251 : 调用验证登录信息的接口失败
251 : 调用验证登录信息接口返回的json串格式错误,解析失败

其他异常

401 : 没有此流程的认证权限(应用使用了错误的授权方式进行授权)
402 : 错误的code(1、code码超时,code码时效为5分钟;2、测试环境与正式环境code码混用;3、自己编造的code码)
403 : url不匹配(请求url与开发者中心创建应用时填写的url不一致;2、没有填写url)
404 : 错误的请求(JOS授权安全机制限制:用户在授权页面输入账号密码出错后,重新在原页面输入账号密码均会报404。处理方法:请重新获取授权页面,或回退两次即可)
405 : "code":"405","error_description":"用户[xxx]无权给app[C05EBAAB019CC6E91D44D45834ER]授权"(请将报错信息,包含用户名及appkey发送至jos#jd.com申请绑定授权关系)

六、京东服务协议

尊敬的用户:


        您授权使用京东网会员账号登录第三方站点或软件,如果您无法认同如下内容的,请您停止进行授权。


1、您完成授权后,即视为您同意和授权第三方站点和软件使用京东网数据接口调用您京东网账号和与该账号关联的店铺或系统的相关信息数据,并接受本协议全部内容。


2、第三方站点和软件的质量和品质由第三方独立负责,京东仅提供登录接口,对第三方站点或软件的服务等不承担任何责任。如因第三方站点或软件存在漏洞、瑕疵、故障、病毒等原因造成您相关权益受损的,您可以请京东协调,但您不应就登录和使用第三方站点或软件的后果要求京东承担任何责任。


3、为了保障您的权益,京东将对第三方站点和软件进行定期检测和代码扫描,但您理解任何技术手段并非完全可靠。京东郑重提醒您启用杀毒和安全措施,以减轻病毒、恶意代码、漏洞等的不良影响。


4、网络欺诈往往会模仿、仿冒本登录页面的样式制作视觉感相似的页面引诱用户输入账号和密码等信息,京东提醒您防范网络风险,不要向非京东网的站点或任何人士透露京东网账号、密码等相关信息。


5、如您发现第三方站点或软件侵犯您的合法权益的,或您不幸遭遇网络欺诈的,请您及时联系并通知京东。