Streaming SDK コネクタの認証の設定
Streaming SDKで構築されたすべてのコネクタには、認証が必要です。 コネクタを送信またはリリースする前に、サポートされる1つの認証メカニズムを設定します。
コネクタの統合モデルに一致するメカニズムを設定します。
始める前に
次の要素が含まれていることを確認します。
- Streaming SDK コネクタの実装が完了しました。
- ストリーミング取り込みAPI エンドポイントをステージングまたはテストします。
- Adobeの組織とサンドボックスのテスト。
- テストイベントペイロード。
- 資格情報を安全に保存および移動するための計画。
- 秘密鍵を公開することなく、リクエストと応答の詳細を取得できる方法です。
その他のOAuth要件
OAuth 2.0を使用する場合は、次の要件を満たしていることを確認してください。
- Adobe Developer Consoleへのアクセス：
- コネクタに必要なAPIまたは製品プロファイル。
- 選択した資格情報のクライアント IDとクライアント秘密鍵。
- 必要なスコープ。
- コネクタに必要なOAuth フローとトークンエンドポイント。
適切なAdobe資格情報の種類と実装の詳細については、次を参照してください。
追加のHMAC要件
HMACを使用する場合は、次の条件を満たしていることを確認してください。
- Webhookまたはコネクター用に設定された共有シークレット。
- 秘密鍵を保存するための安全な場所。
- HMAC-SHA256署名を計算できるコード。
- Adobeに送信される正確なシリアル化されたイベント本文。
- 有効、無効、欠落、およびローテーションされたシークレットのテスト手順。
OAuth 2.0の設定
1. Adobe資格情報の作成または選択
まず、コネクタに必要なAdobe Developer Console資格情報を作成または選択する必要があります。
次の設定を行います。
- 資格情報タイプ。
- 必要なAdobe APIまたは製品プロファイル。
- 必要なスコープ。
- 選択したOAuth フローに適用できる場合は、リダイレクトまたは同意の設定。
コネクタの統合モデルでサポートされていない資格情報タイプを使用しないでください。
2. OAuth設定を安全に保存する
次の値を安全に保存します。
- クライアント ID。
- クライアントの秘密鍵：
- 必要な範囲：
- トークンエンドポイント：
- コネクタ固有のテナント、組織、または環境の値。
クライアントシークレットをソースコントロールにコミットしたり、ログ、エラーメッセージ、スクリーンショット、テスト結果に含めたりしないでください。
3. コネクタへのOAuth設定の追加
コネクタの独自の設定またはサービスにOAuth設定値を保存します。 Streaming SDKでは、この認証手順の接続仕様フィールドは定義されません。これは、コネクタがStreaming Ingestion APIを呼び出す方法を制御するためであり、Experience Platformがソースに接続する方法を制御しないためです。
コネクタの設定には、次のものが含まれている必要があります。
- 認証タイプ：
- クライアント ID。
- クライアントの秘密鍵：
- 範囲：
- トークンエンドポイント：
- 資格情報タイプに必要な追加のテナントまたは組織の値。
4. アクセストークンの取得
資格情報タイプについて文書化されたOAuth フローを実装します。
コネクタには次の操作が必要です。
- 設定したOAuth資格情報を使用して認証します。
- Streaming SDK統合で必要なスコープをリクエストします。
- アクセストークンをメモリまたは別の安全な場所に保存します。
- トークンの有効期間に応じて、トークンを更新または再取得します。
- トークンまたはクライアントシークレットのログ記録を避けます。
5. リクエストへのアクセストークンの追加
コネクターから送信されたリクエストに、アクセストークンをベアラートークンとして含めます。
Authorization: Bearer {ACCESS_TOKEN}
すべてのリクエストにHTTPSを使用します。
6. トークンの失敗の処理
コネクタは、次のような認証エラーを検出して処理する必要があります。
- アクセストークンがありません。
- 期限切れのアクセストークン：
- クライアント資格情報が無効です。
- 範囲が不十分です。
- 認証情報が失効または無効になりました。
トークンの有効期限が切れると、文書化されたOAuth フローを使用して新しいトークンを取得し、操作が安全に再試行できる場合にのみ再試行します。
HMAC ベースの認証の設定
1. 共有シークレットの設定
コネクタで必要な共有シークレットを作成または取得し、コネクタまたはwebhook設定で設定します。
秘密鍵は次でなければなりません：
- 安全に保存。
- 実行時に署名コードで使用できます。
- ソース管理とログから除外されます。
- セキュリティポリシーに従ってローテーションされます。
2. イベントのシリアル化
署名を計算する前に、イベントをシリアライズします。
署名は、コネクタがリクエスト本文に送信するのと同じシリアル化されたメッセージから計算する必要があります。
serializedMessage = serialize(event)
イベントの1つの表現から署名を計算し、別の表現を送信しないでください。 空白、プロパティの順序、エスケープ、エンコーディングまたは行末文字を変更すると、署名の検証が失敗する可能性があります。
3. HMAC-SHA256署名の計算
次を使用してHMAC-SHA256値を計算します。
- キー：設定済みの共有秘密鍵。
- メッセージ：シリアル化されたリクエスト本文。
signature = HMAC-SHA256(secret, serializedMessage)
4. HMAC ヘッダーの追加
計算された署名をx-hmac-sha256 ヘッダーとしてリクエストに追加します。
POST <streaming-ingestion-endpoint>
Content-Type: application/json
x-hmac-sha256: {CALCULATED_SIGNATURE}
<serialized-message>
例えば、ヘッダーは次のような値に解決されます。
{
"x-hmac-sha256": "5f2c8b7e0d9c3a4e6b1f2d3c4a5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3"
}
ヘッダー値は、Adobeに送信された正確なリクエスト本文のHMAC-SHA256計算を表す必要があります。
5. リクエストを送信
署名済みリクエストをHTTPS経由でストリーミング取得API エンドポイントに送信します。
ストリーミング取り込みAPIは、イベントを処理する前に署名を検証します。 署名が見つからないか無効なリクエストは拒否されます。
6. シークレットを安全に回転する
シークレットをローテーションする場合は、次の順序に従います。
- 資格情報管理システムで新しい秘密鍵を作成します。
- 重複するシークレットがサポートされている場合は、新しいシークレットをデプロイする間、既存のシークレットをアクティブのままにします。
- 新しい秘密鍵でコネクタ設定を更新します。
- 設定をデプロイまたは保存します。
- テストリクエストを送信し、認証が成功したことを確認します。
- 認証エラーを監視してから、すべてのコネクタインスタンスが新しい秘密鍵を使用した後に、古い秘密鍵を取り消します。
コネクタの確認
成功した認証シナリオと失敗した認証シナリオの両方を使用して、コネクタをテストします。
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 | |
|---|---|
| テスト | 期待される結果 |
| 有効なアクセストークンを使用したリクエスト | イベントは受け入れられ、処理されます。 |
| アクセストークンを使用しないリクエスト | リクエストは拒否されます。 |
| 期限切れのアクセストークンを使用したリクエスト | リクエストが拒否されるか、コネクタが新しいトークンを取得し、再試行ポリシーに従って再試行します。 |
| 無効なアクセストークンを使用したリクエスト | リクエストは拒否されます。 |
| 範囲が不十分なリクエスト | リクエストは拒否されます。 |
| 資格情報のローテーション後のリクエスト | コネクタは、新しい資格情報を正常に取得して使用します。 |
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 | |
|---|---|
| テスト | 期待される結果 |
| 有効な署名と現在の秘密鍵を使用したリクエスト | イベントは受け入れられ、処理されます。 |
x-hmac-sha256を含まないリクエスト |
リクエストは拒否されます。 |
| 無効な署名を含むリクエスト | リクエストは拒否されます。 |
| 間違った秘密鍵で署名されたリクエスト | リクエストは拒否されます。 |
| 署名の生成後にリクエスト本文が変更されました | リクエストは拒否されます。 |
| ローテーション中に有効な以前の秘密鍵で署名されたリクエスト | この結果は、文書化されたシークレットローテーションの動作に従います。 |
| 削除された秘密鍵で署名された要求 | リクエストは拒否されます。 |
各テストに対して次の項目を記録します。
- リクエストメソッドとエンドポイント：
- シークレットとトークンが墨消しされたリクエストヘッダー。
- シリアル化されたリクエスト本文。
- 使用される認証メカニズム。
- 応答のステータスと本文：
- タイムスタンプと相関関係またはトレース識別子（使用可能な場合）。
- イベントが正常に取り込まれたかどうか。
トラブルシューティング
OAuth認証エラー
次の項目を確認します。
- アクセストークンは、適切なAdobeの組織と環境に対して生成されました。
- クライアント IDとクライアント秘密鍵は、設定された資格情報に属しています。
- 要求された範囲は正しいです。
- アクセストークンの有効期限が切れていません。
- トークンは、Authorization: Bearer スキームを使用して送信されます。
- コネクタで正しいトークンエンドポイントが使用されています。
- 資格情報は、必要なAPIまたは製品プロファイルにアクセスできます。
HMAC認証エラー
次の項目を確認します。
x-hmac-sha256ヘッダーが存在します。- ヘッダーの名前と値が正しく入力されています。
- コネクタは正しい秘密鍵を使用しています。
- 署名はHMAC-SHA256で計算されます。
- 署名は、正確にシリアル化されたリクエスト本文を通じて計算されます。
- 署名を計算した後、リクエスト本文は再フォーマットされません。
- 必要な署名エンコーディングと文字の大文字と小文字は正しいです。
- コネクタは、回転中に正しい現在または以前の秘密鍵を使用しています。
- シークレットはランタイムで利用でき、切り捨てられたり変更されたりしていません。
提出の要件
コネクタを送信またはリリースする前に、次の点を確認してください。
- コネクターは、ストリーミング取得APIへのリクエストごとにOAuth 2.0またはHMAC ベースの認証を使用します。
- コネクタの検証でシナリオをテストし、結果を記録しました。
- コネクタは、未認証および誤って認証されたリクエストを拒否します。
- 秘密鍵とトークンは、ソース管理、ログ、エラーメッセージ、スクリーンショットにはコミットされません。
次の手順
認証が設定され、検証された状態で、 テストに進み、ソースを送信します。 ソースの認証要件を文書化する方法については、「 ソースを文書化する（ストリーミング SDK） 」を参照してください。