|
| 1 | +--- |
| 2 | +title: Configure cross-tenant customer-managed keys for an existing storage account (preview) |
| 3 | +titleSuffix: Azure Storage |
| 4 | +description: Learn how to configure Azure Storage encryption with customer-managed keys in an Azure key vault that resides in a different tenant than the tenant where the storage account resides (preview). Customer-managed keys allow a service provider to encrypt the customer's data using an encryption key that is managed by the service provider's customer and that isn't accessible to the service provider. |
| 5 | +services: storage |
| 6 | +author: tamram |
| 7 | + |
| 8 | +ms.service: storage |
| 9 | +ms.topic: how-to |
| 10 | +ms.date: 08/31/2022 |
| 11 | +ms.author: tamram |
| 12 | +ms.reviewer: ozgun |
| 13 | +ms.subservice: common |
| 14 | +ms.custom: devx-track-azurepowershell, devx-track-azurecli |
| 15 | +--- |
| 16 | + |
| 17 | +# Configure cross-tenant customer-managed keys for an existing storage account (preview) |
| 18 | + |
| 19 | +Azure Storage encrypts all data in a storage account at rest. By default, data is encrypted with Microsoft-managed keys. For additional control over encryption keys, you can manage your own keys. Customer-managed keys must be stored in an Azure Key Vault or in an Azure Key Vault Managed Hardware Security Model (HSM). |
| 20 | + |
| 21 | +This article shows how to configure encryption with customer-managed keys for an existing storage account. In the cross-tenant scenario, the storage account resides in a tenant managed by an ISV, while the key used for encryption of that storage account resides in a key vault in a tenant that is managed by the customer. |
| 22 | + |
| 23 | +To learn how to configure customer-managed keys for a new storage account, see [Configure cross-tenant customer-managed keys for a new storage account (preview)](customer-managed-keys-configure-cross-tenant-new-account.md). |
| 24 | + |
| 25 | +## About the preview |
| 26 | + |
| 27 | +To use the preview, you must register for the Azure Active Directory federated client identity feature. Follow these instructions to register with PowerShell or Azure CLI: |
| 28 | + |
| 29 | +### [PowerShell](#tab/powershell-preview) |
| 30 | + |
| 31 | +To register with PowerShell, call the **Register-AzProviderFeature** command. |
| 32 | + |
| 33 | +```azurepowershell |
| 34 | +Register-AzProviderFeature -ProviderNamespace Microsoft.Storage ` |
| 35 | + -FeatureName FederatedClientIdentity |
| 36 | +``` |
| 37 | + |
| 38 | +To check the status of your registration with PowerShell, call the **Get-AzProviderFeature** command. |
| 39 | + |
| 40 | +```azurepowershell |
| 41 | +Get-AzProviderFeature -ProviderNamespace Microsoft.Storage ` |
| 42 | + -FeatureName FederatedClientIdentity |
| 43 | +``` |
| 44 | + |
| 45 | +After your registration is approved, you must re-register the Azure Storage resource provider. To re-register the resource provider with PowerShell, call the **Register-AzResourceProvider** command. |
| 46 | + |
| 47 | +```azurepowershell |
| 48 | +Register-AzResourceProvider -ProviderNamespace 'Microsoft.Storage' |
| 49 | +``` |
| 50 | + |
| 51 | +### [Azure CLI](#tab/azure-cli-preview) |
| 52 | + |
| 53 | +To register with Azure CLI, call the **az feature register** command. |
| 54 | + |
| 55 | +```azurecli |
| 56 | +az feature register --namespace Microsoft.Storage \ |
| 57 | + --name FederatedClientIdentity |
| 58 | +``` |
| 59 | + |
| 60 | +To check the status of your registration with Azure CLI, call the **az feature show** command. |
| 61 | + |
| 62 | +```azurecli |
| 63 | +az feature show --namespace Microsoft.Storage \ |
| 64 | + --name FederatedClientIdentity |
| 65 | +``` |
| 66 | + |
| 67 | +After your registration is approved, you must re-register the Azure Storage resource provider. To re-register the resource provider with Azure CLI, call the **az provider register command**. |
| 68 | + |
| 69 | +```azurecli |
| 70 | +az provider register --namespace 'Microsoft.Storage' |
| 71 | +``` |
| 72 | + |
| 73 | +--- |
| 74 | + |
| 75 | +> [!IMPORTANT] |
| 76 | +> Using cross-tenant customer-managed keys with Azure Storage encryption is currently in PREVIEW. |
| 77 | +> 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. |
| 78 | +
|
| 79 | +[!INCLUDE [active-directory-msi-cross-tenant-cmk-overview](../../../includes/active-directory-msi-cross-tenant-cmk-overview.md)] |
| 80 | + |
| 81 | +[!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)] |
| 82 | + |
| 83 | +## Configure customer-managed keys for an existing account |
| 84 | + |
| 85 | +Up to this point, you've configured the multi-tenant application on the ISV's tenant, installed the application on the customer's tenant, and configured the key vault and key on the customer's tenant. Next you can configure customer-managed keys on an existing storage account with the key from the customer's tenant. |
| 86 | + |
| 87 | +The examples in this article show how to configure customer-managed keys on an existing storage account by using a user-assigned managed identity to authorize access to the key vault. You can also use a system-assigned managed identity to configure customer-managed keys on an existing storage account. In either case, the managed identity must have appropriate permissions to access the key vault. For more information, see [Authenticate to Azure Key Vault](../../key-vault/general/authentication.md). |
| 88 | + |
| 89 | +When you configure encryption with customer-managed keys for an existing storage account, you can choose to automatically update the key version used for Azure Storage encryption whenever a new version is available in the associated key vault. To do so, omit the key version from the key URI. Alternately, you can explicitly specify a key version to be used for encryption until the key version is manually updated. Including the key version on the key URI configures customer-managed keys for manual updating of the key version. |
| 90 | + |
| 91 | +> [!IMPORTANT] |
| 92 | +> To rotate a key, create a new version of the key in Azure Key Vault. Azure Storage does not handle key rotation, so you will need to manage rotation of the key in the key vault. You can [configure key auto-rotation in Azure Key Vault](../../key-vault/keys/how-to-configure-key-rotation.md) or rotate your key manually. |
| 93 | +> |
| 94 | +> Azure Storage checks the key vault for a new key version only once daily. When you rotate a key in Azure Key Vault, be sure to wait 24 hours before disabling the older version. |
| 95 | +
|
| 96 | +### [Azure portal](#tab/portal) |
| 97 | + |
| 98 | +To configure cross-tenant customer-managed keys for an existing storage account in the Azure portal, follow these steps: |
| 99 | + |
| 100 | +1. Navigate to your storage account. |
| 101 | +1. On the **Settings** blade for the storage account, select **Encryption**. By default, key management is set to **Microsoft-managed keys**, as shown in the following image. |
| 102 | + |
| 103 | + :::image type="content" source="media/customer-managed-keys-configure-existing-account/portal-configure-encryption-keys.png" alt-text="Screenshot showing encryption options in Azure portal." lightbox="media/customer-managed-keys-configure-existing-account/portal-configure-encryption-keys.png"::: |
| 104 | + |
| 105 | +1. Select the **Customer-managed keys** option. |
| 106 | +1. Choose the **Select from Key Vault** option. |
| 107 | +1. Select **Enter key URI**, and specify the key URI. Omit the key version from the URI if you want Azure Storage to automatically check for a new key version and update it. |
| 108 | +1. Select the subscription that contains the key vault and key. |
| 109 | +1. In the **Identity type** field, select **User-assigned**, then specify the managed identity with the federated identity credential that you created previously. |
| 110 | +1. Expand the **Advanced** section, and select the multi-tenant registered application that you previously created in the ISV's tenant. |
| 111 | + |
| 112 | + :::image type="content" source="media/customer-managed-keys-configure-cross-tenant-existing-account/portal-configure-cross-tenant-cmk.png" alt-text="Screenshot showing how to configure cross-tenant customer-managed keys for an existing storage account in Azure portal."::: |
| 113 | + |
| 114 | +1. Save your changes. |
| 115 | + |
| 116 | +After you've specified the key from the key vault in the customer's tenant, the Azure portal indicates that customer-managed keys are configured with that key. It also indicates that automatic updating of the key version is enabled, and displays the key version currently in use for encryption. The portal also displays the type of managed identity used to authorize access to the key vault, the principal ID for the managed identity, and the application ID of the multi-tenant application. |
| 117 | + |
| 118 | +:::image type="content" source="media/customer-managed-keys-configure-cross-tenant-existing-account/portal-cross-tenant-cmk-settings.png" alt-text="Screenshot showing cross-tenant customer-managed key configuration."::: |
| 119 | + |
| 120 | +### [PowerShell](#tab/powershell) |
| 121 | + |
| 122 | +N/A |
| 123 | + |
| 124 | +### [Azure CLI](#tab/azure-cli) |
| 125 | + |
| 126 | +N/A |
| 127 | + |
| 128 | +--- |
| 129 | + |
| 130 | +[!INCLUDE [storage-customer-managed-keys-change-include](../../../includes/storage-customer-managed-keys-change-include.md)] |
| 131 | + |
| 132 | +[!INCLUDE [storage-customer-managed-keys-revoke-include](../../../includes/storage-customer-managed-keys-revoke-include.md)] |
| 133 | + |
| 134 | +[!INCLUDE [storage-customer-managed-keys-disable-include](../../../includes/storage-customer-managed-keys-disable-include.md)] |
| 135 | + |
| 136 | +## See also |
| 137 | + |
| 138 | +- [Customer-managed keys for Azure Storage encryption](customer-managed-keys-overview.md) |
| 139 | +- [Configure cross-tenant customer-managed keys for a new storage account](customer-managed-keys-configure-cross-tenant-new-account.md) |
0 commit comments