文件Experience PlatformExperience 平台概觀

使用API設定及設定客戶自控金鑰

Last update: Tue Nov 19 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主題：
  • API

建立對象：

  • 開發人員

本文介紹在Adobe Experience Platform中使用API啟用客戶自控金鑰(CMK)功能的程式。 有關如何使用UI完成此程式的說明，請參閱UI CMK設定檔案。

先決條件

若要在Adobe Experience Platform中檢視並瀏覽加密區段，您必須已建立角色，並已將管理客戶管理的金鑰許可權指派給該角色。 任何擁有管理客戶管理的金鑰許可權的使用者都可以為其組織啟用CMK。

有關在Experience Platform中指派角色和許可權的詳細資訊，請參閱設定許可權檔案。

若要啟用CMK，您的Azure 金鑰儲存庫必須使用下列設定來設定：

設定CMK應用程式 register-app

在您設定金鑰儲存庫後，下一步是註冊將連結至您Azure租使用者的CMK應用程式。

快速入門

註冊CMK應用程式時，您必須呼叫平台API。 如需有關如何收集進行這些呼叫所需的驗證標頭的詳細資訊，請參閱平台API驗證指南。

雖然驗證指南提供如何為必要的x-api-key請求標頭產生您自己的唯一值的指示，但本指南中的所有API作業都使用靜態值acp_provisioning。 不過，您仍必須提供您自己的{ACCESS_TOKEN}和{ORG_ID}值。

在本指南中顯示的所有API呼叫中，platform.adobe.io會作為根路徑，其預設值為VA7區域。 如果貴組織使用不同的地區，platform後面必須加上破折號和指派給貴組織的地區代碼： NLD2為nld2或AUS5為aus5 （例如： platform-aus5.adobe.io）。 如果您不知道您組織的區域，請聯絡您的系統管理員。

擷取驗證URL fetch-authentication-url

若要開始註冊程式，請向應用程式註冊端點發出GET請求，以擷取組織所需的驗證URL。

要求

curl -X GET \
  https://platform.adobe.io/data/infrastructure/manager/byok/app-registration \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: acp_provisioning' \
  -H 'x-gw-ims-org-id: {ORG_ID}'

回應

成功的回應傳回包含驗證URL的applicationRedirectUrl屬性。

{
    "id": "byok",
    "name": "acpebae9422Caepcmkmultitenantapp",
    "applicationUri": "https://adobe.com/acpebae9422Caepcmkmultitenantapp",
    "applicationId": "e463a445-c6ac-4ca2-b36a-b5146fcf6a52",
    "applicationRedirectUrl": "https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&client_id=e463a445-c6ac-4ca2-b36a-b5146fcf6a52&redirect_uri=https://adobe.com/acpebae9422Caepcmkmultitenantapp&scope=user.read"
}

將applicationRedirectUrl位址複製並貼到瀏覽器中，以開啟驗證對話方塊。 選取​ Accept ​將CMK應用程式服務主體新增至您的Azure租使用者。

反白顯示接受的Microsoft許可權要求對話方塊。

將CMK應用程式指派給角色 assign-to-role

完成驗證程式後，請導覽回您的Azure金鑰儲存庫，並在左側導覽中選取​ Access control。 從這裡，依次選取​ Add ​和​ Add role assignment。

反白顯示Add和Add role assignment的Microsoft Azure儀表板。

下一個畫面會提示您選擇此指派的角色。 選取​ Key Vault Crypto Service Encryption User ​再選取​ Next ​以繼續。

NOTE
如果您有Managed-HSM Key Vault層，則必須選取​ Managed HSM Crypto Service Encryption User ​使用者角色。

反白顯示Key Vault Crypto Service Encryption User的Microsoft Azure儀表板。

在下一個畫面中，選擇​ Select members ​以在右側邊欄中開啟對話方塊。 使用搜尋列來尋找CMK應用程式的服務主體，並從清單中選取它。 完成後，選取​ Save。

NOTE
如果您在清單中找不到您的應用程式，則表示您的服務主體尚未被租使用者接受。 為確保您擁有正確的許可權，請與您的Azure管理員或代表合作。

在Experience Platform上啟用加密金鑰設定 send-to-adobe

在Azure上安裝CMK應用程式後，您可以將加密金鑰識別碼傳送給Adobe。 在左側導覽中選取​ Keys，然後選取您要傳送的金鑰名稱。

反白顯示Keys物件和金鑰名稱的Microsoft Azure儀表板。

選取金鑰的最新版本，其詳細資訊頁面就會顯示。 從這裡，您可以選擇設定金鑰的允許操作。

IMPORTANT
金鑰允許的最小必要操作為​ Wrap Key ​和​ Unwrap Key ​許可權。 您可視需要包含Encrypt、Decrypt、Sign和Verify。

金鑰識別碼 ​欄位會顯示金鑰的URI識別碼。 複製此URI值以用於下一個步驟。

Microsoft Azure儀表板金鑰詳細資訊，其中Permitted operations和復本金鑰URL區段強調顯示。

取得金鑰儲存庫URI後，您可以使用POST請求將其傳送到CMK設定端點。

NOTE
只有金鑰儲存庫和金鑰名稱與Adobe一起儲存，而不是金鑰版本。

要求

將金鑰儲存庫URI傳送至CMK設定端點的範例要求。
code language-shell 
curl -X POST \
  https://platform.adobe.io/data/infrastructure/manager/customer/config \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: acp_provisioning' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -d '{
        "name": "Config1",
        "type": "BYOK_CONFIG",
        "imsOrgId": "{ORG_ID}",
        "configData": {
          "providerType": "AZURE_KEYVAULT",
          "keyVaultKeyIdentifier": "https://adobecmkexample.vault.azure.net/keys/adobeCMK-key/7c1d50lo28234cc895534c00d7eb4eb4"
        }
      }'
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
屬性 說明
name 設定的名稱。 請確定您記得這個值，因為在之後的步驟中需要檢查組態狀態。 值區分大小寫。
type 設定型別。 必須設定為BYOK_CONFIG。
imsOrgId 您的組織ID。 此ID的值必須與x-gw-ims-org-id標頭下提供的值相同。
configData

此屬性包含有關設定的下列詳細資訊：

  • providerType：必須設定為AZURE_KEYVAULT。
  • keyVaultKeyIdentifier：您複製early的金鑰儲存庫URI。

回應

成功的回應會傳回設定工作的詳細資訊。
code language-json 
{
  "id": "4df7886b-a122-4391-880b-47888d5c5b92",
  "config": {
    "configData": {
      "keyVaultUri": "https://adobecmkexample.vault.azure.net",
      "keyVaultKeyIdentifier": "https://adobecmkexample.vault.azure.net/keys/adobeCMK-key/7c1d50lo28234cc895534c00d7eb4eb4",
      "keyVersion": "7c1d50lo28234cc895534c00d7eb4eb4",
      "keyName": "Config1",
      "providerType": "AZURE_KEYVAULT"
    },
    "name": "acpcf978863Aaepcmkmultitenantapp",
    "type": "BYOK_CONFIG",
    "imsOrgId": "{ORG_ID}",
    "status": "NEW"
  },
  "status": "CREATED"
}

工作應在幾分鐘內完成處理。

驗證設定的狀態 check-status

若要檢查設定要求的狀態，您可以提出GET要求。

要求

您必須將您要檢查之設定的name附加至路徑（以下範例中為config1），並包含設定為BYOK_CONFIG的configType查詢引數。

檢查設定要求狀態的範例要求。
code language-shell 
curl -X GET \
  https://platform.adobe.io/data/infrastructure/manager/customer/config/config1?configType=BYOK_CONFIG \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: acp_provisioning' \
  -H 'x-gw-ims-org-id: {ORG_ID}'

回應

成功的回應會傳回工作的狀態。
code language-json 
{
  "name": "acpcf978863Aaepcmkmultitenantapp",
  "type": "BYOK_CONFIG",
  "status": "COMPLETED",
  "configData": {
    "keyVaultUri": "https://adobecmkexample.vault.azure.net",
    "keyVaultKeyIdentifier": "https://adobecmkexample.vault.azure.net/keys/adobeCMK-key/7c1d50lo28234cc895534c00d7eb4eb4",
    "keyVersion": "7c1d50lo28234cc895534c00d7eb4eb4",
    "keyName": "Config1",
    "providerType": "AZURE_KEYVAULT"
  },
  "imsOrgId": "{ORG_ID}",
  "subscriptionId": "cf978863-7325-47b1-8fd9-554b9fdb6c36",
  "id": "4df7886b-a122-4391-880b-47888d5c5b92",
  "rowType": "BYOK_KEY"
}

status屬性可以有以下含義的四個值之一：

  1. RUNNING：驗證Platform可以存取金鑰和金鑰儲存庫。
  2. UPDATE_EXISTING_RESOURCES：系統正在將金鑰儲存庫和金鑰名稱新增至貴組織所有沙箱的資料存放區。
  3. COMPLETED：金鑰儲存庫和金鑰名稱已成功新增至資料存放區。
  4. FAILED：發生問題，主要與金鑰、金鑰儲存庫或多租使用者應用程式設定有關。

後續步驟

完成上述步驟，您已成功為組織啟用CMK。 現在將使用Azure金鑰儲存庫中的金鑰加密和解密擷取到主要資料存放區的資料。 若要進一步瞭解Adobe Experience Platform中的資料加密，請參閱加密檔案。

recommendation-more-help
5741548a-2e07-44b3-9157-9c181502d0c5