Agent SDK 비밀 및 HMAC 서명
에이전트 API 자격 증명을 보호하고 SDK가 타임스탬프가 지정된 재생 방지 HMAC-SHA256 요청 서명을 생성하는 방법을 이해합니다.
Agent SDK 요청은 파트너 API 비밀로 인증됩니다. 신뢰할 수 있는 백엔드 서비스 내에 해당 비밀을 유지하고 가능할 때마다 SDK가 서명 필드를 생성하도록 하십시오.
2가지 서명 프로토콜
Agent SDK 서명은 정렬된 요청 필드, 초 기반 타임스탬프 및 nonce를 사용합니다. 직접 Developer API 요청은 다음에 설명된 별도의 프로세스를 사용합니다. 서명 요청. 하나의 페이로드 형식을 다른 페이로드 형식에 재사용하지 마십시오.
서명 규칙
Agent SDK 요청의 경우:
sign필드를 제외합니다.- 값이 비어 있는 필드를 생략합니다.
- 나머지 필드 이름을 ASCII 순서로 정렬합니다.
- 필드를
k=v&k2=v2로 결합합니다. - HMAC-SHA256 16진수 서명을
apiSecret로 계산합니다.
배열 값은 서명 페이로드에 합류하기 전에 압축된 JSON로 직렬화됩니다. 예를 들어, platformUserIds는 ["1188041528"]로 서명되어 k=v 페이로드에 platformUserIds=["1188041528"]를 제공합니다. 배열 요소 순서, 큰따옴표 및 문자열 ID를 유지합니다. 서식 지정 공백을 삽입하거나 Java List.toString()(예: [1188041528])를 사용하지 마세요. SDK는 이 직렬화를 자동으로 처리합니다.
SDK는 전송하는 것과 동일한 데이터에서 이 값을 구축해야 합니다. 서명 생성 후 서명된 필드를 변경하면 확인이 실패합니다.
SDK-관리 필드
비밀 저장
- 백엔드 비밀 관리자 또는 보호된 런타임 구성에서
apiSecret을 로드합니다. - 프런트엔드 번들, 모바일 앱, 데스크톱 클라이언트, 스크린샷 또는 지원 티켓에 비밀을 넣지 마세요.
- 개발, 스테이징, 프로덕션에 대한 자격 증명을 별도로 보관하세요.
- 이를 필요로 하는 서비스 및 운영자에 대한 액세스를 제한하십시오.
- 로그에서 요청 서명, 인증 값, 비밀을 수정합니다.
- 노출이 의심되는 경우 자격 증명을 취소하고 교체합니다.
시계 및 재생 보호
SDK에는 재생 위험을 줄이기 위해 timestamp 및 nonce가 포함되어 있습니다. 백엔드 시계를 동기화된 상태로 유지하고 수동으로 구성된 nonce를 재사용하지 마세요. 서명 검증에 실패하면 구성된 비밀, 서버 시간, 직렬화된 필드 및 환경을 확인한 후 다시 시도하세요.