3.8 KiB
3.8 KiB
认证机制详解
认证流程
外部系统调用数据接口时,经过以下认证流程:
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
- 调用的接口
- 请求参数
- 响应状态