Setup and configure customer-managed keys using the API
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 register-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 fetch-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.
Assign the CMK app to a role assign-to-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 next screen prompts you to choose a role for this assignment. Select Key Vault Crypto Service Encryption User before selecting Next to continue.
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.
Enable the encryption key configuration on Experience Platform send-to-adobe
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.
Select the latest version of the key and its details page appears. From here, you can optionally configure the permitted operations for the key.
The Key Identifier field displays the URI identifier for the key. Copy this URI value for use in the next step.
Once you have obtained the key vault URI, you can send it using a POST request to the CMK configuration endpoint.
Request
| code language-shell |
|---|
|
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 | |
|---|---|
| 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:
|
Response
| code language-json |
|---|
|
The job should complete processing within a few minutes.
Verify the configuration’s status check-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.
| code language-shell |
|---|
|
Response
| code language-json |
|---|
|
The status attribute can have one of four values with the following meanings:
RUNNING: Validates that Platform can access the key and key vault.UPDATE_EXISTING_RESOURCES: The system is adding the key vault and key name to the datastores across all sandboxes in your organization.COMPLETED: 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. To learn more about data encryption in Adobe Experience Platform, see the encryption documentation.