嵌入签名与令牌

概述

平台没有 OAuth、CAS、SAML 一类的标准单点登录协议。第三方系统接入的免登录方式是签名免登：第三方后端用 appSecret 对「应用 ID、账号、姓名、报表 ID、过期时间」做 HMAC-SHA256，把载荷和签名一起做 Base64Url 编码，得到一个签名串（参数名 _s）。平台收到签名串后验签，自动查找或创建对应的外部用户，再放行访问。

签名是在第三方服务端本地计算的，不需要调用平台接口去申请。使用前先在 第三方应用管理 中注册应用获取 appId 与 appSecret。

签名规则

载荷字段：

验签失败或不满足条件时，平台返回的提示：

reportId 的绑定方式

操作步骤

用 curl 生成签名并换取会话令牌

以下脚本依赖 openssl，可在 Linux 与 macOS 终端运行。

BASE=https://your-domain          # 平台访问地址
APP_ID=erp-system
SECRET='在三方集成页面保存的 appSecret'
ACCOUNT=zhangsan
NAME='张三'
REPORT=rpt_sales
EXPIRE=$(( $(date +%s) + 600 ))   # 10 分钟后过期，单位秒

SIGN=$(printf '%s' "$APP_ID|$ACCOUNT|$NAME|$REPORT|$EXPIRE" \
  | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')

PAYLOAD=$(printf '{"appId":"%s","account":"%s","userName":"%s","reportId":"%s","expireAt":%s,"signature":"%s"}' \
  "$APP_ID" "$ACCOUNT" "$NAME" "$REPORT" "$EXPIRE" "$SIGN")

# Base64Url，无填充
S=$(printf '%s' "$PAYLOAD" | base64 | tr -d '\n=' | tr '+/' '-_')

# 用签名换取嵌入会话
curl -s -X POST "$BASE/api/embed/auth" \
  -H 'Content-Type: application/json' \
  -d "{\"signature\":\"$S\",\"reportId\":\"$REPORT\"}"

成功响应（code 为 200）：

{
  "code": 200,
  "success": true,
  "message": "...",
  "data": {
    "sessionToken": "embed_3f2c...",
    "userId": "b1c9...",
    "userName": "张三",
    "externalAccount": "ext__erp-system__zhangsan",
    "appId": "erp-system",
    "reportId": "rpt_sales",
    "expireAt": 1790658966000
  }
}

expireAt 是会话过期时间，毫秒时间戳，取「签名过期时间」与「当前时间加应用最大有效期」中较早者。之后调用需要嵌入会话的接口时，带上请求头 X-Embed-Session: <sessionToken>：

curl -s "$BASE/api/embed/session/validate" -H "X-Embed-Session: embed_3f2c..."

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public static String buildSignature(String appId, String secret, String account,
                                    String userName, String reportId, int expireMinutes) throws Exception {
    long expireAt = System.currentTimeMillis() / 1000 + expireMinutes * 60L;
    String content = String.join("|", appId, account, userName,
            reportId != null ? reportId : "", String.valueOf(expireAt));
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    StringBuilder hex = new StringBuilder();
    for (byte b : mac.doFinal(content.getBytes(StandardCharsets.UTF_8))) hex.append(String.format("%02x", b));
    String payload = String.format(
        "{\"appId\":\"%s\",\"account\":\"%s\",\"userName\":\"%s\",\"reportId\":\"%s\",\"expireAt\":%d,\"signature\":\"%s\"}",
        appId, account, userName, reportId != null ? reportId : "", expireAt, hex);
    return Base64.getUrlEncoder().withoutPadding().encodeToString(payload.getBytes(StandardCharsets.UTF_8));
}

Python

import base64, hashlib, hmac, json, time

def build_signature(app_id, secret, account, user_name, report_id="", expire_minutes=10):
    expire_at = int(time.time()) + expire_minutes * 60
    content = "|".join([app_id, account, user_name, report_id, str(expire_at)])
    sig = hmac.new(secret.encode(), content.encode(), hashlib.sha256).hexdigest()
    payload = json.dumps({
        "appId": app_id, "account": account, "userName": user_name,
        "reportId": report_id, "expireAt": expire_at, "signature": sig,
    }, ensure_ascii=False)
    return base64.urlsafe_b64encode(payload.encode()).rstrip(b"=").decode()

Node.js

const crypto = require('crypto');

function buildSignature(appId, secret, account, userName, reportId = '', expireMinutes = 10) {
  const expireAt = Math.floor(Date.now() / 1000) + expireMinutes * 60;
  const content = [appId, account, userName, reportId, expireAt].join('|');
  const signature = crypto.createHmac('sha256', secret).update(content).digest('hex');
  const payload = JSON.stringify({ appId, account, userName, reportId, expireAt, signature });
  return Buffer.from(payload).toString('base64url');
}

注意事项

注意：appSecret 只能在第三方服务端使用；每次打开报表都应实时生成新的签名，不要长期缓存或写进静态页面。

注意：平台对 /api/embed/** 按客户端 IP 限流，每个 IP 每分钟最多 120 次请求，超过返回 429（请求频率超限，请稍后再试）。

提示：签名有效期只需覆盖「打开页面」这一步，有效期建议 5 到 15 分钟。会话建立后，嵌入页遇到会话过期会自动用地址栏中的签名重新认证，此时签名本身也必须还在有效期内。

提示：expireAt 是秒，会话的 expireAt 是毫秒，两者单位不同。

相关文档

• 第三方应用管理
• 报表集成
• 嵌入接口清单
• 公开链接与访问密码
• 登录集成