"""接口认证 (InterfaceOauth) 模块 对应前端源码: api/systemData/interfaceOauth.ts 关键机制(基于后端源码分析): - AppId/AppSecret 认证:外部系统通过 appId + appSecret 调用接口 - 签名验证:verifySignature=1 时启用 HMAC-SHA256 签名验证 - 授权接口绑定:一个 AppId 可授权访问多个数据接口 - 用户秘钥:UserKey 用于标识调用方用户 - 黑/白名单:IP 白名单限制,支持黑名单排除 - 使用期限:usefulLife 可设置有效期 认证流程(基于 infoToIdNew 方法): 1. 从请求头 Authorization 解析 appId 和签名 2. 验证 appId 有效性、接口在授权列表中、启用状态 3. 若 verifySignature=1:验证时间戳(1分钟内)和 HMAC-SHA256 签名 4. 若 verifySignature=0:仅验证 appSecret 匹配 5. 验证使用期限 6. 通过 UserKey 获取用户 token 7. 验证 IP 白名单 8. 调用实际数据接口 参考: - 后端: InterfaceOauthController.java, InterfaceOauthServiceImpl.java - 后端工具: InterfaceUtil.java(签名算法) - 前端: api/systemData/interfaceOauth.ts - 实体: base_data_interface_oauth 表 """ import json from typing import Any, Dict, List, Optional from aibridge.client import JNPFClient from aibridge.models import APIResponse class InterfaceOauthAPI: """接口认证 API 提供接口认证的 CRUD 管理,以及外部系统调用数据接口的能力。 典型用法:: oauth = InterfaceOauthAPI(client) # 创建认证 oauth_id = oauth.create({ "appId": "my_app", "appName": "我的应用", "appSecret": "生成的秘钥", "verifySignature": 0, }) # 绑定授权接口 oauth.bind_interfaces(oauth_id, ["di_id_1", "di_id_2"]) # 外部系统调用(使用生成的 appId 和 appSecret) # GET /api/system/DataInterface/{id}/Actions/Response # Header: Authorization: {appId}::{signature} (verifySignature=1) # 或 {appId}::{appSecret} (verifySignature=0) # Header: YmDate: {timestamp} (verifySignature=1 时必需) # Header: UserKey: {userKey} (用户标识) """ def __init__(self, client: JNPFClient): self._client = client self._prefix = "/api/system/InterfaceOauth" # ==================== 基础 CRUD ==================== def get_list(self, data: dict = None) -> APIResponse: """获取接口认证列表(分页) Args: data: 查询参数,常用字段: - currentPage, pageSize: 分页 - keyword: 关键字搜索 """ return self._client.request("GET", self._prefix, params=data) def get_selector(self) -> APIResponse: """获取接口认证下拉框""" return self._client.request("GET", f"{self._prefix}/Selector") def create(self, data: dict) -> APIResponse: """新建接口认证 Args: data: 认证配置,常用字段: - appId: 应用ID(唯一) - appName: 应用名称 - appSecret: 秘钥(可调用 get_app_secret 获取) - verifySignature: 0=不验签, 1=验签 - usefulLife: 使用期限(日期,可为空表示永久) - whiteList: IP白名单(多个用英文逗号分隔) - enabledMark: 1=启用, 0=禁用 """ return self._client.request("POST", self._prefix, data=data) def update(self, data: dict) -> APIResponse: """修改接口认证""" oauth_id = data.get("id") return self._client.request("PUT", f"{self._prefix}/{oauth_id}", data=data) def get_info(self, oauth_id: str) -> APIResponse: """获取接口认证详情(含授权接口列表和用户列表)""" return self._client.request("GET", f"{self._prefix}/{oauth_id}") def delete(self, oauth_id: str) -> APIResponse: """删除接口认证""" return self._client.request("DELETE", f"{self._prefix}/{oauth_id}") # ==================== 秘钥管理 ==================== def get_app_secret(self) -> APIResponse: """获取新的应用秘钥 Returns: 返回新生成的 UUID 秘钥(去连字符) """ return self._client.request("GET", f"{self._prefix}/getAppSecret") # ==================== 授权管理 ==================== def get_interface_list(self, oauth_id: str) -> APIResponse: """获取已授权的接口列表 Args: oauth_id: 接口认证ID """ return self._client.request("GET", f"{self._prefix}/getInterfaceList/{oauth_id}") def bind_interfaces(self, oauth_id: str, interface_ids: List[str]) -> APIResponse: """绑定授权接口 Args: oauth_id: 接口认证ID interface_ids: 数据接口ID列表 """ data = { "interfaceIdentId": oauth_id, "dataInterfaceIds": ",".join(interface_ids), } return self._client.request("POST", f"{self._prefix}/saveInterfaceList", data=data) # ==================== 用户授权 ==================== def get_user_list(self, oauth_id: str) -> APIResponse: """获取授权用户列表""" resp = self.get_info(oauth_id) if resp.success and resp.data: return resp.data.get("userList", []) return [] def save_user_list(self, oauth_id: str, users: List[dict]) -> APIResponse: """保存授权用户 Args: oauth_id: 接口认证ID users: 用户列表,每个元素: - userId: 用户ID - userKey: 用户标识 """ data = { "interfaceIdentId": oauth_id, "userList": users, } return self._client.request("POST", f"{self._prefix}/SaveUserList", data=data) # ==================== 日志 ==================== def get_log(self, oauth_id: str, data: dict = None) -> APIResponse: """获取接口调用日志 Args: oauth_id: 接口认证ID data: 查询参数: - currentPage, pageSize: 分页 """ return self._client.request("GET", f"{self._prefix}/dataInterfaceLog/{oauth_id}", params=data) # ==================== 外部调用 ==================== @staticmethod def build_authorization_header(app_id: str, app_secret: str, method: str = "GET", url_path: str = "", timestamp: int = None, verify_signature: bool = False) -> dict: """构建外部调用所需的请求头(仅用于参考,实际应从后端获取) Args: app_id: 应用ID app_secret: 应用秘钥 method: 请求方法 url_path: 请求路径(如 /api/system/DataInterface/{id}/Actions/Response) timestamp: 时间戳(毫秒),verifySignature=1 时必需 verify_signature: 是否启用签名验证 Returns: 请求头字典,包含: - Authorization: {appId}::{signature} 或 {appId}::{appSecret} - YmDate: 时间戳(仅验签时) - UserKey: 用户标识 """ headers = {} if verify_signature: import base64 import hmac import hashlib from urllib.parse import quote if timestamp is None: import time timestamp = int(time.time() * 1000) # 签名源字符串: method + '\n' + url + '\n' + timestamp + '\n' + host + '\n' source = f"{method}\n{url_path}\n{timestamp}\n\n" signature = hmac.new( base64.b64decode(app_secret), source.encode('utf-8'), hashlib.sha256 ).hexdigest() headers["Authorization"] = f"{app_id}::{signature}" headers["YmDate"] = str(timestamp) else: headers["Authorization"] = f"{app_id}::{app_secret}" return headers # ==================== 验证示例 ==================== # 场景1: 创建接口认证 # secret_resp = oauth.get_app_secret() # app_secret = secret_resp.data # oauth.create({ # "appId": "test_app", # "appName": "测试应用", # "appSecret": app_secret, # "verifySignature": 0, # "enabledMark": 1, # }) # 场景2: 绑定授权接口 # oauth.bind_interfaces(oauth_id, ["di_id_1", "di_id_2"]) # 场景3: 获取调用日志 # logs = oauth.get_log(oauth_id, {"currentPage": 1, "pageSize": 20})