Agent SDK Secretos y HMAC Firma
Proteja las credenciales del Agente API y comprenda cómo el SDK genera firmas de solicitud HMAC-SHA256 resistentes a la reproducción y con marca de tiempo.
Las solicitudes Agent SDK se autentican con un secreto de socio API. Mantenga ese secreto dentro de un servicio backend confiable y permita que SDK genere campos de firma siempre que sea posible.
Dos protocolos de firma
Agent SDK la firma utiliza campos de solicitud ordenados, una marca de tiempo basada en segundos y un nonce. Las solicitudes directas Developer API utilizan el proceso separado descrito en Solicitar firma. No reutilice un formato de carga útil para el otro.
regla de firma
Para solicitudes Agent SDK:
- Excluya el campo
sign. - Omitir campos con valores vacíos.
- Ordene los nombres de campos restantes en ASCII orden.
- Une los campos como
k=v&k2=v2. - Calcula la firma hexadecimal HMAC-SHA256 con
apiSecret.
Los valores de la matriz se serializan como JSON compacto antes de unirse a la carga útil de firma. Por ejemplo, platformUserIds firma como ["1188041528"], dando platformUserIds=["1188041528"] en la carga útil k=v. Preservar el orden de los elementos de la matriz, las comillas dobles y los ID de cadenas; no inserte espacios de formato ni utilice Java List.toString() (como [1188041528]). El SDK maneja esta serialización automáticamente.
El SDK debería generar este valor a partir de los mismos datos que envía. Cambiar un campo firmado después de la generación de la firma provoca que falle la verificación.
SDK-campos administrados
Almacenamiento secreto
- Cargue
apiSecretdesde un administrador secreto backend o una configuración de tiempo de ejecución protegida. - Nunca coloque el secreto en paquetes de interfaz, aplicaciones móviles, clientes de escritorio, capturas de pantalla o tickets de soporte.
- Mantenga separadas las credenciales de desarrollo, puesta en escena y producción.
- Limitar el acceso a los servicios y operadores que lo requieran.
- Redactar firmas de solicitudes, valores de autorización y secretos de los registros.
- Revocar y reemplazar las credenciales cuando se sospeche de exposición.
Protección de reloj y reproducción
El SDK incluye timestamp y nonce para reducir el riesgo de repetición. Mantenga sincronizados los relojes del backend y no reutilice un nonce creado manualmente. Si la validación de la firma falla, confirme el secreto configurado, la hora del servidor, los campos serializados y el entorno antes de volver a intentarlo.