生成用户签名
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 生成」 章节。
四、常见问题排查
加密失败常见原因
- 密钥格式错误:密钥不是合法的 Base64 编码,或解码后长度不为 32 字节。
- Payload 格式错误:使用格式化 JSON(含空格/换行)、字段类型错误(如 expires_at 为字符串);
- 字符编码不一致:未使用 UTF-8 编码加密字符串;
- IV 生成不安全:使用了固定 IV 或弱随机数生成器(必须使用密码学安全的随机数)。
- 跨语言拼接顺序不一致:加密结果必须严格遵循 IV(12字节) + 密文 + 认证标签(16字节) 的顺序。
- expires_at 异常:时间戳为非整型、已过期、时区错误(非 UTC)。
签名鉴权失败补充检查
- 确认
version固定为字符串 "1",非数字 1; - 确认
expires_at时间戳未过期,且为 UTC 时区; - 确认加密前的 JSON 字符串无任何格式修改(如多余逗号、字段顺序变更)。
