Files
aibridge/docs/interface-oauth/README.md
T
2026-05-18 09:28:15 +08:00

191 lines
4.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` |