|
| 1 | +--- |
| 2 | +title: Configure cross-tenant customer-managed keys for your Azure Cosmos DB account with Azure Key Vault (preview) |
| 3 | +description: Learn how to configure encryption with customer-managed keys for Azure Cosmos DB using an Azure Key Vault that resides in a different tenant. |
| 4 | +author: seesharprun |
| 5 | +ms.author: sidandrews |
| 6 | +ms.service: cosmos-db |
| 7 | +ms.topic: how-to |
| 8 | +ms.date: 09/27/2022 |
| 9 | +ms.reviewer: turao |
| 10 | +--- |
| 11 | + |
| 12 | +# Configure cross-tenant customer-managed keys for your Azure Cosmos DB account with Azure Key Vault (preview) |
| 13 | + |
| 14 | +[!INCLUDE[appliesto-all-apis](includes/appliesto-all-apis.md)] |
| 15 | + |
| 16 | +Data stored in your Azure Cosmos DB account is automatically and seamlessly encrypted with service-managed keys managed by Microsoft. However, you can choose to add a second layer of encryption with keys you manage. These keys are known as customer-managed keys (or CMK). Customer-managed keys are stored in an Azure Key Vault instance. |
| 17 | + |
| 18 | +This article walks through how to configure encryption with customer-managed keys at the time that you create an Azure Cosmos DB account. In this example cross-tenant scenario, the Azure Cosmos DB account resides in a tenant managed by an Independent Software Vendor (ISV) referred to as the service provider. The key used for encryption of the Azure Cosmos DB account resides in a key vault in a different tenant that is managed by the customer. |
| 19 | + |
| 20 | +## About the preview |
| 21 | + |
| 22 | +To use the preview, you must register for the Azure Active Directory federated client identity feature in the service provider's tenant. Follow these instructions to register with Azure PowerShell or Azure CLI: |
| 23 | + |
| 24 | +### [Portal](#tab/azure-portal) |
| 25 | + |
| 26 | +Not yet supported. |
| 27 | + |
| 28 | +### [PowerShell](#tab/azure-powershell) |
| 29 | + |
| 30 | +To register with Azure PowerShell, use the [Register-AzProviderFeature](/powershell/module/az.resources/register-azproviderfeature) cmdlet. |
| 31 | + |
| 32 | +```azurepowershell |
| 33 | +$parameters = @{ |
| 34 | + FeatureName = "FederatedClientIdentity" |
| 35 | + ProviderNamespace = "Microsoft.Storage" |
| 36 | +} |
| 37 | +Register-AzProviderFeature @parameters |
| 38 | +``` |
| 39 | + |
| 40 | +To check the status of your registration, use [Get-AzProviderFeature](/powershell/module/az.resources/get-azproviderfeature). |
| 41 | + |
| 42 | +```azurepowershell |
| 43 | +$parameters = @{ |
| 44 | + FeatureName = "FederatedClientIdentity" |
| 45 | + ProviderNamespace = "Microsoft.Storage" |
| 46 | +} |
| 47 | +Get-AzProviderFeature @parameters |
| 48 | +``` |
| 49 | + |
| 50 | +After your registration is approved, you must re-register the Azure Storage resource provider. To re-register the resource provider with PowerShell, use [Register-AzResourceProvider](/powershell/module/az.resources/register-azresourceprovider). |
| 51 | + |
| 52 | +```azurepowershell |
| 53 | +$parameters = @{ |
| 54 | + ProviderNamespace = "Microsoft.Storage" |
| 55 | +} |
| 56 | +Register-AzResourceProvider @parameters |
| 57 | +``` |
| 58 | + |
| 59 | +### [Azure CLI](#tab/azure-cli) |
| 60 | + |
| 61 | +To register with Azure CLI, use the [az feature register](/cli/azure/feature#az-feature-register) command. |
| 62 | + |
| 63 | +```azurecli |
| 64 | +az feature register \ |
| 65 | + --name FederatedClientIdentity \ |
| 66 | + --namespace Microsoft.Storage |
| 67 | +``` |
| 68 | + |
| 69 | +To check the status of your registration with Azure CLI, use [az feature show](/cli/azure/feature#az-feature-show). |
| 70 | + |
| 71 | +```azurecli |
| 72 | +az feature show \ |
| 73 | + --name FederatedClientIdentity \ |
| 74 | + --namespace Microsoft.Storage |
| 75 | +``` |
| 76 | + |
| 77 | +After your registration is approved, you must re-register the Azure Storage resource provider. To re-register the resource provider with Azure CLI, use [az provider register](/cli/azure/provider#az-provider-register). |
| 78 | + |
| 79 | +```azurecli |
| 80 | +az provider register \ |
| 81 | + --namespace 'Microsoft.Storage' |
| 82 | +``` |
| 83 | + |
| 84 | +--- |
| 85 | + |
| 86 | +> [!IMPORTANT] |
| 87 | +> Using cross-tenant customer-managed keys with Azure Cosmos DB encryption is currently in PREVIEW. See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability. |
| 88 | +
|
| 89 | +[!INCLUDE [active-directory-msi-cross-tenant-cmk-overview](../../includes/active-directory-msi-cross-tenant-cmk-overview.md)] |
| 90 | + |
| 91 | +[!INCLUDE [active-directory-msi-cross-tenant-cmk-create-identities-authorize-key-vault](../../includes/active-directory-msi-cross-tenant-cmk-create-identities-authorize-key-vault.md)] |
| 92 | + |
| 93 | +## Create a new Azure Cosmos DB account encrypted with a key from a different tenant |
| 94 | + |
| 95 | +> [!NOTE] |
| 96 | +> Cross-tenant customer-managed keys with Azure Cosmos DB encryption PREVIEW is not compatible with Continuous Backup or Azure Synapse link features. |
| 97 | +
|
| 98 | +Up to this point, you've configured the multi-tenant application on the service provider's tenant. You've also installed the application on the customer's tenant and configured the key vault and key on the customer's tenant. Next you can create an Azure Cosmos DB account on the service provider's tenant and configure customer-managed keys with the key from the customer's tenant. |
| 99 | + |
| 100 | +You must use an existing user-assigned managed identity to authorize access to the key vault when you configure customer-managed keys while creating the Azure Cosmos DB account. The user-assigned managed identity must have appropriate permissions to access the key vault. As the key vault is on another tenant, we'll use the multi tenant application created previously and register the user assigned managed identity as a federated identity of this multi-tenant application. For more information, see the [Phase 3 - The service provider encrypts data in an Azure resource using the customer-managed key](#phase-3---the-service-provider-encrypts-data-in-an-azure-resource-using-the-customer-managed-key) section of this article. |
| 101 | + |
| 102 | +Whenever a new version of the key is available in the key vault, it will be automatically updated on the Azure Cosmos DB account. |
| 103 | + |
| 104 | +## Using Azure Resource Manager JSON templates |
| 105 | + |
| 106 | +Deploy an ARM template with the following specific parameters: |
| 107 | + |
| 108 | +| Parameter | Description | Example value | |
| 109 | +| --- | --- | --- | |
| 110 | +| `keyVaultKeyUri` | Identifier of the customer-managed key residing in the service provider's key vault. | `https://my-vault.vault.azure.com/keys/my-key` | |
| 111 | +| `identity` | Object specifying that the managed identity should be assigned to the Azure Cosmos DB account. | `"identity":{"type":"UserAssigned","userAssignedIdentities":{"/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-identity":{}}}` | |
| 112 | +| `defaultIdentity` | Combination of the resource ID of the managed identity and the application ID of the multi-tenant Azure Active Directory application. | `UserAssignedIdentity=/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-identity&FederatedClientId=11111111-1111-1111-1111-111111111111` | |
| 113 | + |
| 114 | +Here's an example of a template segment with the three parameters configured: |
| 115 | + |
| 116 | +```json |
| 117 | +{ |
| 118 | + "kind": "GlobalDocumentDB", |
| 119 | + "location": "East US 2", |
| 120 | + "identity": { |
| 121 | + "type": "UserAssigned", |
| 122 | + "userAssignedIdentities": { |
| 123 | + "/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-identity": {} |
| 124 | + } |
| 125 | + }, |
| 126 | + "properties": { |
| 127 | + "locations": [ |
| 128 | + { |
| 129 | + "locationName": "East US 2", |
| 130 | + "failoverPriority": 0, |
| 131 | + "isZoneRedundant": false |
| 132 | + } |
| 133 | + ], |
| 134 | + "databaseAccountOfferType": "Standard", |
| 135 | + "keyVaultKeyUri": "https://my-vault.vault.azure.com/keys/my-key", |
| 136 | + "defaultIdentity": "UserAssignedIdentity=/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-identity&FederatedClientId=11111111-1111-1111-1111-111111111111" |
| 137 | + } |
| 138 | +} |
| 139 | +``` |
| 140 | + |
| 141 | +> [!IMPORTANT] |
| 142 | +> This feature is not yet supported in Azure PowerShell, Azure CLI, or the Azure portal. |
| 143 | +
|
| 144 | +You can't configure customer-managed keys with a specific version of the key version when you create a new Azure Cosmos DB account. The key itself must be passed with no versions and no trailing backslashes. |
| 145 | + |
| 146 | +To Revoke or Disable customer-managed keys, see [configure customer-managed keys for your Azure Cosmos DB account with Azure Key Vault](how-to-setup-customer-managed-keys.md) |
| 147 | + |
| 148 | +## See also |
| 149 | + |
| 150 | +- [Configure customer-managed keys for your Azure Cosmos account with Azure Key Vault](how-to-setup-cmk.md) |
0 commit comments