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

4.8 KiB
Raw Permalink Blame History

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