# JNPF 接口认证 (InterfaceOauth) 开发指南 ## 概述 InterfaceOauth 是 JNPF 平台的**外部系统接口认证机制**,用于: - 为第三方应用分配 `appId` + `appSecret` 访问凭证 - 控制哪些数据接口可以被外部调用 - 可选启用 HMAC-SHA256 签名验证增强安全性 - 记录接口调用日志 **注意**:这与 `dataExceptionJson`(JS脚本验证)是完全独立的两个机制: - `dataExceptionJson`:接口内部的 JS 脚本验证(API类型接口专用) - `InterfaceOauth`:外部系统访问的 API Key 认证 --- ## 文档索引 | 文档 | 说明 | |------|------| | **README.md** | 本文档,概述与快速开始 | | [认证机制](01-auth-mechanism.md) | 认证流程、签名算法、错误码 | | [使用指南](02-usage-guide.md) | 创建认证、绑定接口、调用示例 | --- ## 快速开始 ### 1. 创建接口认证 ```python 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. 绑定授权接口 ```python # 绑定允许访问的数据接口 oauth.bind_interfaces(oauth_id, [ "83ae1f5e5c26447b8c4849ead352b048", # 当前用户 "420587863533428357", # 行政区划 ]) ``` ### 3. 外部系统调用 #### 不启用签名验证(verifySignature=0) ```python 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) ```python 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 ```python 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` |