Configure customer-managed keys for Azure Storage encryption from PowerShell

Azure Storage supports encryption at rest with either Microsoft-managed keys or customer-managed keys. Customer-managed keys enable you to create, rotate, disable, and revoke access controls.

Use Azure Key Vault to manage your keys and audit your key usage. 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 storage account and the key vault must be in the same region, but they can be in different subscriptions. For more information about Azure Key Vault, see What is Azure Key Vault?

This article shows how to configure a key vault with customer-managed keys using PowerShell.

Important

Using customer-managed keys with Azure Storage encryption requires that two properties be set on the key vault, Soft Delete and Do Not Purge. These properties are not enabled by default. To enable these properties, use either PowerShell or Azure CLI. Only RSA keys and key size 2048 are supported.

Assign an identity to the storage account

To enable customer-managed keys for your storage account, first assign a system-assigned managed identity to the storage account. You'll use this managed identity to grant the storage account permissions to access the key vault.

To assign a managed identity using PowerShell, call Set-AzStorageAccount. Remember to replace the placeholder values in brackets with your own values.

$storageAccount = Set-AzStorageAccount -ResourceGroupName <resource_group> `
    -Name <storage-account> `
    -AssignIdentity

For more information about configuring system-assigned managed identities with PowerShell, see Configure managed identities for Azure resources on an Azure VM using PowerShell.

Create a new key vault

To create a new key vault using PowerShell, call New-AzKeyVault. The key vault that you use to store customer-managed keys for Azure Storage encryption must have two key protection settings enabled, Soft Delete and Do Not Purge.

Remember to replace the placeholder values in brackets with your own values.

$keyVault = New-AzKeyVault -Name <key-vault> `
    -ResourceGroupName <resource_group> `
    -Location <location> `
    -EnableSoftDelete `
    -EnablePurgeProtection

Configure the key vault access policy

Next, configure the access policy for the key vault so that the storage account has permissions to access it. In this step, you'll use the managed identity that you previously assigned to the storage account.

To set the access policy for the key vault, call Set-AzKeyVaultAccessPolicy. Remember to replace the placeholder values in brackets with your own values and to use the variables defined in the previous examples.

Set-AzKeyVaultAccessPolicy `
    -VaultName $keyVault.VaultName `
    -ObjectId $storageAccount.Identity.PrincipalId `
    -PermissionsToKeys wrapkey,unwrapkey,get,recover

Create a new key

Next, create a new key in the key vault. To create a new key, call Add-AzKeyVaultKey. Remember to replace the placeholder values in brackets with your own values and to use the variables defined in the previous examples.

$key = Add-AzKeyVaultKey -VaultName $keyVault.VaultName -Name <key> -Destination 'Software'

Configure encryption with customer-managed keys

By default, Azure Storage encryption uses Microsoft-managed keys. In this step, configure your Azure Storage account to use customer-managed keys and specify the key to associate with the storage account.

Call Set-AzStorageAccount to update the storage account's encryption settings. Remember to replace the placeholder values in brackets with your own values and to use the variables defined in the previous examples.

Set-AzStorageAccount -ResourceGroupName $storageAccount.ResourceGroupName `
    -AccountName $storageAccount.StorageAccountName `
    -KeyvaultEncryption `
    -KeyName $key.Name `
    -KeyVersion $key.Version `
    -KeyVaultUri $keyVault.VaultUri

Update the key version

When you create a new version of a key, you'll need to update the storage account 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 section.

Next steps