Agent SDK Secrets et HMAC Signature
Protégez les informations d’identification de l’agent API et comprenez comment le SDK génère des signatures de requête HMAC-SHA256 horodatées et résistantes à la relecture.
Les requêtes Agent SDK sont authentifiées avec un secret API partenaire. Gardez ce secret dans un service backend de confiance et laissez SDK générer des champs de signature autant que possible.
Deux protocoles de signature
La signature Agent SDK utilise des champs de requête triés, un horodatage basé sur les secondes et un nom occasionnel. Les requêtes directes Developer API utilisent le processus distinct décrit dans Demande de signature. Ne réutilisez pas un format de charge utile pour un autre.
Règle de signature
Pour les requêtes Agent SDK :
- Excluez le champ
sign. - Omettez les champs avec des valeurs vides.
- Triez les noms de champs restants dans l’ordre ASCII.
- Joignez les champs sous la forme
k=v&k2=v2. - Calculez la signature hexadécimale HMAC-SHA256 avec
apiSecret.
Les valeurs du tableau sont sérialisées sous forme compacte JSON avant de rejoindre la charge utile de signature. Par exemple, platformUserIds signe comme ["1188041528"], donnant platformUserIds=["1188041528"] dans la charge utile k=v. Conservez l’ordre des éléments du tableau, les guillemets doubles et les ID de chaîne ; n’insérez pas d’espaces de formatage et n’utilisez pas Java List.toString() (comme [1188041528]). Le SDK gère automatiquement cette sérialisation.
Le SDK doit construire cette valeur à partir des mêmes données qu’il envoie. La modification d’un champ signé après la génération de la signature entraîne l’échec de la vérification.
SDK-champs gérés
Stockage secret
- Chargez
apiSecretà partir d’un gestionnaire de secrets backend ou d’une configuration d’exécution protégée. - Ne placez jamais le secret dans les bundles frontaux, les applications mobiles, les clients de bureau, les captures d’écran ou les tickets d’assistance.
- Séparez les informations d’identification pour le développement, la préparation et la production.
- Limiter l’accès aux services et aux opérateurs qui en ont besoin.
- Supprimez les signatures de requêtes, les valeurs d’autorisation et les secrets des journaux.
- Révoquer et remplacer les informations d’identification lorsqu’une exposition est suspectée.
Protection de l’horloge et de la relecture
Le SDK inclut timestamp et nonce pour réduire le risque de relecture. Gardez les horloges back-end synchronisées et ne réutilisez pas un occasionnel construit manuellement. Si la validation de la signature échoue, confirmez le secret configuré, l’heure du serveur, les champs sérialisés et l’environnement avant de réessayer.