Files
2026-05-18 09:28:15 +08:00

3.8 KiB
Raw Permalink Blame History

认证机制详解

认证流程

外部系统调用数据接口时,经过以下认证流程:

1. 解析请求头 Authorization → {appId}::{signature/secret}
         ↓
2. 验证 appId 有效性
   - appId 存在
   - 接口在授权列表中
   - enabledMark = 1(已启用)
         ↓
3. 签名验证(verifySignature=1 时)
   - 验证时间戳(1分钟内有效)
   - 验证 HMAC-SHA256 签名
         ↓
   (verifySignature=0 时)
   - 仅验证 appSecret 匹配
         ↓
4. 验证使用期限
   - usefulLife 为空 或 未过期
         ↓
5. 获取用户 token
   - 通过 UserKey 获取
         ↓
6. IP 白名单验证
   - whiteList 为空 或 当前IP在白名单中
         ↓
7. 调用实际数据接口

签名算法

verifySignature=1(启用签名)

// 签名源字符串格式
String source = method + '\n' + url + '\n' + timestamp + '\n' + host + '\n';

// 示例
method = "GET"
url = "/api/system/DataInterface/xxx/Actions/Response"
timestamp = "1743600000000"
host = "localhost:30000"

source = "GET\n/api/system/DataInterface/xxx/Actions/Response\n1743600000000\nlocalhost:30000\n"

// HMAC-SHA256 签名
Mac mac = Mac.getInstance("HmacSHA256");
SecretKeySpec secretKeySpec = new SecretKeySpec(Base64.decodeBase64(appSecret), "HmacSHA256");
mac.init(secretKeySpec);
String signature = Hex.encodeHexString(mac.doFinal(source.getBytes("UTF-8")));

verifySignature=0(不启用签名)

直接使用 appSecret 作为签名:

Authorization: {appId}::{appSecret}

请求头说明

请求头 说明 必需
Authorization 认证信息,格式:{appId}::{signature} 或 {appId}::{appSecret} 是
YmDate 时间戳(毫秒),verifySignature=1 时必需 条件必需
UserKey 用户标识,用于获取调用方用户身份 是
Host 请求主机(参与签名计算) 条件必需

错误码详解

SYS124 - 请求已过期

原因:YmDate 时间戳超过1分钟
解决:确保请求前生成新的时间戳,确保客户端与服务端时间同步

SYS125 - 签名验证失败

原因:HMAC-SHA256 签名不匹配
解决:
1. 确认 appSecret 正确
2. 确认签名源字符串格式正确(注意换行符 \n)
3. 确认 appSecret 是 Base64 编码后的字符串

SYS126 - 使用期限已过

原因:usefulLife 设置了日期且已过期
解决:修改接口认证的 usefulLife 或清空(永久有效)

SYS127 - AppId 不存在

原因:提供的 appId 在 base_data_interface_oauth 表中不存在
解决:确认 appId 正确,检查接口认证是否已删除

FA021 - 接口未授权

原因:appId 未授权访问该数据接口
解决:在 JNPF 平台中将该接口ID添加到授权列表

数据表结构

base_data_interface_oauth

字段 类型 说明
F_Id varchar(50) 主键
F_App_Id varchar(100) 应用ID(唯一)
F_App_Name varchar(100) 应用名称
F_App_Secret varchar(500) 应用秘钥
F_Verify_Signature int 是否验签:0=否, 1=是
F_Useful_Life datetime 使用期限
F_White_List text IP白名单
F_Black_List text IP黑名单
F_Data_Interface_Ids text 授权接口ID列表(逗号分隔)
F_Enabled_Mark int 启用状态:0=禁用, 1=启用

base_data_interface_user

字段 类型 说明
F_Id varchar(50) 主键
F_Interface_Oauth_Id varchar(50) 关联的认证ID
F_User_Id varchar(50) 用户ID
F_User_Key varchar(100) 用户标识

调用日志

每次接口调用会记录日志,包含:

  • 调用时间
  • 调用方 IP
  • 使用的 UserKey
  • 调用的接口
  • 请求参数
  • 响应状态