Skip to content

生成用户签名 ​

APP 服务端主要负责生成用户鉴权签名(userSignature)并返回给客户端,该签名是客户端进行身份鉴权的核心凭证。

一、前置准备 ​

在开始集成前,请确保完成以下准备工作:

  • 配置数据对称加密密钥:需在 SUD OpenPaaS 管理后台完成对称密钥的配置(详见 数据安全密钥说明)。当前采用 AES-256-GCM 算法,密钥为 32 字节(256 位),Base64 编码。请妥善保管该密钥。

二、生成鉴权签名 ​

服务端需要构造特定的 JSON 数据并进行加密,以生成鉴权所需的 用户鉴权签名(userSignature)。

1. 构造加密载荷 (Payload) ​

请构造包含以下字段的紧凑格式 JSON 字符串(无 空格、无换行):

json
{"version":"1","user_id":"xxx","expires_at":1761638855}
参数名必填类型说明
version是string协议版本号,当前固定值为 1(无多余空格)
user_id是string用户的唯一标识 ID(非空,建议与业务侧用户 ID 保持一致)
expires_at是int签名过期的 Unix 时间戳(单位:秒,UTC 时区);建议有效期不超过 24 小时

参数校验规则:

  • version 必须为字符串 "1",不允许修改;
  • user_id 不能为空字符串或空值;
  • expires_at 必须为整型正数,且需大于当前时间戳(避免签名生成即过期)。

2. 加密处理 ​

使用在前置准备中配置的数据对称加密密钥,按 AES-256-GCM 规范对上述 JSON 字符串进行加密。加密结果格式统一为:初始化向量 (IV) + 密文 + 认证标签,并对该二进制数据进行 Base64 编码,最终返回 Base64 编码字符串。

AES-256-GCM 算法参数:

  • 加密算法:AES-256-GCM
  • 密钥长度:256 位(32 字节)
  • 初始化向量(IV):每次加密必须随机生成,长度为 12 字节(96位)
  • 认证标签长度:16 字节(128 位)
  • 字符编码:UTF-8

三、示例代码 ​

完整示例代码(包含 Payload 构造、参数校验与 AES-256-GCM 加密)见 示例代码 下各语言版本的 「1. userSignature 生成」 章节。

四、常见问题排查 ​

加密失败常见原因 ​

  1. 密钥格式错误:密钥不是合法的 Base64 编码,或解码后长度不为 32 字节。
  2. Payload 格式错误:使用格式化 JSON(含空格/换行)、字段类型错误(如 expires_at 为字符串);
  3. 字符编码不一致:未使用 UTF-8 编码加密字符串;
  4. IV 生成不安全:使用了固定 IV 或弱随机数生成器(必须使用密码学安全的随机数)。
  5. 跨语言拼接顺序不一致:加密结果必须严格遵循 IV(12字节) + 密文 + 认证标签(16字节) 的顺序。
  6. expires_at 异常:时间戳为非整型、已过期、时区错误(非 UTC)。

签名鉴权失败补充检查 ​

  1. 确认 version 固定为字符串 "1",非数字 1;
  2. 确认 expires_at 时间戳未过期,且为 UTC 时区;
  3. 确认加密前的 JSON 字符串无任何格式修改(如多余逗号、字段顺序变更)。