191 lines
4.8 KiB
Markdown
191 lines
4.8 KiB
Markdown
# 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` |
|