Generate User Signature
The APP Server is mainly responsible for generating the user authentication signature (userSignature) and returning it to the client. This signature is the core credential used by the client for identity authentication.
1. Prerequisites
Before starting integration, make sure the following preparation is complete:
- Configure the data symmetric encryption key: You need to configure the symmetric key in the SUD OpenPaaS admin console (see Data Security Key Reference). The current algorithm is AES-256-GCM, with a 32-byte (256-bit) key in Base64 encoding. Keep this key safe.
2. Generate the Authentication Signature
The server needs to construct specific JSON data and encrypt it to generate the user authentication signature (userSignature) required for authentication.
1. Construct the encryption payload (Payload)
Construct a compact JSON string (no spaces, no line breaks) containing the following fields:
{"version":"1","user_id":"xxx","expires_at":1761638855}| Parameter | Required | Type | Description |
|---|---|---|---|
| version | Yes | string | Protocol version number, currently a fixed value of 1 (no extra spaces) |
| user_id | Yes | string | The user's unique identifier ID (non-empty, recommended to keep consistent with the business-side user ID) |
| expires_at | Yes | int | The Unix timestamp when the signature expires (unit: seconds, UTC time zone); a validity period of no more than 24 hours is recommended |
Parameter validation rules:
versionmust be the string "1" and must not be modified;user_idmust not be an empty string or a null value;expires_atmust be a positive integer and must be greater than the current timestamp (to avoid the signature expiring at the moment it is generated).
2. Encryption Processing
Using the data symmetric encryption key configured in the prerequisites, encrypt the above JSON string according to the AES-256-GCM specification. The encryption result is uniformly formatted as: initialization vector (IV) + ciphertext + auth tag, then Base64-encode this binary data, and finally return the Base64-encoded string.
AES-256-GCM algorithm parameters:
- Encryption algorithm: AES-256-GCM
- Key length: 256 bits (32 bytes)
- Initialization vector (IV): must be randomly generated for each encryption, with a length of 12 bytes (96 bits)
- Auth tag length: 16 bytes (128 bits)
- Character encoding: UTF-8
3. Example Code
Complete example code (including Payload construction, parameter validation, and AES-256-GCM encryption) is available in the "1. userSignature Generation" section of each language version under Example Code.
4. Common Troubleshooting
Common causes of encryption failure
- Malformed key: the key is not valid Base64 encoding, or its length after decoding is not 32 bytes.
- Malformed Payload: using formatted JSON (with spaces/line breaks), or wrong field types (e.g., expires_at as a string);
- Inconsistent character encoding: the string was not encrypted using UTF-8 encoding;
- Insecure IV generation: a fixed IV or a weak random number generator was used (a cryptographically secure random number must be used).
- Inconsistent cross-language concatenation order: the encryption result must strictly follow the order IV (12 bytes) + ciphertext + auth tag (16 bytes).
- Abnormal expires_at: the timestamp is non-integer, already expired, or in the wrong time zone (not UTC).
Additional checks for signature authentication failure
- Confirm that
versionis fixed as the string "1", not the number 1; - Confirm that the
expires_attimestamp has not expired and is in the UTC time zone; - Confirm that the JSON string before encryption has no format modifications whatsoever (such as extra commas or changed field order).
