关注JEECG发展历程 关注最新动态和版本, 记录JEECG成长点滴 更新日志 - 技术支持 - 招聘英才

JEECG最新版本下载 JEECG智能开发平台 - 显著提高开发效率 常见问题 - 入门视频 - 参与开源团队

商务QQ: 69893005、3102411850 商务热线(5*8小时): 010-64808099 官方邮箱: jeecgos@163.com

查看: 8622|回复: 2

【JEECG技术文档】JEECG平台对外接口JWT应用文档V3.7.2

[复制链接]
发表于 2018-2-7 14:59:16 | 显示全部楼层 |阅读模式
一、 接口方式
    接口调用采用http协议,rest请求方式;

二、 接口安全
    接口安全采用Json web token (JWT)机制,基于token的鉴权机制.

1. 机制说明
    基于token的鉴权机制类似于http协议也是无状态的,它不需要在服务端去保留用户的认证信息或者会话信息。这就意味着基于token认证机制的应用不需要去考虑用户在哪一台服务器登录了,这就为应用的扩展提供了便利。

2. 基本流程
    流程上是这样的:
        (1) 用户使用用户名密码来请求服务器
        (2) 服务器进行验证用户的信息
        (3) 服务器通过验证发送给用户一个token
        (4) 客户端存储token,并在每次请求时附送上这个token值(存在head里的参数X-AUTH-TOKEN)
        (5) 服务端验证token值,并返回数据
7.png
3. 优点

  •   因为json的通用性,所以JWT是可以进行跨语言支持的,像JAVA,JavaScript,NodeJS,PHP等很多语言都可以使用。
  •   因为有了payload部分,所以JWT可以在自身存储一些其他业务逻辑所必要的非敏感信息。
  •   便于传输,jwt的构成非常简单,字节占用很小,所以它是非常便于传输的。
  •   它不需要在服务端保存会话信息, 所以它易于应用的扩展

4. 安全相关

  •   不应该在jwt的payload部分存放敏感信息,因为该部分是客户端可解密的部分。
  •   保护好secret私钥,该私钥非常重要。
  •   如果可以,请使用https协议

三、 缓存配置

    JWT 验证token采用redis进行缓存,
    redis配置文件:src/main/resources/redis.properties
    修改redis对应的IP和端口。

[java] view plain copy
  1. #redis  
  2. redis.host=124.206.91.99  
  3. redis.port=6379  
  4. redis.pass=  
  5. redis.adapter.maxIdle=100  
  6. redis.adapter.minIdle=10  
  7. redis.adapter.testOnBorrow=true  
  8. redis.adapter.testOnReturn=true  
  9. redis.adapter.testWhileIdle=true  
  10. redis.adapter.numTestsPerEvictionRun=10  
  11. redis.adapter.timeBetweenEvictionRunsMillis=60000  
复制代码
四、 接口说明

    注意:访问除【鉴权TOKEN接口】以外的接口时,都需要访问用户拥有对接口的访问权限,如无权限,将直接返回如下信息:
  1. {"message":"您没有该接口的权限!","data":null,"ok":false,"respCode":"-1"}
复制代码
1. 鉴权TOKEN接口

    ■描述
        根据用户名和密码获取TOKEN。
    ■访问地址
        http://域名/rest/tokens
    ■访问方式
        GET
    ■参数
参数名
数据类型
是否必须
示例值
默认值
描述
username
String
Y
“admin”

用户名
password
String
Y
“123456”

密码
    ■返回值
        成功时,直接返回token字符串。
        失败时,直接返回用户账号密码错误!
    ■校验规则
        无
    ■请求示例
        请求地址:http://域名/rest/tokens
  1. {  
  2.     "username":"admin",  
  3.     "password":"123456"  
  4. }  
复制代码
    ■返回示例
    1. 成功案例:
    2. eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI4YThhYjBiMjQ2ZGM4MTEyMDE0NmRjODE4MTk1MDA1MiIsInN1YiI6ImFkbWluIiwiaWF0IjoxNTExODU0NDE4fQ.tnILZEivS-6YOX9uqsnCHygh7-XrG_-Sj8vLslNGkdQ
    3. 失败案例:
    4. 用户账号密码错误!
    复制代码

2. 创建黑名单信息接口

    ■描述
        创建黑名单信息接口,黑名单为单表。
    ■访问地址
        http://域名/rest/tsBlackListController
    ■访问方式
        POST
    ■参数(详见excel)
参数名
数据类型
是否必须
示例值
默认值
描述
ip
String
Y
“192.168.1.1”


......


……省略信息其他字段……

    ■返回值
参数名
描述
respCode
返回码(见附录1接口返回信息列表)
respMsg
返回信息(见附录1接口返回信息列表)
data
返回结果(NULL)
ok
状态
   

   校验规则
        1. 接口中涉及日期时间的字段,要求格式化为字符串传递,日期格式为“YYYY-MM-dd”,时间格式为“YYYY-MM-dd HH:mm:ss”。
    ■请求示例
        请求地址:http://域名/rest/tsBlackListController
    参数如下:
     注意:创建企业无需传id,子表无需传id和企业id,这些都会在后台生成,必需要传入的是来源id和来源表。
  1. {  
  2.   "ip": "192.1.1.1",  
  3. ……(省略信息其他字段)  
  4. }
复制代码
    ■返回示例


成功案例:  {      "respCode":"0",      " respMsg":"成功"  }  失败案例:  {      "respCode":"-1",      "respMsg":"黑名单创建失败"  }  
3. 查询黑名单信息接口

    ■描述
        根据id查询或查询黑名单信息接口。
    ■访问地址
根据id查询
http://域名/rest/tsBlackListController/get/{id}
    ■访问方式
        GET
    ■参数
        无
    ■返回值
参数名
描述
respCode
返回码(见附录1接口返回信息列表)
respMsg
返回信息(见附录1接口返回信息列表)
data
返回结果(结构参照创建企业接口的参数,具体字段参照excel)
ok
状态

    ■请求示例
        请求地址:http://域名
  1. /rest/tsBlackListController/get/297e7ae15f7f7f7e015f7fb0f57e0040  
复制代码
    ■返回示例

  • 成功案例:  
    1.   
    2. {  
    3.   
    4.     "message": "成功",  
    5.   
    6.     "data": {  
    7.   
    8.         "id": "402881f15e751d2a015e75212c570005",  
    9.   
    10.         "createBy": "admin",  
    11.   
    12.         "updateBy": "",  
    13.   
    14.         "bpmStatus": "1",  
    15.   
    16.         "ip": "111.193.210.4",  
    17.   
    18.         "createName": "管理员",  
    19.   
    20.         "createDate": "2017-09-12 16:07:41",  
    21.   
    22.         "updateName": "",  
    23.   
    24.         "updateDate": null,  
    25.   
    26.         "sysOrgCode": "A03",  
    27.   
    28.         "sysCompanyCode": "A03"  
    29.   
    30.     },  
    31.   
    32.     "respCode": "0",  
    33.   
    34.     "ok": true  
    35.   
    36. }
    复制代码
  • 失败案例:  
    1. {"data":null,"respCode":"-1","respMsg":"根据所传id查询无结果"}  
    复制代码

4. 修改黑名单信息接口

    ■描述
        根据id修改
    ■访问地址
        http://域名/rest/tsBlackListController/update/{id}
    ■访问方式
        PUT
    ■参数
参数名
数据类型
是否必须
示例值
默认值
描述
id
String
Y
“402881f15f811877015f8124ca1c0002”


ip
String
Y
“192.168.1.1”





……省略信息其他字段……
    ■返回值
参数名
描述
respCode
返回码(见附录1接口返回信息列表)
respMsg
返回信息(见附录1接口返回信息列表)
data
返回结果(NULL)
ok
状态
    ■校验规则
        通过校验主表的字段:来源id和来源表验证数据唯一性。
    ■请求示例
       请求地址:http://域名/rest/tsBlackListController/update/402881f15f811877015f8124ca1c0002
       参数如下:
  1. {  
  2.   "id": "402881e75f94878e015f94896bb80002",  
  3.   "ip": "1.1.1.1"  
  4.   
  5. }
复制代码
    ■返回示例
  1. 成功案例:  
  2. {  
  3.     "respCode":"0",  
  4.     "respMsg":"成功"  
  5. }  
  6.   
  7. 失败案例:  
  8. {  
  9.     "respCode":"-1",  
  10.     "respMsg":"输入ID无效,重复输入"  
  11. }
复制代码
5. 删除黑名单接口

    ■描述
        根据id删除
    ■访问地址
        http://域名/rest/tsBlackListController/delete/{id}
    ■访问方式
        DELETE
    ■参数
       无
    ■返回值
参数名
描述
respCode
返回码(见附录1接口返回信息列表)
respMsg
返回信息(见附录1接口返回信息列表)
data
返回结果(NULL)
ok
状态
    ■校验规则
        无
    ■请求示例
        请求地址:http://域名/rest/tsBlackListController/delete/297e7ae15f7f7f7e015f7fb0f57e0040
    ■返回示例
  1. 成功案例:  
  2. {  
  3.     "respCode":"0",  
  4.     "respMsg":"成功"  
  5. }  
  6. 失败案例:  
  7. {  
  8.     "respCode":"-1",  
  9.     "respMsg":"输入ID无效,重复输入"  
  10. }
复制代码
五、 客户端测试代码

    代码示例

  • public static String getToken(String userName,String password){  
  •         String url = "http://localhost:8080/jeecg/rest/tokens?username="+userName+"&password="+password;  
  •         String token= JwtHttpUtil.httpRequest(url, "POST", null);  
  •         return token;  
  •     }  
  •         //获取黑名单列表  
  •     public static JSONObject getBlackList(String token){  
  •         String url = "http://localhost:8080/jeecg/rest/tsBlackListController";  
  •         JSONObject resp= JwtHttpUtil.httpRequest(url, "GET", null,token);  
  •         return resp;  
  •     }  
  •     //创建黑名单  
  •     public static JSONObject createBlackList(String token,String json){  
  •         String url = "http://localhost:8080/jeecg/rest/tsBlackListController";  
  •         JSONObject resp= JwtHttpUtil.httpRequest(url, "POST", json,token);  
  •         return resp;  
  •     }  
  •     //更新黑名单  
  •     public static JSONObject updateBlackList(String token,String json){  
  •         String url = "http://localhost:8080/jeecg/rest/tsBlackListController";  
  •         JSONObject resp= JwtHttpUtil.httpRequest(url, "PUT", json,token);  
  •         return resp;  
  •     }  
  •     //删除黑名单  
  •     public static JSONObject deleteBlackList(String token,String id){  
  •         String url = "http://localhost:8080/jeecg/rest/tsBlackListController/"+id;  
  •         JSONObject resp= JwtHttpUtil.httpRequest(url, "DELETE", null,token);  
  •         return resp;  
  •     }  
  •     //查询黑名单  
  •     public static JSONObject getBlackList(String token,String id){  
  •         String url = "http://localhost:8080/jeecg/rest/tsBlackListController/"+id;  
  •         JSONObject resp= JwtHttpUtil.httpRequest(url, "GET", null,token);  
  •         return resp;  
  •     }  



  • 参考源码:
[java] view plain copy


  • package org.jeecgframework.test.demo;  
  •   
  • import org.jeecgframework.jwt.util.JwtHttpUtil;  
  •   
  • import com.alibaba.fastjson.JSONObject;  
  •   
  • /**
  • * jeecg jwt
  • * 接口客户端调用demo
  • * @author qinfeng
  • *
  • */  
  • public class JwtRestfulClientDemo {  
  •       
  •     public static String getToken(String userName,String password){  
  •         String url = "http://localhost:8080/jeecg/rest/tokens?username="+userName+"&password="+password;  
  •         String token= JwtHttpUtil.httpRequest(url, "POST", null);  
  •         return token;  
  •     }  
  •       
  •       
  •     //获取黑名单列表  
  •     public static JSONObject getBlackList(String token){  
  •         String url = "http://localhost:8080/jeecg/rest/tsBlackListController";  
  •         JSONObject resp= JwtHttpUtil.httpRequest(url, "GET", null,token);  
  •         return resp;  
  •     }  
  •       
  •     //创建黑名单  
  •     public static JSONObject createBlackList(String token,String json){  
  •         String url = "http://localhost:8080/jeecg/rest/tsBlackListController";  
  •         JSONObject resp= JwtHttpUtil.httpRequest(url, "POST", json,token);  
  •         return resp;  
  •     }  
  •       
  •       
  •     //更新黑名单  
  •     public static JSONObject updateBlackList(String token,String json){  
  •         String url = "http://localhost:8080/jeecg/rest/tsBlackListController";  
  •         JSONObject resp= JwtHttpUtil.httpRequest(url, "PUT", json,token);  
  •         return resp;  
  •     }  
  •       
  •       
  •     //删除黑名单  
  •     public static JSONObject deleteBlackList(String token,String id){  
  •         String url = "http://localhost:8080/jeecg/rest/tsBlackListController/"+id;  
  •         JSONObject resp= JwtHttpUtil.httpRequest(url, "DELETE", null,token);  
  •         return resp;  
  •     }  
  •       
  •     //查询黑名单  
  •     public static JSONObject getBlackList(String token,String id){  
  •         String url = "http://localhost:8080/jeecg/rest/tsBlackListController/"+id;  
  •         JSONObject resp= JwtHttpUtil.httpRequest(url, "GET", null,token);  
  •         return resp;  
  •     }  
  •       
  •       
  •     public static void main(String[] args) {  
  •         String token = getToken("interfaceuser","123456");  
  • //      String token = "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJhZG1pbiIsInN1YiI6ImFkbWluIiwiaWF0IjoxNTExODU5NjM2fQ.Emfe8VZKA_L33jaW8ZUtVFVDEin83Np_d3gKlPIZryE";  
  • //      System.out.println(token);  
  •          
  •         //添加黑名单  
  • //      JSONObject jsonObject=new JSONObject();  
  • //      jsonObject.put("ip","192.168.1.2");  
  • //      System.out.println("======添加黑名单======="+createBlackList(token,jsonObject.toJSONString()));  
  •         //更新黑名单  
  • //      JSONObject jsonObject=new JSONObject();  
  • //      jsonObject.put("id","402881ee6001da57016001dc13110001");  
  • //      jsonObject.put("ip","192.168.0.111");  
  • //      System.out.println("======更新黑名单======="+updateBlackList(token,jsonObject.toJSONString()));  
  •         //删除黑名单  
  • //      System.out.println("======删除黑名单======="+deleteBlackList(token,"402881ee6001da57016001dc13110001"));  
  •         //查询黑名单  
  • //      System.out.println("======查询黑名单======="+getBlackList(token,"402881ee6001e873016001f369f40008"));  
  •         //获取黑名单列表  
  •         System.out.println("======获取黑名单列表======="+getBlackList(token));  
  •     }  
  •   
  • }  

[java] view plain copy


  • package org.jeecgframework.jwt.util;  
  •   
  • import java.io.BufferedReader;  
  • import java.io.InputStream;  
  • import java.io.InputStreamReader;  
  • import java.io.OutputStream;  
  • import java.net.ConnectException;  
  • import java.net.HttpURLConnection;  
  • import java.net.URL;  
  • import org.jeecgframework.core.util.LogUtil;  
  • import com.alibaba.fastjson.JSONObject;  
  •   
  • /**
  • * JWT 客户端
  • * @author qinfeng
  • *
  • */  
  • public class JwtHttpUtil {  
  •   
  •     /**
  •      * 发起https请求并获取结果
  •      *  
  •      * @param requestUrl
  •      *            请求地址
  •      * @param requestMethod
  •      *            请求方式(GET、POST)
  •      * @param outputStr
  •      *            提交的数据
  •      * @return JSONObject(通过JSONObject.get(key)的方式获取json对象的属性值)
  •      */  
  •     public static JSONObject httpRequest(String requestUrl, String requestMethod, String outputStr, String sign) {  
  •         JSONObject jsonObject = null;  
  •         StringBuffer buffer = new StringBuffer();  
  •         HttpURLConnection httpUrlConn = null;  
  •         try {  
  •             // 创建SSLContext对象,并使用我们指定的信任管理器初始化  
  •             URL url = new URL(requestUrl);  
  •             httpUrlConn = (HttpURLConnection) url.openConnection();  
  •             httpUrlConn.setDoOutput(true);  
  •             httpUrlConn.setDoInput(true);  
  •             httpUrlConn.setUseCaches(false);  
  •             httpUrlConn.setRequestProperty("X-AUTH-TOKEN", sign);  
  •             httpUrlConn.setRequestProperty("Accept", "*/*");  
  •             httpUrlConn.setRequestProperty("Content-Type", "application/json");  
  •             // 设置请求方式(GET/POST)  
  •             httpUrlConn.setRequestMethod(requestMethod);  
  •             if ("GET".equalsIgnoreCase(requestMethod))  
  •                 httpUrlConn.connect();  
  •   
  •             // 当有数据需要提交时  
  •             if (null != outputStr) {  
  •                 OutputStream outputStream = httpUrlConn.getOutputStream();  
  •                 // 注意编码格式,防止中文乱码  
  •                 outputStream.write(outputStr.getBytes("UTF-8"));  
  •                 outputStream.close();  
  •             }  
  •   
  •             // 将返回的输入流转换成字符串  
  •             InputStream inputStream = httpUrlConn.getInputStream();  
  •             InputStreamReader inputStreamReader = new InputStreamReader(inputStream, "utf-8");  
  •             BufferedReader bufferedReader = new BufferedReader(inputStreamReader);  
  •   
  •             String str = null;  
  •             while ((str = bufferedReader.readLine()) != null) {  
  •                 buffer.append(str);  
  •             }  
  •             bufferedReader.close();  
  •             inputStreamReader.close();  
  •             // 释放资源  
  •             inputStream.close();  
  •             inputStream = null;  
  •             httpUrlConn.disconnect();  
  •             System.out.println(buffer.toString());  
  •             jsonObject = JSONObject.parseObject(buffer.toString());  
  •             // jsonObject = JSONObject.fromObject(buffer.toString());  
  •         } catch (ConnectException ce) {  
  •             LogUtil.info("Weixin server connection timed out.");  
  •         } catch (Exception e) {  
  •             e.printStackTrace();  
  •             org.jeecgframework.core.util.LogUtil.info("https request error:{}" + e.getMessage());  
  •         } finally {  
  •             try {  
  •                 httpUrlConn.disconnect();  
  •             } catch (Exception e) {  
  •                 e.printStackTrace();  
  •                 org.jeecgframework.core.util.LogUtil.info("http close error:{}" + e.getMessage());  
  •             }  
  •         }  
  •         return jsonObject;  
  •     }  
  •       
  •       
  •     /**  
  •      * 发起https请求并获取结果  
  •      *   
  •      * @param requestUrl  
  •      *            请求地址  
  •      * @param requestMethod  
  •      *            请求方式(GET、POST)  
  •      * @param outputStr  
  •      *            提交的数据  
  •      * @return JSONObject(通过JSONObject.get(key)的方式获取json对象的属性值)  
  •      */  
  •     public static String httpRequest(String requestUrl, String requestMethod, String outputStr) {  
  •         String res = "";  
  •         StringBuffer buffer = new StringBuffer();  
  •         HttpURLConnection httpUrlConn = null;  
  •         try {  
  •             // 创建SSLContext对象,并使用我们指定的信任管理器初始化  
  •             URL url = new URL(requestUrl);  
  •             httpUrlConn = (HttpURLConnection) url.openConnection();  
  •             httpUrlConn.setDoOutput(true);  
  •             httpUrlConn.setDoInput(true);  
  •             httpUrlConn.setUseCaches(false);  
  •             httpUrlConn.setRequestProperty("Accept", "text/plain");  
  •              httpUrlConn.setRequestProperty("Content-Type", "application/json");  
  •             // 设置请求方式(GET/POST)  
  •             httpUrlConn.setRequestMethod(requestMethod);  
  •             if ("GET".equalsIgnoreCase(requestMethod))  
  •                 httpUrlConn.connect();  
  •   
  •             // 当有数据需要提交时  
  •             if (null != outputStr) {  
  •                 OutputStream outputStream = httpUrlConn.getOutputStream();  
  •                 // 注意编码格式,防止中文乱码  
  •                 outputStream.write(outputStr.getBytes("UTF-8"));  
  •                 outputStream.close();  
  •             }  
  •   
  •             // 将返回的输入流转换成字符串  
  •             InputStream inputStream = httpUrlConn.getInputStream();  
  •             InputStreamReader inputStreamReader = new InputStreamReader(inputStream, "utf-8");  
  •             BufferedReader bufferedReader = new BufferedReader(inputStreamReader);  
  •   
  •             String str = null;  
  •             while ((str = bufferedReader.readLine()) != null) {  
  •                 buffer.append(str);  
  •             }  
  •             bufferedReader.close();  
  •             inputStreamReader.close();  
  •             // 释放资源  
  •             inputStream.close();  
  •             inputStream = null;  
  •             httpUrlConn.disconnect();  
  •             res = buffer.toString();  
  •             System.out.println(res);  
  • //          jsonObject = JSONObject.parseObject(buffer.toString());  
  •             // jsonObject = JSONObject.fromObject(buffer.toString());  
  •         } catch (ConnectException ce) {  
  •             LogUtil.info("Weixin server connection timed out.");  
  •         } catch (Exception e) {  
  •             e.printStackTrace();  
  •             org.jeecgframework.core.util.LogUtil.info("https request error:{}" + e.getMessage());  
  •         } finally {  
  •             try {  
  •                 httpUrlConn.disconnect();  
  •             } catch (Exception e) {  
  •                 e.printStackTrace();  
  •                 org.jeecgframework.core.util.LogUtil.info("http close error:{}" + e.getMessage());  
  •             }  
  •         }  
  •         return res;  
  •     }  
  •   
  • }  


  • 附录1:接口返回CODE

code
msg
说明
解决方案
0
SUCCESS
成功

-1
ERROR
无接口访问权限

1000
VALID_ERROR
验证失败

r0001
SAVE_SUCCESS
写入成功

r0002
UPDATE_SUCCESS
更新成功

r0003
REMOVE_SUCCESS
删除成功


发表于 2018-7-3 14:49:38 | 显示全部楼层
我按照上边的流程来做,自定义开发了接口,结果还是没办法调通,但是调试自带的黑名单示例接口确可以。
报错信息:

======获取token=======eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJ1aWMwMiIsInN1YiI6InVpYzAyIiwiaWF0IjoxNTMwNjAwNTQ3fQ.ceUEc2Z5TjezA29ZiFUUcQ74UTUU0UJEJse1D3BZHNg
java.io.FileNotFoundException: http://localhost:8080/jeecg/rest/appUserController
        at sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1623)
        at org.jeecgframework.jwt.util.JwtHttpUtil.httpRequest(JwtHttpUtil.java:63)
        at test.InterfaceTest.getAppUserList(InterfaceTest.java:34)
        at test.InterfaceTest.main(InterfaceTest.java:17)

求指导~~~
发表于 2018-7-19 11:16:54 | 显示全部楼层
配好了redis   做此文档里步骤四时  请求地址为 http://192.168.1.79:8080/sdaf/rest/tokens
报以下错误   不知何故
11111.gif
您需要登录后才可以回帖 登录 | 立即注册

本版积分规则

快速回复 返回顶部 返回列表