| title | Configure customer-managed keys in the same tenant for a new storage account | |||
|---|---|---|---|---|
| titleSuffix | Azure Storage | |||
| description | Learn how to configure Azure Storage encryption with customer-managed keys for a new storage account by using the Azure portal, PowerShell, or Azure CLI. Customer-managed keys are stored in an Azure Key Vault. | |||
| services | storage | |||
| author | normesta | |||
| ms.service | azure-storage | |||
| ms.topic | how-to | |||
| ms.date | 03/23/2023 | |||
| ms.author | normesta | |||
| ms.reviewer | ozgun | |||
| ms.subservice | storage-common-concepts | |||
| ms.custom |
|
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).
This article shows how to configure encryption with customer-managed keys at the time that you create a new storage account. The customer-managed keys are stored in a key vault.
To learn how to configure customer-managed keys for an existing storage account, see Configure customer-managed keys in an Azure Key Vault for an existing storage account.
Note
Azure Key Vault and Azure Key Vault Managed HSM support the same APIs and management interfaces for configuration of customer-managed keys. Any action that is supported for Azure Key Vault is also supported for Azure Key Vault Managed HSM.
[!INCLUDE storage-customer-managed-keys-key-vault-configure-include]
[!INCLUDE storage-customer-managed-keys-key-vault-add-key-include]
[!INCLUDE storage-customer-managed-keys-key-vault-user-assigned-identity-include]
When you configure encryption with customer-managed keys for a new 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. Alternately, you can explicitly specify a key version to be used for encryption until the key version is manually updated.
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 storage account. The user-assigned managed identity must have appropriate permissions to access the key vault. For more information, see Authenticate to Azure Key Vault.
Azure Storage can automatically update the customer-managed key that is used for encryption to use the latest key version from the key vault. Azure Storage checks the key vault daily for a new version of the key. When a new version becomes available, then Azure Storage automatically begins using the latest version of the key for encryption.
Important
Azure Storage checks the key vault for a new key version only once daily. When you rotate a key, be sure to wait 24 hours before disabling the older version.
To configure customer-managed keys for a new storage account with automatic updating of the key version, follow these steps:
-
In the Azure portal, navigate to the Storage accounts page, and select the Create button to create a new account.
-
Follow the steps outlined in Create a storage account to fill out the fields on the Basics, Advanced, Networking, and Data Protection tabs.
-
On the Encryption tab, indicate for which services you want to enable support for customer-managed keys in the Enable support for customer-managed keys field.
-
In the Encryption type field, select Customer-managed keys (CMK).
-
In the Encryption key field, choose Select a key vault and key, and specify the key vault and key.
-
For the User-assigned identity field, select an existing user-assigned managed identity.
:::image type="content" source="media/customer-managed-keys-configure-new-account/portal-new-account-configure-cmk.png" alt-text="Screenshot showing how to configure customer-managed keys for a new storage account in Azure portal.":::
-
Select the Review button to validate and create the account.
You can also configure customer-managed keys with manual updating of the key version when you create a new storage account. Follow the steps described in Configure encryption for manual updating of key versions.
To configure customer-managed keys for a new storage account with automatic updating of the key version, call New-AzStorageAccount, as shown in the following example. Use the variable you created previously for the resource ID for the user-assigned managed identity. You'll also need the key vault URI and key name:
$accountName = "<storage-account>"
New-AzStorageAccount -ResourceGroupName $rgName `
-Name $accountName `
-Kind StorageV2 `
-SkuName Standard_LRS `
-Location $location `
-AllowBlobPublicAccess $false `
-IdentityType SystemAssignedUserAssigned `
-UserAssignedIdentityId $userIdentity.Id `
-KeyVaultUri $keyVault.VaultUri `
-KeyName $key.Name `
-KeyVaultUserAssignedIdentityId $userIdentity.Id
To configure customer-managed keys for a new storage account with automatic updating of the key version, call az storage account create, as shown in the following example. Use the variable you created previously for the resource ID for the user-assigned managed identity. You'll also need the key vault URI and key name:
accountName="<storage-account>"
az storage account create \
--name $accountName \
--resource-group $rgName \
--location $location \
--sku Standard_LRS \
--kind StorageV2 \
--identity-type SystemAssigned,UserAssigned \
--user-identity-id $identityResourceId \
--encryption-key-vault <key-vault-uri> \
--encryption-key-name $keyName \
--encryption-key-source Microsoft.Keyvault \
--key-vault-user-identity-id $identityResourceId
If you prefer to manually update the key version, then explicitly specify the version when you configure encryption with customer-managed keys while creating the storage account. In this case, Azure Storage won't automatically update the key version when a new version is created in the key vault. To use a new key version, you must manually update the version used for Azure Storage encryption.
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 storage account. The user-assigned managed identity must have appropriate permissions to access the key vault. For more information, see Authenticate to Azure Key Vault.
To configure customer-managed keys with manual updating of the key version in the Azure portal, specify the key URI, including the version, while creating the storage account. To specify a key as a URI, follow these steps:
-
In the Azure portal, navigate to the Storage accounts page, and select the Create button to create a new account.
-
Follow the steps outlined in Create a storage account to fill out the fields on the Basics, Advanced, Networking, and Data Protection tabs.
-
On the Encryption tab, indicate for which services you want to enable support for customer-managed keys in the Enable support for customer-managed keys field.
-
In the Encryption type field, select Customer-managed keys (CMK).
-
To locate the key URI in the Azure portal, navigate to your key vault, and select the Keys setting. Select the desired key, then select the key to view its versions. Select a key version to view the settings for that version.
-
Copy the value of the Key Identifier field, which provides the URI.
:::image type="content" source="media/customer-managed-keys-configure-new-account/portal-copy-key-identifier.png" alt-text="Screenshot showing key vault key URI in Azure portal.":::
-
In the Encryption key settings for your storage account, choose the Enter key URI option.
-
Paste the URI that you copied into the Key URI field. Include the key version on the URI to configure manual updating of the key version.
-
Specify a user-assigned managed identity by choosing the Select an identity link.
:::image type="content" source="media/customer-managed-keys-configure-new-account/portal-specify-key-uri.png" alt-text="Screenshot showing how to enter key URI in Azure portal.":::
-
Select the Review button to validate and create the account.
To configure customer-managed keys with manual updating of the key version, explicitly provide the key version when you configure encryption while creating the storage account. Call Set-AzStorageAccount to update the storage account's encryption settings, as shown in the following example, and include the -KeyvaultEncryption option to enable customer-managed keys for the storage account.
Remember to replace the placeholder values in brackets with your own values and to use the variables defined in the previous examples.
$accountName = "<storage-account>"
New-AzStorageAccount -ResourceGroupName $rgName `
-Name $accountName `
-Kind StorageV2 `
-SkuName Standard_LRS `
-Location $location `
-AllowBlobPublicAccess $false `
-IdentityType SystemAssignedUserAssigned `
-UserAssignedIdentityId $userIdentity.Id `
-KeyVaultUri $keyVault.VaultUri `
-KeyName $key.Name `
-KeyVersion $key.Version `
-KeyVaultUserAssignedIdentityId $userIdentity.Id
When you manually update the key version, you'll need to update the storage account's encryption settings to use the new version. First, call Get-AzKeyVaultKey to get the latest version of the key. Then call Set-AzStorageAccount to update the storage account's encryption settings to use the new version of the key, as shown in the previous example.
To configure customer-managed keys with manual updating of the key version, explicitly provide the key version when you configure encryption while creating the storage account. Call az storage account update to update the storage account's encryption settings, as shown in the following example. Include the --encryption-key-source parameter and set it to Microsoft.Keyvault to enable customer-managed keys for the account.
Remember to replace the placeholder values in brackets with your own values.
accountName="<storage-account>"
key_vault_uri=$(az keyvault show \
--name <key-vault> \
--resource-group <resource_group> \
--query properties.vaultUri \
--output tsv)
key_version=$(az keyvault key list-versions \
--name <key> \
--vault-name <key-vault> \
--query [-1].kid \
--output tsv | cut -d '/' -f 6)
az storage account create \
--name $accountName \
--resource-group $rgName \
--location $location \
--sku Standard_LRS \
--kind StorageV2 \
--allow-blob-public-access false \
--identity-type SystemAssigned,UserAssigned \
--user-identity-id $identityResourceId \
--encryption-key-vault $keyVaultUri \
--encryption-key-name $keyName \
--encryption-key-source Microsoft.Keyvault \
--encryption-key-version $keyVersion \
--key-vault-user-identity-id $identityResourceId
When you manually update the key version, you'll need to update the storage account's encryption settings to use the new version. First, query for the key vault URI by calling az keyvault show, and for the key version by calling az keyvault key list-versions. Then call az storage account update to update the storage account's encryption settings to use the new version of the key, as shown in the previous example.
[!INCLUDE storage-customer-managed-keys-change-include]
If the new key is in a different key vault, you must grant the managed identity access to the key in the new vault. If you choose manual updating of the key version, you will also need to update the key vault URI.
[!INCLUDE storage-customer-managed-keys-revoke-include]
Disabling the key will cause attempts to access data in the storage account to fail with error code 403 (Forbidden). For a list of storage account operations that will be affected by disabling the key, see Revoke access to a storage account that uses customer-managed keys.