首页 登录

对接文档

本文档说明如何把你的软件接入 北辰网络授权中心 的授权体系。所有接口均位于 /api/，采用 RSA-SHA256 请求签名，无需在请求中明文传输密钥。

一、整体流程

  1. 在用户中心创建一个应用，得到 AppID 与 API Key，并下载该应用的 RSA 私钥（PEM）。
  2. 在你的软件里采集机器或站点的唯一识别码，通过 apply_auth 接口提交授权申请，并填写授权文件将要部署的网站根目录地址。
  3. 后台（管理员或代理）审核授权、设定有效期（留空为永久），平台生成随机文件名的授权文件。
  4. 你下载该文件，放到之前填写的网站根目录。巡查站会定期访问该文件核验有效性。
  5. 软件启动时调用 query_auth 或读取本地文件后调用 verify_file 判断授权状态。

二、请求签名（RSA-SHA256）

每个请求都需携带以下公共参数，并对它们（不含 sign）按 key 升序拼接成待签名串后用应用私钥签名：

参数说明
action接口名称，如 apply_auth
app_id应用 ID
api_key应用 API Key
timestampUnix 时间戳，与服务器误差需在 ±300 秒内
nonce随机串，选填，用于进一步防重放
sign对以上参数拼接串的 RSA 签名（base64）

拼接规则：把除 sign 外的所有参数按 key 字典序排序，拼接为 key1=value1&key2=value2...，再用 SHA256WithRSA 签名。

PHP 签名示例

<?php
function sign($params, $privateKey) {
    unset($params['sign']);
    ksort($params);
    $str = http_build_query($params); // 或手动拼接 key=value&
    openssl_sign($str, $sig, $privateKey, OPENSSL_ALGO_SHA256);
    return base64_encode($sig);
}

$params = [
    'action'    => 'query_auth',
    'app_id'    => 'APPxxxxxxxx',
    'api_key'   => 'AKxxxxxxxx',
    'timestamp' => time(),
    'unique_code' => 'WIN-ABC-123',
];
$params['sign'] = sign($params, file_get_contents('app_private.pem'));

$ch = curl_init('https://你的站点/api/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resp = json_decode(curl_exec($ch), true);
?>

Python 签名示例

import json, time, base64, hashlib
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

def sign(params, priv_pem):
    p = {k: v for k, v in params.items() if k != 'sign'}
    items = '&'.join(f'{k}={p[k]}' for k in sorted(p))
    key = serialization.load_pem_private_key(priv_pem, password=None)
    sig = key.sign(items.encode(), padding.PKCS1v15(), hashes.SHA256())
    return base64.b64encode(sig).decode()

params = {'action':'query_auth','app_id':'APPxxx','api_key':'AKxxx',
          'timestamp':int(time.time()),'unique_code':'WIN-ABC-123'}
params['sign'] = sign(params, open('app_private.pem','rb').read())

三、接口说明

1. apply_auth 提交授权申请

业务参数：unique_code（唯一识别码）、deploy_url（授权文件部署的网站根目录，需 http(s):// 开头）。

返回示例：

{ "code":0, "msg":"授权申请已提交，等待审核", "data":{ "request_id":12, "status":"pending" } }

2. query_auth 查询授权状态

业务参数：unique_code。

{ "code":0, "msg":"ok", "data":{
  "authorized":true, "status":"authorized",
  "expire_at":0, "expire_text":"永久",
  "issued_at":1696000000, "last_check_at":1696000500,
  "last_check_status":"正常" } }

3. verify_file 核验已部署的授权文件

把软件读取到的本地授权文件原文（JSON 字符串）放进业务参数 file 提交，平台用服务器公钥验签并比对令牌、有效期。

{ "code":0, "msg":"授权文件有效", "data":{ "valid":true, "app_id":"APPxxx", "expire_at":0 } }

若无效，data.valid=false 并给出原因：sign_error / token_mismatch / not_authorized / expired。

4. heartbeat 心跳上报

用于在线统计，业务参数选填 unique_code。返回 {"code":0,"msg":"pong","data":{"time":...}}。

5. get_app_info 获取应用信息

无需业务参数，返回应用名称、状态、创建时间。

6. renew_auth 续期申请

业务参数 unique_code。提交后该记录回到待审核状态，由后台重新设定有效期。

四、授权文件格式

授权文件是一个 JSON，由平台用服务器私钥签名，内容如下：

{
  "app_id": "APPxxxxxxxx",
  "unique_code": "WIN-ABC-123",
  "expire_at": 0,
  "issued_at": 1696000000,
  "token": "随机令牌",
  "sign": "RSA 签名(base64)"
}

软件可定期读取该文件并调用 verify_file 核验；巡查站也会直接访问该文件做服务端核验。

五、巡查机制

平台提供巡查脚本 station/index.php，建议通过系统定时任务每 5 分钟执行一次：

*/5 * * * * php /你的路径/zy-auth/station/index.php >> /var/log/zy_station.log 2>&1

脚本会逐个访问已授权设备部署的授权文件，验证签名、令牌与有效期，并把巡查结果（正常 / 文件缺失 / 签名异常 / 令牌不符 / 已过期）写回后台，便于你掌握每台机器的真实部署情况。

需要帮助？可联系平台管理员。所有接口返回均为 JSON，code=0 表示成功。

北辰网络授权中心 · 对接文档