設定串流SDK聯結器的驗證
使用串流SDK建置的所有聯結器都需要驗證。 送出或釋放聯結器之前，請先設定一個支援的驗證機制：
設定符合聯結器整合模型的機制。
開始之前
請確定您擁有：
- 已完成的串流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設定值儲存在聯結器自己的設定或服務中。 串流SDK不會為此驗證步驟定義連線規格欄位，因為它控制您的聯結器呼叫串流擷取API的方式，而非Experience Platform連線至您的來源的方式。
您的聯結器設定必須包括：
- 驗證型別。
- 使用者端ID。
- 使用者端密碼。
- 範圍。
- 權杖端點。
- 您的認證型別需要的任何其他租使用者或組織值。
4. 取得存取權杖
實作針對您的認證型別記錄的OAuth流程。
聯結器必須：
- 使用設定的OAuth憑證進行驗證。
- 請求串流SDK整合所需的範圍。
- 將存取權杖儲存在記憶體或其他安全位置。
- 根據Token存留期重新整理或重新取得Token。
- 請避免記錄權杖或使用者端密碼。
5. 將存取權杖新增至請求
在聯結器傳送的請求中包含存取權杖作為持有人權杖：
Authorization: Bearer {ACCESS_TOKEN}
所有請求均使用HTTPS。
6. 處理權杖失敗
聯結器應偵測並處理驗證失敗，包括：
- 缺少存取權杖。
- 存取權杖已過期。
- 無效的使用者端認證。
- 範圍不足。
- 已撤銷或已停用的認證。
權杖過期時，請使用紀錄的OAuth流程取得新權杖，並僅在作業可安全重試時重試。
設定以HMAC為基礎的驗證
1. 設定共用機密
建立或取得聯結器所需的共用機密，並在聯結器或webhook設定中加以設定。
密碼必須是：
- 安全儲存。
- 可在執行階段供簽署程式碼使用。
- 已從原始檔控制和記錄檔中排除。
- 根據您的安全性原則輪換。
2. 序列化事件
計算簽章前先序列化事件。
簽章必須從聯結器在要求內文中傳送的相同序列化訊息中計算。
serializedMessage = serialize(event)
請勿從事件的一個表示法計算簽章，並傳送另一個表示法。 變更空白、屬性順序、逸出、編碼或行尾可能會導致簽名驗證失敗。
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 | |
|---|---|
| 測試 | 預期結果 |
| 使用有效的存取Token進行請求 | 接受並處理事件。 |
| 沒有存取權杖的請求 | 請求被拒絕。 |
| 使用過期的存取Token進行請求 | 請求被拒絕，或聯結器取得新權杖並根據其重試原則重試。 |
| 使用無效存取權杖的請求 | 請求被拒絕。 |
| 要求範圍不足 | 請求被拒絕。 |
| 認證輪換後要求 | 聯結器已成功取得並使用新認證。 |
| 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和使用者端密碼屬於已設定的認證。
- 要求的範圍正確。
- 存取權杖尚未過期。
- 權杖會使用「授權：持有人」配置傳送。
- 聯結器使用正確的權杖端點。
- 此認證可存取必要的API或產品設定檔。
HMAC驗證失敗
檢查下列專案：
x-hmac-sha256標頭已存在。- 標頭名稱和值的拼寫正確。
- 聯結器使用正確的密碼。
- 簽名是使用HMAC-SHA256計算。
- 簽章是以完全序列化的要求內文來計算。
- 計算簽名後，請求內文不會重新格式化。
- 必要的簽名編碼和字母大小寫正確。
- 聯結器在旋轉期間使用正確的目前或上一個密碼。
- 密碼可供執行階段使用，且尚未被截斷或更改。
提交需求
在提交或釋放聯結器之前，請確認下列事項：
- 您的聯結器會對串流獲取API的每個請求使用OAuth 2.0或HMAC型驗證。
- 您已在中測試情境驗證聯結器並記錄結果。
- 您的聯結器會拒絕未驗證及錯誤驗證的請求。
- 您的秘密和權杖未提交至原始檔控制、記錄檔、錯誤訊息或熒幕擷取畫面。
後續步驟
設定驗證並驗證後，繼續測試並提交您的來源。 若要瞭解如何記錄來源的驗證需求，請參閱記錄您的來源（串流SDK）。