JNPF 接口认证 (InterfaceOauth) 开发指南
概述
InterfaceOauth 是 JNPF 平台的外部系统接口认证机制,用于:
- 为第三方应用分配
appId+appSecret访问凭证 - 控制哪些数据接口可以被外部调用
- 可选启用 HMAC-SHA256 签名验证增强安全性
- 记录接口调用日志
注意:这与 dataExceptionJson(JS脚本验证)是完全独立的两个机制:
dataExceptionJson:接口内部的 JS 脚本验证(API类型接口专用)InterfaceOauth:外部系统访问的 API Key 认证
文档索引
| 文档 | 说明 |
|---|---|
| README.md | 本文档,概述与快速开始 |
| 认证机制 | 认证流程、签名算法、错误码 |
| 使用指南 | 创建认证、绑定接口、调用示例 |
快速开始
1. 创建接口认证
from aibridge import JNPFClient, JNPFConfig
client = JNPFClient.from_config(JNPFConfig())
client.login()
oauth = client.interface_oauth
# 获取新秘钥
secret_resp = oauth.get_app_secret()
app_secret = secret_resp.data
# 创建认证
resp = oauth.create({
"appId": "my_app",
"appName": "我的应用",
"appSecret": app_secret,
"verifySignature": 0, # 0=不验签, 1=验签
"enabledMark": 1,
})
oauth_id = resp.data # 假设返回ID
2. 绑定授权接口
# 绑定允许访问的数据接口
oauth.bind_interfaces(oauth_id, [
"83ae1f5e5c26447b8c4849ead352b048", # 当前用户
"420587863533428357", # 行政区划
])
3. 外部系统调用
不启用签名验证(verifySignature=0)
import requests
app_id = "my_app"
app_secret = "生成的秘钥"
di_id = "83ae1f5e5c26447b8c4849ead352b048"
response = requests.get(
f"http://localhost:30000/api/system/DataInterface/{di_id}/Actions/Response",
headers={
"Authorization": f"{app_id}::{app_secret}",
"UserKey": "user_key_123",
}
)
启用签名验证(verifySignature=1)
import base64
import hmac
import hashlib
import time
app_id = "my_app"
app_secret = "生成的秘钥"
di_id = "83ae1f5e5c26447b8c4849ead352b048"
method = "GET"
url_path = f"/api/system/DataInterface/{di_id}/Actions/Response"
timestamp = int(time.time() * 1000)
# 签名源字符串
source = f"{method}\n{url_path}\n{timestamp}\n\n"
signature = hmac.new(
base64.b64decode(app_secret),
source.encode('utf-8'),
hashlib.sha256
).hexdigest()
response = requests.get(
f"http://localhost:30000{url_path}",
headers={
"Authorization": f"{app_id}::{signature}",
"YmDate": str(timestamp),
"UserKey": "user_key_123",
}
)
核心概念
认证字段
| 字段 | 说明 |
|---|---|
| appId | 应用ID(唯一标识) |
| appSecret | 应用秘钥(自动生成或手动输入) |
| verifySignature | 是否启用签名验证:0=否, 1=是 |
| usefulLife | 使用期限(为空表示永久有效) |
| whiteList | IP白名单(多个用英文逗号分隔) |
| dataInterfaceIds | 授权访问的数据接口ID列表 |
签名算法
当 verifySignature=1 时,使用 HMAC-SHA256 签名:
签名源 = method + '\n' + url + '\n' + timestamp + '\n' + host + '\n'
签名 = HMAC-SHA256(appSecret Base64解码, 签名源).hex()
错误码
| 错误码 | 含义 |
|---|---|
| SYS124 | 请求已过期(时间戳超过1分钟) |
| SYS125 | 签名验证失败 |
| SYS126 | 已超过使用期限 |
| SYS127 | AppId 不存在 |
| FA021 | 接口未授权访问 |
AIBridge API
oauth = client.interface_oauth
# CRUD
oauth.get_list(data) # 获取认证列表
oauth.create(data) # 创建认证
oauth.update(data) # 修改认证
oauth.get_info(oauth_id) # 获取详情(含授权接口和用户)
oauth.delete(oauth_id) # 删除认证
# 秘钥
oauth.get_app_secret() # 获取新秘钥
# 授权
oauth.get_interface_list(oauth_id) # 获取已授权接口
oauth.bind_interfaces(oauth_id, interface_ids) # 绑定接口
oauth.get_user_list(oauth_id) # 获取授权用户
oauth.save_user_list(oauth_id, users) # 保存授权用户
# 日志
oauth.get_log(oauth_id, data) # 获取调用日志
源码位置
| 资源 | 路径 |
|---|---|
| 前端入口 | 前端/.../views/dataCenter/interfaceOauth/ |
| 前端API | 前端/.../api/systemData/interfaceOauth.ts |
| 后端Controller | 后端/.../base/controller/InterfaceOauthController.java |
| 后端Service | 后端/.../base/service/impl/InterfaceOauthServiceImpl.java |
| 签名工具 | 后端/.../base/util/interfaceutil/InterfaceUtil.java |
| 实体类 | 后端/.../base/entity/InterfaceOauthEntity.java |
| AIBridge模块 | aibridge/modules/interface_oauth.py |