基于AK和SK认证鉴权OpenAPI

v3.8.1+支持

本文介绍了基于安全认证Access Key/Secret Key鉴权，HTTP调用API的流程。

应用场景：通过AK/SK的方式来调用API接口，主要用于第三方系统对接，避免了token的复杂性和安全性问题。

API 调用流程简介

基于安全认证AK/SK进行鉴权，调用API流程如下图所示。

1. 创建安全认证的AK/SK账号。获取安全认证Access Key（即AK）、Secret Key（即SK）。
2. 接口配置并授权，通过平台配置接口，并将接口授权给AK/SK账号。
3. 生成鉴权签名signature。根据签名算法生成鉴权信息signature。
4. 调用API接口。

API 调用流程

步骤一：API授权

在系统中创建OpenAPI接口配置，并将接口授权给指定的AK/SK账号。只有被授权的接口才允许调用，否则将被拒绝。

步骤二：获取安全认证AK/SK

在系统中获取安全认证的 Access Key（AK）和 Secret Key（SK），用于后续生成签名。

步骤三：生成用于鉴权的认证字符串signature

调用OpenAPI时，需要在请求头中添加以下三个参数：

请求头	说明	示例
appkey	授权的AK（appkey）	ak-r2nbujSB6SKwUp42
timestamp	当前时间戳（毫秒）	1710000000000
signature	签名字符串，算法为 md5(appkey + sk + timestamp)	e10adc3949ba59abbe56e057f20f883e

调用地址格式：{baseUrl}/openapi/call/{path}?参数...

返回结果格式：

字段	说明
code	状态码
message	提示信息
result	接口返回的业务数据
success	是否成功（true/false）
timestamp	时间戳

查看OpenAPI可调用接口，启动jeecg后，访问swagger地址，找到OpenAPI组即可。

通过单元测试调用OpenAPI示例

package org.jeecg.modules.openapi.test;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.apache.http.HttpEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import org.junit.jupiter.api.Test;

import java.security.MessageDigest;

/**
 * OpenAPI 开放接口调用示例
 *
 * 调用地址: {baseUrl}/openapi/call/{path}?参数...
 * 请求头: appkey, signature, timestamp
 * 签名算法: signature = MD5(appkey + sk + timestamp)
 */
public class SampleOpenApiTest {
    private final String base_url = "http://localhost:8080/jeecg-boot";
    private final String appKey = "ak-r2nbujSB6SKwUp42";
    private final String searchKey = "XpZpRzlwVBBrEiyIwS5FdRQPGQZsMxJw";

    @Test
    public void test() throws Exception {
        // 根据部门ID查询用户
        String url = base_url+"/openapi/call/TEwcXBlr?id=c6d7cb4deeac411cb3384b1b31278596";
        JSONObject header = genTimestampAndSignature();
        HttpGet httpGet = new HttpGet(url);
        // 设置请求头
        httpGet.setHeader("Content-Type", "application/json");
        httpGet.setHeader("appkey",appKey);
        httpGet.setHeader("signature",header.get("signature").toString());
        httpGet.setHeader("timestamp",header.get("timestamp").toString());
        try (CloseableHttpClient httpClient = HttpClients.createDefault();
             CloseableHttpResponse response = httpClient.execute(httpGet);) {
            // 获取响应状态码
            int statusCode = response.getStatusLine().getStatusCode();
            System.out.println("[debug] 响应状态码: " + statusCode);

            HttpEntity entity = response.getEntity();
            System.out.println(entity);
            // 获取响应内容
            String responseBody = EntityUtils.toString(response.getEntity());
            System.out.println("[debug] 响应内容: " + responseBody);

            // 解析JSON响应
            JSONObject res = JSON.parseObject(responseBody);
            //错误日志判断
            if(res.containsKey("success")){
                Boolean success = res.getBoolean("success");
                if(success){
                    System.out.println("[info] 调用成功： " + res.toJSONString());
                }else{
                    System.out.println("[error] 调用失败： " + res.getString("message"));
                }
            }else{
                System.out.println("[error] 调用失败： " + res.getString("message"));
            }
        }

    }

    /**
     * 生成 timestamp 和 signature
     */
    private JSONObject genTimestampAndSignature(){
        JSONObject jsonObject = new JSONObject();
        long timestamp = System.currentTimeMillis();
        jsonObject.put("timestamp",timestamp);
        jsonObject.put("signature", md5(appKey + searchKey + timestamp));
        return jsonObject;
    }

    protected String md5(String sourceStr) {
        String result = "";
        try {
            MessageDigest md = MessageDigest.getInstance("MD5");
            md.update(sourceStr.getBytes("utf-8"));
            byte[] hash = md.digest();
            int i;
            StringBuffer buf = new StringBuffer(32);
            for (int offset = 0; offset < hash.length; offset++) {
                i = hash[offset];
                if (i < 0) {
                    i += 256;
                }
                if (i < 16) {
                    buf.append("0");
                }
                buf.append(Integer.toHexString(i));
            }
            result = buf.toString();
        } catch (Exception e) {
            throw new RuntimeException("sign签名错误", e);
        }
        return result;
    }
}

通过Postman调用OpenAPI示例

• header（必须项）

• 参数（可选项）

参考博客：https://cloud.baidu.com/doc/WENXINWORKSHOP/s/Hlwerugt8

管理后台使用说明

系统菜单路径：OpenAPI → 授权管理 / 接口管理 / 日志管理 / 接口文档

接口配置

在"接口管理"页面，可以将系统内部接口开放为 OpenAPI 供外部调用。

新增接口步骤：

1. 点击"新增"按钮，填写以下基本信息：

字段	说明
接口名称	便于识别的名称，如"查询用户列表"
接口地址	自动生成的对外调用路径（短码），点击可复制完整地址
请求方式	GET / POST / PUT / DELETE 等
原始接口	系统内部实际接口路径，如 /sys/depart/list，必须以 / 开头
IP 白名单	限制允许调用的来源IP，支持精确IP、CIDR网段、通配符；为空则不限制
接口描述	对该接口用途的说明

2. 在下方 Tabs 中补充详细配置：

Tab	说明
请求头	配置调用时必须携带的 Header 参数（默认已包含 appKey、signature、timestamp）
请求参数	配置 URL Query 参数，支持设置参数类型、是否必填、默认值、示例值
请求体	配置 POST 请求的 Body（JSON 格式）
响应配置	配置响应示例和响应字段说明，用于生成接口文档

IP白名单示例：192.168.1.100（精确IP）、10.0.0.0/8（CIDR网段）、172.16.*.*（通配符），每行一条或逗号分隔。

---

授权管理

在"授权管理"页面管理 AK/SK 账号，每个账号对应一个外部调用方（如合作方系统）。

字段	说明
授权对象	调用方名称，如"ERP系统"、"移动端App"
访问密钥（AK）	调用时使用的 Access Key，格式如 ak-xxxxxxxx
签名密钥（SK）	用于生成签名的 Secret Key（页面不展示，通过详情查看）

创建后将 AK/SK 提供给调用方，调用方据此生成签名进行鉴权。

---

日志管理

"日志管理"页面记录所有 OpenAPI 的调用记录，可用于排查问题（2026.5.25 以后支持）。

列表字段说明：

字段	说明
调用时间	接口被调用的时间
请求方式	GET / POST / PUT / DELETE 等
请求路径	实际调用的接口路径，如 /jeecg-boot/openapi/call/xxxxxx
调用者AK	发起调用的 AK 账号
来源IP	调用方的 IP 地址
状态码	HTTP 响应状态码（200=成功，401=鉴权失败，500=服务异常）

筛选条件： 支持按调用者AK、来源IP、请求路径、请求方式、响应状态码、调用时间范围筛选。

点击"详情"可查看完整的请求头、请求参数、响应内容及耗时信息，便于定位问题。

---

接口文档

"接口文档"页面以 Swagger UI 形式展示所有已配置的 OpenAPI，包括接口地址、请求方式、参数说明、响应示例等，方便调用方查阅和调试。