Agent SDK の秘密と HMAC の署名
エージェント API の認証情報を保護し、SDK がタイムスタンプ付きのリプレイ耐性のある HMAC-SHA256 リクエスト署名を生成する方法を理解します。
Agent SDK リクエストはパートナー API シークレットで認証されます。その秘密を信頼できるバックエンド サービス内に保管し、可能な限り SDK に署名フィールドを生成させます。
2 つの署名プロトコル
Agent SDK 署名では、並べ替えられたリクエスト フィールド、秒ベースのタイムスタンプ、およびナンスが使用されます。直接の 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 が含まれています。バックエンドクロックの同期を維持し、手動で構築したノンスを再利用しないでください。署名の検証が失敗した場合は、再試行する前に、構成されたシークレット、サーバー時間、シリアル化されたフィールド、および環境を確認してください。