cmk docs clarifications

deeikele · deeikele · commit 2be151f95378 · 2025-07-30T17:52:11.000-07:00
diff --git a/articles/ai-foundry/concepts/encryption-keys-portal.md b/articles/ai-foundry/concepts/encryption-keys-portal.md
@@ -18,55 +18,50 @@ zone_pivot_groups: project-type
 
 # Customer-managed keys for encryption with Azure AI Foundry
 
-Customer-managed keys (CMKs) in [Azure AI Foundry portal](https://ai.azure.com/?cid=learnDocs) provide enhanced control over the encryption of your data. By using CMKs, you can manage your own encryption keys to add an extra layer of protection and meet compliance requirements more effectively.
+Customer-managed key (CMK) encryption in [Azure AI Foundry](https://ai.azure.com/?cid=learnDocs) provide enhanced control over the encryption of your data. By using CMK, you can manage your own encryption keys to add an extra layer of protection and meet compliance requirements more effectively.
 
 ## About encryption in Azure AI Foundry
 
-Azure AI Foundry is a service in the Microsoft Azure cloud. By default, services use Microsoft-managed encryption keys to encrypt data in transit and at rest.
+Azure AI Foundry is a service in the Microsoft Azure cloud. By default, Azure services use Microsoft-managed encryption keys to encrypt data in transit and at rest.
 
 ::: zone pivot="hub-project"
 
-Azure AI Hub resource takes a dependency on Azure AI Foundry resource as a dependency. Both resources are managed in your Azure subscription. You must configure customer-managed key encryption on both.
-
-*  AI Foundry resources, data is encrypted and decrypted using [FIPS 140-2](https://en.wikipedia.org/wiki/FIPS_140-2) compliant [256-bit AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) encryption. Encryption and decryption are transparent, meaning encryption and access are managed for you. Your data is secure by default and you don't need to modify your code or applications to take advantage of encryption.
+When you use hub-based projects, the Azure AI hub resource acts as gateway to a number of Azure services including Azure AI Hub, Azure Storage account and Azure AI Foundry resource. You must configure customer-managed key encryption on each of these services to use CMK encryption throughout with AI Foundry.
 
 * AI Hub resources, and [!INCLUDE [hub](../includes/hub-project-name.md)] resources are implementations of the Azure Machine Learning workspace and encrypt data in transit and at rest. For details, see [Data encryption with Azure Machine Learning](../../machine-learning/concept-data-encryption.md). 
 
-::: zone-end
-
-::: zone pivot="fdp-project"
-
-When an Azure AI Foundry resource is created, you can update from Microsoft-managed keys to customer-managed keys. However, you cannot switch back from customer-managed keys to Microsoft-managed keys.
+*  AI Foundry resources data is encrypted and decrypted using [FIPS 140-2](https://en.wikipedia.org/wiki/FIPS_140-2) compliant [256-bit AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) encryption. Encryption and decryption are transparent, meaning encryption and access are managed for you. Your data is secure by default and you don't need to modify your code or applications to take advantage of encryption.
 
-Data is encrypted and decrypted using [FIPS 140-2](https://en.wikipedia.org/wiki/FIPS_140-2) compliant [256-bit AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) encryption. Encryption and decryption are transparent, meaning encryption and access are managed for you. Your data is secure by default and you don't need to modify your code or applications to take advantage of encryption.
+* Azure Storage accounts are used to store data uploaded when using AI Foundry portal and when using Foundry tools. For details on how to setup CMK encryption, see [Customer-managed keys for Azure Storage encryption](/azure/storage/common/customer-managed-keys-overview). 
 
 ::: zone-end
 
-## Storage of encrypted data when using customer-managed keys
+::: zone pivot="fdp-project"
 
-Customer-managed key encryption can be enabled during resource creation through the Azure portal or template options. The encrypted data is stored service-side on Microsoft-managed resources using your encryption key. 
+On your Azure AI Foundry resource data is encrypted and decrypted using [FIPS 140-2](https://en.wikipedia.org/wiki/FIPS_140-2) compliant [256-bit AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) encryption. Encryption and decryption are transparent, meaning encryption and access are managed for you. Your data is secure by default and you don't need to modify your code or applications to take advantage of encryption.
 
-> [!NOTE]
-> Due to the dedicated hosting model for certain services when using customer-managed key encrypted data, additional charges may apply.
+::: zone-end
 
-> [!NOTE]
-> When you use server-side encryption, Azure charges will continue to accrue during the soft delete retention period.
+> [!IMPORTANT]
+> If you [connect AI Foundry with other Azure tools](../how-to/connections-add.md), note that CMK encryption must be configured on every top level Azure resource.
 
 ::: zone pivot="hub-project"
+## Data storage options with Azure AI Hub CMK encryption
 
-## Service-side storage of encrypted data when using customer-managed keys with AI hub
+Two architecture options are available when using customer-managed keys with Azure AI Hubs:
 
-Two architecture options are available when using customer-managed keys:
+* **(Recommended) Encrypted data is stored in Microsoft subscription**
 
-* **Encrypted data is stored in Microsoft subscription (recommended)**
+  Data is stored service-side on Microsoft-managed resources instead of in managed resources in your subscription. Metadata is stored in multitenant resources using document-level CMK encryption. An Azure AI Search instance is hosted in the Microsoft-subscription per customer, for each hub, in order to provide data isolation of encrypted data. It is recommended to pick this option for any new deployments.
 
-  Data is stored service-side on Microsoft-managed resources instead of in managed resources in your subscription. Metadata is stored in multitenant resources using document-level CMK encryption. An Azure AI Search instance is hosted on the Microsoft-side per customer, and for each hub.
+* **(Legacy) Encrypted data is stored in your subscription** 
 
-* **Encrypted data is stored in your subscription** 
+  Traditionally in Azure Machine Learning platform (which AI Hub resource is built on), data is stored in your subscription using a Microsoft-managed resource group that includes an Azure Storage account, Azure Cosmos DB resource and Azure AI Search. The configuration of these resources cannot be modified. Changes to its configurations are not supported. 
 
-   Data is stored in your subscription using a Microsoft-managed resource group that includes an Azure Storage account, Azure Cosmos DB resource and Azure AI Search. The configuration of these resources cannot be modified. Changes to its configurations are not supported. 
+  > [!IMPORTANT]
+  > This option is available for backwards compatibility, and is not recommended for new workloads.
 
-   All projects using the same hub store data on the resources in a managed resource group identified by the name `azureml-rg-hubworkspacename_GUID`. Projects use Microsoft Entra ID authentication when interacting with these resources. If your hub has a private link endpoint, network access to the managed resources is restricted. The managed resource group is deleted, when the hub is deleted. 
+  All projects using the same hub store data on the resources in a managed resource group identified by the name `azureml-rg-hubworkspacename_GUID`. Projects use Microsoft Entra ID authentication when interacting with these resources. If your hub has a private link endpoint, network access to the managed resources is restricted. The managed resource group is deleted, when the hub is deleted. 
 
   The following data is stored on the managed resources.
 
@@ -76,33 +71,17 @@ Two architecture options are available when using customer-managed keys:
   |Azure AI Search|Stores indices that are used to help query your Azure AI Foundry content.|An index based off your model deployment names|
   |Azure Storage Account|Stores instructions for how customization tasks are orchestrated|JSON representation of flows you create in [Azure AI Foundry portal](https://ai.azure.com/?cid=learnDocs)|
 
-
 ::: zone-end
 
 ## Use customer-managed keys with Azure Key Vault
 
-::: zone pivot="fdp-project"
-
-You must use Azure Key Vault to store your customer-managed keys. You can either create your own keys and store them in a key vault, or you can use the Azure Key Vault APIs to generate keys. The Azure AI Foundry resource and the key vault must be in the same region and in the same Microsoft Entra tenant, but they can be in different subscriptions. For more information about Azure Key Vault, see [What is Azure Key Vault?](/azure/key-vault/general/overview).
+You must use Azure Key Vault to store your customer-managed keys. You can either create your own keys and store them in a key vault, or you can use the Azure Key Vault APIs to generate keys. Your Azure resources and the Azure Key vault resources must be in the same region and in the same Microsoft Entra tenant, but they can be in different subscriptions. For more information about Azure Key Vault, see [What is Azure Key Vault?](/azure/key-vault/general/overview).
 
 - You must enable both the **Soft Delete** and **Do Not Purge** properties on the key vault.
 - If you use the [Key Vault firewall](/azure/key-vault/general/access-behind-firewall), you must allow trusted Microsoft services to access the key vault.
 - You must grant your [!INCLUDE [fdp](../includes/fdp-project-name.md)] system-assigned managed identity the following permissions on your key vault: *get key*, *wrap key*, *unwrap key*.
 - Only RSA and RSA-HSM keys of size 2048 are supported. For more information about keys, see **Key Vault keys** in [About Azure Key Vault keys, secrets, and certificates](/azure/key-vault/general/about-keys-secrets-certificates).
 
-::: zone-end
-
-::: zone pivot="hub-project"
-
-You must use Azure Key Vault to store your customer-managed keys. You can either create your own keys and store them in a key vault, or you can use the Azure Key Vault APIs to generate keys. The Azure AI services resource and the key vault must be in the same region and in the same Microsoft Entra tenant, but they can be in different subscriptions. For more information about Azure Key Vault, see [What is Azure Key Vault?](/azure/key-vault/general/overview).
-
-To enable customer-managed keys, the key vault containing your keys must meet these requirements:
-
-- You must enable both the **Soft Delete** and **Do Not Purge** properties on the key vault.
-- If you use the [Key Vault firewall](/azure/key-vault/general/access-behind-firewall), you must allow trusted Microsoft services to access the key vault.
-- You must grant your hub and Azure AI Foundry resource's system-assigned managed identity the following permissions on your key vault: *get key*, *wrap key*, *unwrap key*.
-- Only RSA and RSA-HSM keys of size 2048 are supported. For more information about keys, see **Key Vault keys** in [About Azure Key Vault keys, secrets, and certificates](/azure/key-vault/general/about-keys-secrets-certificates).
-
 ### Enable your Azure AI Foundry resource's managed identity
 
 Managed identity must be enabled as a prerequisite for using customer-managed keys.
@@ -112,13 +91,11 @@ Managed identity must be enabled as a prerequisite for using customer-managed ke
 1. Switch the system-assigned managed identity status to **On**.
 1. Save your changes, and confirm that you want to enable the system-assigned managed identity.
 
-::: zone-end
-
 ## Enable customer-managed keys
 
 ::: zone pivot="fdp-project"
 
-Customer-managed key encryption is configured via Azure portal in a similar way for each Azure resource:
+Customer-managed key encryption is configured via Azure portal (or alternatively infrastructure-as-code options) in a similar way for each Azure resource:
 
 > [!IMPORTANT]
 > The Azure Key Vault used for encryption **must be in the same resource group** as the AI Foundry project. Key Vaults in other resource groups are not currently supported by the deployment wizards or project configuration workflows.
@@ -134,17 +111,13 @@ Customer-managed key encryption is configured via Azure portal in a similar way
 
 ::: zone pivot="hub-project"
 
-Azure AI Foundry builds on hub as implementation of Azure Machine Learning workspace, Azure AI Services, and lets you connect with other resources in Azure. You must set encryption specifically on each resource.
+Customer-managed key encryption is configured via Azure portal (or alternatively infrastructure-as-code options) in a similar way for each Azure resource:
 
-Customer-managed key encryption is configured via Azure portal in a similar way for each Azure resource:
 1. Create a new Azure resource in Azure portal.
 1. Under the encryption tab, select your encryption key.
+1. For Azure AI Hub, check or uncheck 'Service-side encryption' to select your prefered data storage option. Service-side encryption is recommended for any new workload.
 
-    :::image type="content" source="../../machine-learning/media/concept-customer-managed-keys/cmk-service-side-encryption.png" alt-text="Screenshot of the encryption tab with the option for service side encryption selected." lightbox="../../machine-learning/media/concept-customer-managed-keys/cmk-service-side-encryption.png":::
-
-Alternatively, use infrastructure-as-code options for automation. Example Bicep templates for Azure AI Foundry are available on the Azure Quickstart repo:
-1. [CMK encryption for hub](https://github.com/Azure/azure-quickstart-templates/tree/master/quickstarts/microsoft.machinelearningservices/aifoundry-cmk).
-1. [Service-side CMK encryption preview for hub](https://github.com/azure/azure-quickstart-templates/tree/master/quickstarts/microsoft.machinelearningservices/aistudio-cmk-service-side-encryption).
+   :::image type="content" source="../../machine-learning/media/concept-customer-managed-keys/cmk-service-side-encryption.png" alt-text="Screenshot of the encryption tab with the option for service side encryption selected." lightbox="../../machine-learning/media/concept-customer-managed-keys/cmk-service-side-encryption.png":::
 
 ::: zone-end
 
@@ -176,16 +149,29 @@ How to Rotate Encryption Keys
 
 * The service will begin using the new key for encryption of newly stored data. Existing data remains encrypted with the previous key unless reprocessed.
 
+## Additional Azure cost when using customer-managed keys
+
+When using customer-managed keys, generally your data is stored using document-level encryption in Microsoft-managed storage components. To ensure your data can be stored in isolation and encrypted using your keys, certain backend Azure services used by Azure AI Foundry must be hosted in a dedicated manner per AI Foundry resource in combination with CMK encryption. Additional charges apply when using CMK to accomodate this dedicated hosting model. These charges will show in Azure Cost management as sub line items under your Azure AI Foundry resource.
+
 ## Limitations
 
 * The customer-managed key for encryption can only be updated to keys in the same Azure Key Vault instance.
+* Azure OpenAI assistants service does not support CMK encryption.
 * While project sub-resources exist, you can't switch AI Foundry resources from Customer-managed keys to Microsoft managed keys.
 * [Azure AI Foundry Customer-Managed Key Request Form](https://aka.ms/cogsvc-cmk) is required to use customer-managed keys in combination with Azure Speech and Content Moderator capabilities.
 * [Azure AI Foundry Customer-Managed Key Request Form](https://aka.ms/cogsvc-cmk) is required for Speech and Content Moderator.
 * If your AI Foundry resource is in a soft-deleted state, any additional Azure charges will continue to accrue during the soft delete retention period.
 
-## Learn more
+## Next steps
+
+Learn more:
 
 * [Customer-managed key encryption](../concepts/encryption-keys-portal.md)
 * [Disable local auth](../how-to/disable-local-auth.md)
 * [What is Azure Key Vault](/azure/key-vault/general/overview)?
+
+Reference infrastructure-as-code templates:
+
+* [Bicep sample for CMK encyption for Azure AI Foundry resource](https://github.com/azure-ai-foundry/foundry-samples/tree/main/samples/microsoft/infrastructure-setup/30-customer-managed-keys)
+* [Bicep sample for CMK encyption for Azure AI Foundry resource and Agent service standard setup](https://github.com/azure-ai-foundry/foundry-samples/tree/main/samples/microsoft/infrastructure-setup/31-customer-managed-keys-standard-agent)
+* [Bicep sample for CMK encryption for Azure AI hub](https://github.com/azure/azure-quickstart-templates/tree/master/quickstarts/microsoft.machinelearningservices/aistudio-cmk-service-side-encryption).
