文档Experience PlatformExperience Platform 概述

使用API设置和配置客户管理的密钥

Last update: Wed Nov 20 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主题：
  • API

创建对象：

  • 开发人员

本文档介绍了使用API在Adobe Experience Platform中启用客户管理的密钥(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：验证平台是否可以访问密钥和密钥保管库。
  2. UPDATE_EXISTING_RESOURCES：系统正在将密钥保管库和密钥名称添加到组织中所有沙盒的数据存储中。
  3. COMPLETED：密钥保管库和密钥名称已成功添加到数据存储。
  4. FAILED：出现问题，主要与密钥、密钥保管库或多租户应用设置有关。

后续步骤

通过完成上述步骤，您已成功为组织启用CMK。 现在，将使用Azure密钥保管库中的密钥对摄取到主数据存储中的数据加密和解密。 要了解有关Adobe Experience Platform中数据加密的更多信息，请参阅加密文档。

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