当前位置：首页 > news >正文

OneNET HTTP/HTTPS API 鉴权：从普通API Key到安全Token的5步升级指南

news 2026/7/11 19:34:12

OneNET HTTP/HTTPS API 鉴权升级实战：从API Key到安全Token的完整迁移方案

物联网应用的快速发展对API安全性提出了更高要求。作为国内主流物联网平台，OneNET近期对API鉴权机制进行了重要升级，从传统的API Key模式转向更安全的Token鉴权体系。本文将深入解析两种鉴权方式的本质区别，并提供一套可落地的五步迁移方案，帮助开发者顺利完成鉴权升级。

1. 新旧鉴权机制核心差异解析

在开始迁移前，我们需要透彻理解新旧两种鉴权方式的根本区别。以下是对比表格展示了关键差异点：

特性	API Key鉴权（旧版）	Token鉴权（新版）
核心密钥	apiKey	accessKey
Header参数名	`api-key`	`Authorization`
密钥传输方式	直接传输原始密钥	签名计算结果，不含原始密钥
时效控制	不支持	支持（通过et参数设置过期时间）
自定义权限	不支持	支持（即将推出）
密钥更新机制	不支持	支持（即将推出）
安全性等级	较低	较高

关键差异解读：

新版Token鉴权采用签名机制，避免了密钥在网络上直接传输
时效性控制可有效降低密钥泄露风险
未来将支持更细粒度的权限控制，实现最小权限原则

2. 五步迁移实施指南

2.1 获取新版accessKey

迁移第一步需要从OneNET控制台获取新的accessKey。与旧版apiKey不同，accessKey需要妥善保管，因为它将作为生成Token的基础密钥。

重要提示：accessKey相当于系统根密钥，建议采用以下安全措施：
使用密钥管理系统（KMS）存储
设置严格的访问权限
启用定期轮换机制（即将支持）

2.2 修改HTTP请求Header

旧版请求示例：

GET /devices/12345 HTTP/1.1 Host: api.heclouds.com api-key: your_api_key_here

新版请求需要改为：

GET /devices/12345 HTTP/1.1 Host: api.heclouds.com Authorization: version=2022-05-01&res=userid/12345&et=1630000000&method=sha1&sign=xxxxxx

主要变更点：

Header参数名从api-key变为Authorization
参数值变为结构化Token字符串

2.3 实现Token生成算法

Token生成是迁移的核心环节，以下是Python实现示例：

import hashlib import hmac import time import urllib.parse def generate_token(access_key, user_id, expires=3600): version = "2022-05-01" method = "sha1" et = str(int(time.time()) + expires) res = f"userid/{user_id}" # 构造待签名字符串 to_sign = f"et={et}&method={method}&res={res}&version={version}" # 计算HMAC-SHA1签名 signature = hmac.new(access_key.encode(), to_sign.encode(), hashlib.sha1).hexdigest() # URL编码各参数 params = { "version": version, "res": urllib.parse.quote(res), "et": et, "method": method, "sign": signature } # 构造完整Token return "&".join(f"{k}={v}" for k,v in params.items())

2.4 处理时效性与自动更新

新版Token具有时效性（默认1小时），需要实现自动更新机制。推荐两种方案：

预刷新机制：在Token过期前（如剩余5分钟时）自动生成新Token
错误重试机制：当收到401错误时，自动生成新Token并重试请求

以下是自动更新示例代码：

class TokenManager: def __init__(self, access_key, user_id): self.access_key = access_key self.user_id = user_id self.token = None self.expires_at = 0 def get_token(self): now = time.time() if now + 300 > self.expires_at: # 提前5分钟刷新 self.refresh_token() return self.token def refresh_token(self): self.token = generate_token(self.access_key, self.user_id) self.expires_at = time.time() + 3600