Setup and configure customer-managed keys using the API

Last update: 2023-09-29
  • Created for:
  • Developer
    User
    Admin
    Leader

This document covers the process for enabling the customer-managed keys (CMK) feature in Adobe Experience Platform using the API. For instructions on how to complete this process using the UI, refer to the UI CMK setup document.

Prerequisites

To view and visit the Encryption section in Adobe Experience Platform, you must have created a role and assigned the Manage Customer Managed Key permission to that role. Any user that has the Manage Customer Managed Key permission can enable CMK for their organization.

For more information on assigning roles and permissions in Experience Platform, refer to the configure permissions documentation.

To enable CMK, your Azure Key Vault must be configured with the following settings:

Set up the CMK app

After you have your key vault configured, the next step is to register for the CMK application that will link to your Azure tenant.

Getting started

Registering the CMK app requires you to make calls to Platform APIs. For details on how to gather the required authentication headers to make these calls, see the Platform API authentication guide.

While the authentication guide provides instructions on how to generate your own unique value for the required x-api-key request header, all API operations in this guide use the static value acp_provisioning instead. You must still provide your own values for {ACCESS_TOKEN} and {ORG_ID}, however.

In all API calls shown in this guide, platform.adobe.io is used as the root path, which defaults to the VA7 region. If your organization uses a different region, platform must be followed by a dash and the region code assigned to your organization: nld2 for NLD2 or aus5 for AUS5 (for example: platform-aus5.adobe.io). If you do not know your organization’s region, contact your system administrator.

Fetch an authentication URL

To start the registration process, make a GET request to the app registration endpoint to fetch the required authentication URL for your organization.

Request

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}'

Response

A successful response returns an applicationRedirectUrl property, containing the authentication URL.

{
    "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"
}

Copy and paste the applicationRedirectUrl address into a browser to open an authentication dialog. Select Accept to add the CMK app service principal to your Azure tenant.

A Microsoft permission request dialog with Accept highlighted.

Assign the CMK app to a role

After completing the authentication process, navigate back to your Azure Key Vault and select Access control in the left navigation. From here, select Add followed by Add role assignment.

The Microsoft Azure dashboard with Add and Add role assignment highlighted.

The next screen prompts you to choose a role for this assignment. Select Key Vault Crypto Service Encryption User before selecting Next to continue.

The Microsoft Azure dashboard with the Key Vault Crypto Service Encryption User highlighted.

On the next screen, choose Select members to open a dialog in the right rail. Use the search bar to locate the service principal for the CMK application and select it from the list. When finished, select Save.

NOTE

If you cannot find your application in the list, then your service principal has not been accepted into your tenant. To ensure that you have correct privileges, work with your Azure administrator or representative.

Enable the encryption key configuration on Experience Platform

After installing the CMK app on Azure, you can send your encryption key identifier to Adobe. Select Keys in the left navigation, followed by the name of the key you want to send.

The Microsoft Azure dashboard with the Keys object and the key name highlighted.

Select the latest version of the key and its details page appears. From here, you can optionally configure the permitted operations for the key.

IMPORTANT

The minimum required operations to be permitted for the key are the Wrap Key and Unwrap Key permissions. You can include Encrypt, Decrypt, Sign, and Verify should you want.

The Key Identifier field displays the URI identifier for the key. Copy this URI value for use in the next step.

The Microsoft Azure dashboard Key details with the Permitted operations and the copy key URL sections highlighted.

Once you have obtained the key vault URI, you can send it using a POST request to the CMK configuration endpoint.

NOTE

Only the key vault and key name are stored with Adobe, not the key version.

Request

 A sample request to send key vault URI to the CMK configuration endpoint.
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"
        }
      }'
Property Description
name A name for the configuration. Ensure that you remember this value as it is required to check the configuration’s status at a later step. The value is case-sensitive.
type The configuration type. Must be set to BYOK_CONFIG.
imsOrgId Your organization ID. This ID must be the same value as provided under the x-gw-ims-org-id header.
configData This property contains the following details about the configuration:
  • providerType: Must be set to AZURE_KEYVAULT.
  • keyVaultKeyIdentifier: The key vault URI that you copied earlier.

Response

 The successful response returns the details of the configuration job.
{
  "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"
}

The job should complete processing within a few minutes.

Verify the configuration’s status

To check the status of the configuration request, you can make a GET request.

Request

You must append the name of the configuration you want to check to the path (config1 in the example below) and include a configType query parameter set to BYOK_CONFIG.

 A sample request to check the status of the configuration request.
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}'

Response

 The successful response returns the status of the job.
{
  "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"
}

The status attribute can have one of four values with the following meanings:

  1. RUNNING: Validates that Platform can access the key and key vault.
  2. UPDATE_EXISTING_RESOURCES: The system is adding the key vault and key name to the datastores across all sandboxes in your organization.
  3. COMPLETED: The key vault and key name have successfully been added to the datastores.
  4. FAILED: A problem occurred, primarily related to the key, key vault, or multi-tenant app setup.

Next steps

By completing the above steps, you have successfully enabled CMK for your organization. Data that is ingested into primary data stores will now be encrypted and decrypted using the key(s) in your Azure Key Vault. To learn more about data encryption in Adobe Experience Platform, see the encryption documentation.

On this page