Setup and configure customer-managed keys using the Platform UI

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 Platform using the UI. For instructions on how to complete this process using the API, refer to the API 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 the CMK application that will link to your Azure tenant.

Getting started

To view the Encryption configurations dashboard, select Encryption under the Administration heading of the left navigation sidebar.

The Encryption configuration dashboard with Encryption and the Customer Managed Keys card highlighted.

Select Configure to open the Customer Managed Keys configuration view. This workspace contains all the necessary values to complete the steps described below and perform the integration with your Azure Key vault.

Copy authentication URL

To start the registration process, copy the application authentication URL for your organization from the Customer Managed Keys configuration view and paste it into your Azure environment Key Vault Crypto Service Encryption User. Details on how to assign a role are provided in the next section.

Select the copy icon (The copy icon.) by the Application authentication url.

The Customer Managed Keys configuration view with the Application authentication url section highlighted.

Copy and paste the Application authentication url into a browser to open an authentication dialog. Select Accept to add the CMK app service principal to your Azure tenant. Confirming the authentication redirects you to the Experience Cloud landing page.

A Microsoft permission request dialog with Accept highlighted.

IMPORTANT

If you have multiple Microsoft Azure subscriptions, then you could potentially connect your Platform instance to the wrong key vault. In this situation, you must swap the common section of the application authentication URL name for the CMK directory ID.
Copy the CMK directory ID from the Portal settings, Directories, and Subscriptions page of the Microsoft Azure application
The Microsoft Azure application Portal settings, Directories and Subscriptions page with the Directory ID highlighted.
Next, paste it into your browser address bar.
A Google browser page with the 'common' section of the Application authentication url 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.

You can verify the application by comparing the Application ID provided on the Customer Managed Keys configuration view with the Application ID provided on the Microsoft Azure application overview.

The Customer Managed Keys configuration view with the Application ID highlighted.

All the details necessary to verify Azure tools are included in the Platform UI. This level of granularity is provided as many users wish to uze other Azure tools to enhance their ability to monitor and log these applications access to their key vault. Understanding these identifiers is critical for that purpose and to help Adobe services to access the key.

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, return to the Customer Managed Keys configuration view and enter a descriptive Configuration name. Next, add the Key Identifier taken from the Azure Key details page into the Key vault key identifier and select ** Save**.

The Customer Managed Keys configuration view with the Configuration name and the Key vault key identifier sections highlighted.

You are returned to the Encryption configurations dashboard. The status of the Customer Managed Keys configuration displays as Processing.

The Encryption configurations dashboard with Processing highlighted on the Customer Managed Keys card.

Verify the configuration’s status

Allow a significant amount of time for processing. To check the status of the configuration, return to the Customer Managed Keys configuration view and scroll down to the Configuration status. The progress bar has advanced to step one of three and explains that the system is validating that Platform has access to the key and key vault.

There are four potential statuses of the CMK configuration. They are as follows:

  • Step 1: Validates that Platform has the ability to access the key and key vault.
  • Step 2: The key vault and key name are in the process of being added to all datastores across your organization.
  • Step 3: The key vault and key name have successfully been added to the datastores.
  • 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.

On this page