Agent SDK Segreti e HMAC Firma
Proteggi le credenziali dell’agente API e scopri come il SDK genera firme di richiesta con timestamp e resistenti alla riproduzione HMAC-SHA256.
Le richieste Agent SDK vengono autenticate con un segreto del partner API. Mantieni il segreto all’interno di un servizio backend affidabile e lascia che SDK generi campi di firma quando possibile.
Due protocolli di firma
La firma Agent SDK utilizza campi di richiesta ordinati, un timestamp basato sui secondi e un nonce. Le richieste dirette Developer API utilizzano il processo separato descritto in Richiedi la firma. Non riutilizzare un formato di payload per un altro.
Regola di firma
Per le richieste Agent SDK:
- Escludere il campo
sign. - Omettere i campi con valori vuoti.
- Ordina i nomi dei campi rimanenti nell’ordine ASCII.
- Unisci i campi come
k=v&k2=v2. - Calcola la firma esadecimale HMAC-SHA256 con
apiSecret.
I valori dell’array vengono serializzati come compatti JSON prima di unirsi al payload della firma. Ad esempio, platformUserIds viene indicato come ["1188041528"], fornendo platformUserIds=["1188041528"] nel payload k=v. Conserva l’ordine degli elementi dell’array, le virgolette doppie e gli ID delle stringhe; non inserire spazi di formattazione né utilizzare Java List.toString() (ad esempio [1188041528]). Il SDK gestisce questa serializzazione automaticamente.
Il SDK dovrebbe creare questo valore dagli stessi dati che invia. La modifica di un campo firmato dopo la generazione della firma causa il fallimento della verifica.
SDK-campi gestiti
Deposito segreto
- Carica
apiSecretda un gestore segreto backend o da una configurazione runtime protetta. - Non inserire mai il segreto in bundle frontend, app mobili, client desktop, screenshot o ticket di supporto.
- Mantieni separate le credenziali per lo sviluppo, la gestione temporanea e la produzione.
- Limitare l’accesso ai servizi e agli operatori che lo richiedono.
- Oscura le firme delle richieste, i valori di autorizzazione e i segreti dai log.
- Revocare e sostituire le credenziali quando si sospetta un’esposizione.
Protezione orologio e riproduzione
Il SDK include timestamp e nonce per ridurre il rischio di rigiocabilità. Mantieni sincronizzati gli orologi di backend e non riutilizzare un nonce costruito manualmente. Se la convalida della firma fallisce, conferma il segreto configurato, l’ora del server, i campi serializzati e l’ambiente prima di riprovare.