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

admin 发表于 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值，并返回数据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和端口。
view plain copy#redis
redis.host=124.206.91.99
redis.port=6379
redis.pass=
redis.adapter.maxIdle=100
redis.adapter.minIdle=10
redis.adapter.testOnBorrow=true
redis.adapter.testOnReturn=true
redis.adapter.testWhileIdle=true
redis.adapter.numTestsPerEvictionRun=10
redis.adapter.timeBetweenEvictionRunsMillis=60000四、接口说明

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

■描述    根据用户名和密码获取TOKEN。 ■访问地址    http://域名/rest/tokens ■访问方式    GET ■参数
参数名数据类型是否必须示例值默认值描述
usernameStringY“admin”
用户名
passwordStringY“123456”
密码
■返回值    成功时，直接返回token字符串。    失败时，直接返回用户账号密码错误! ■校验规则    无 ■请求示例    请求地址：http://域名/rest/tokens{
"username":"admin",
"password":"123456"
} ■返回示例
[*]成功案例：
eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI4YThhYjBiMjQ2ZGM4MTEyMDE0NmRjODE4MTk1MDA1MiIsInN1YiI6ImFkbWluIiwiaWF0IjoxNTExODU0NDE4fQ.tnILZEivS-6YOX9uqsnCHygh7-XrG_-Sj8vLslNGkdQ
失败案例：
用户账号密码错误!
2. 创建黑名单信息接口

■描述    创建黑名单信息接口，黑名单为单表。 ■访问地址    http://域名/rest/tsBlackListController ■访问方式    POST ■参数（详见excel）
参数名数据类型是否必须示例值默认值描述
ipStringY“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和来源表。{
"ip": "192.1.1.1",
……(省略信息其他字段)
} ■返回示例

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

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

■请求示例    请求地址：http://域名/rest/tsBlackListController/get/297e7ae15f7f7f7e015f7fb0f57e0040 ■返回示例

[*]成功案例:
{

"message": "成功",

"data": {

   "id": "402881f15e751d2a015e75212c570005",

   "createBy": "admin",

   "updateBy": "",

   "bpmStatus": "1",

   "ip": "111.193.210.4",

   "createName": "管理员",

   "createDate": "2017-09-12 16:07:41",

   "updateName": "",

   "updateDate": null,

   "sysOrgCode": "A03",

   "sysCompanyCode": "A03"

},

"respCode": "0",

"ok": true

}[*]失败案例：{"data":null,"respCode":"-1","respMsg":"根据所传id查询无结果"}
4. 修改黑名单信息接口

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

ipStringY“192.168.1.1”

……省略信息其他字段……
■返回值
参数名描述
respCode返回码（见附录1接口返回信息列表）
respMsg返回信息（见附录1接口返回信息列表）
data返回结果（NULL）
ok状态
■校验规则    通过校验主表的字段：来源id和来源表验证数据唯一性。 ■请求示例    请求地址：http://域名/rest/tsBlackListController/update/402881f15f811877015f8124ca1c0002    参数如下：{
"id": "402881e75f94878e015f94896bb80002",
"ip": "1.1.1.1"

} ■返回示例成功案例：
{
"respCode":"0",
"respMsg":"成功"
}

失败案例：
{
"respCode":"-1",
"respMsg":"输入ID无效,重复输入"
}5. 删除黑名单接口

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

代码示例

[*]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;
[*] }

[*]参考源码：
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));
[*] }
[*]
[*]}

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

codemsg说明解决方案
0SUCCESS成功

-1ERROR无接口访问权限

1000VALID_ERROR验证失败

r0001SAVE_SUCCESS写入成功

r0002UPDATE_SUCCESS更新成功

r0003REMOVE_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)

求指导~~~

pangzi5920 发表于 2018-7-19 11:16:54

配好了redis 做此文档里步骤四时请求地址为 http://192.168.1.79:8080/sdaf/rest/tokens
报以下错误不知何故

页: [1]

JEECG技术论坛 - 基于BPM的低代码开发平台's Archiver

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