Configure customer-managed keys in the same tenant for a new storage account

To learn how to create a key vault with the Azure portal, see Quickstart: Create a key vault using the Azure portal. When you create the key vault, select Enable purge protection, as shown in the following image.

To enable purge protection on an existing key vault, follow these steps:

1. Navigate to your key vault in the Azure portal.
2. Under Settings, choose Properties.
3. In the Purge protection section, choose Enable purge protection.

To create a new key vault with PowerShell, install version 2.0.0 or later of the Az.KeyVault PowerShell module. Then call New-AzKeyVault to create a new key vault. With version 2.0.0 and later of the Az.KeyVault module, soft delete is enabled by default when you create a new key vault.

The following example creates a new key vault with soft delete and purge protection enabled. The key vault's permission model is set to use Azure RBAC. Remember to replace the placeholder values in brackets with your own values.

$rgName = "<resource_group>"
$location = "<location>"
$kvName = "<key-vault>"

$keyVault = New-AzKeyVault -Name $kvName `
    -ResourceGroupName $rgName `
    -Location $location `
    -EnablePurgeProtection `
    -EnableRbacAuthorization

To learn how to enable purge protection on an existing key vault with PowerShell, see Azure Key Vault recovery overview.

After you have created the key vault, you'll need to assign the Key Vault Crypto Officer role to yourself. This role enables you to create a key in the key vault. The following example assigns this role to a user, scoped to the key vault:

New-AzRoleAssignment -SignInName "<user-email>" `
    -RoleDefinitionName "Key Vault Crypto Officer" `
    -Scope $keyVault.ResourceId

For more information on how to assign an RBAC role with PowerShell, see Assign Azure roles using Azure PowerShell.

To create a new key vault using Azure CLI, call az keyvault create. The following example creates a new key vault with soft delete and purge protection enabled. The key vault's permission model is set to use Azure RBAC. Remember to replace the placeholder values in brackets with your own values.

rgName="<resource_group>"
location="<location>"
kvName="<key-vault>"

az keyvault create \
    --name $kvName \
    --resource-group $rgName \
    --location $location \
    --enable-purge-protection \
    --enable-rbac-authorization

To learn how to enable purge protection on an existing key vault with Azure CLI, see Azure Key Vault recovery overview.

After you have created the key vault, you'll need to assign the Key Vault Crypto Officer role to yourself. This role enables you to create a key in the key vault. The following example assigns this role to a user, scoped to the key vault:

kvResourceId=$(az keyvault show --resource-group $rgName \
    --name $kvName \
    --query id \
    --output tsv)

az role assignment create --assignee "<user-email>" \
    --role "Key Vault Crypto Officer" \
    --scope $kvResourceId

For more information on how to assign an RBAC role with Azure CLI, see Assign Azure roles using Azure CLI.

To learn how to add a key with the Azure portal, see Quickstart: Set and retrieve a key from Azure Key Vault using the Azure portal.

To add a key with PowerShell, 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.

$keyName = "<key-name>"

$key = Add-AzKeyVaultKey -VaultName $keyVault.VaultName `
    -Name $keyName `
    -Destination 'Software'

To add a key with Azure CLI, call az keyvault key create. Remember to replace the placeholder values in brackets with your own values.

keyName="<key-name>"

az keyvault key create \
    --name $keyName \
    --vault-name $kvName

Before you can configure customer-managed keys with a user-assigned managed identity, you must assign the Key Vault Crypto Service Encryption User role to the user-assigned managed identity, scoped to the key vault. This role grants the user-assigned managed identity permissions to access the key in the key vault. For more information on assigning Azure RBAC roles with the Azure portal, see Assign Azure roles using the Azure portal.

When you configure customer-managed keys with the Azure portal, you can select an existing user-assigned identity through the portal user interface.

The following example shows how to retrieve the user-assigned managed identity and assign to it the required RBAC role, scoped to the key vault. Remember to replace the placeholder values in brackets with your own values and to use the variables defined in the previous examples:

$userIdentity = Get-AzUserAssignedIdentity -Name <user-assigned-identity> `
    -ResourceGroupName $rgName

$principalId = $userIdentity.PrincipalId

New-AzRoleAssignment -ObjectId $principalId `
    -RoleDefinitionName "Key Vault Crypto Service Encryption User" `
    -Scope $keyVault.ResourceId

The following example shows how to retrieve the user-assigned managed identity and assign to it the required RBAC role, scoped to the key vault. Remember to replace the placeholder values in brackets with your own values and to use the variables defined in the previous examples:

identityResourceId=$(az identity show --name <user-assigned-identity> \
    --resource-group $rgName \
    --query id \
    --output tsv)

principalId=$(az identity show --name <user-assigned-identity> \
    --resource-group $rgName \
    --query principalId \
    --output tsv)

az role assignment create --assignee-object-id $principalId \
    --role "Key Vault Crypto Service Encryption User" \
    --scope $kvResourceId \
    --assignee-principal-type ServicePrincipal

To configure customer-managed keys for a new storage account with automatic updating of the key version, follow these steps:

1. In the Azure portal, navigate to the Storage accounts page, and select the Create button to create a new account.

2. Follow the steps outlined in Create a storage account to fill out the fields on the Basics, Advanced, Networking, and Data Protection tabs.

3. 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.

4. In the Encryption type field, select Customer-managed keys (CMK).

5. In the Encryption key field, choose Select a key vault and key, and specify the key vault and key.

6. For the User-assigned identity field, select an existing user-assigned managed identity.

   

7. 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

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:

1. In the Azure portal, navigate to the Storage accounts page, and select the Create button to create a new account.

2. Follow the steps outlined in Create a storage account to fill out the fields on the Basics, Advanced, Networking, and Data Protection tabs.

3. 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.

4. In the Encryption type field, select Customer-managed keys (CMK).

5. 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.

6. Copy the value of the Key Identifier field, which provides the URI.

   

7. In the Encryption key settings for your storage account, choose the Enter key URI option.

8. 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.

9. Specify a user-assigned managed identity by choosing the Select an identity link.

   

10. 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.

To change the key with the Azure portal, follow these steps:

1. Navigate to your storage account and display the Encryption settings.
2. Select the key vault and choose a new key.
3. Save your changes.

To change the key with PowerShell, call Set-AzStorageAccount and provide the new key name and version. If the new key is in a different key vault, then you must also update the key vault URI.

To change the key with Azure CLI, call az storage account update and provide the new key name and version. If the new key is in a different key vault, then you must also update the key vault URI.

To disable a customer-managed key with the Azure portal, follow these steps:

1. Navigate to the key vault that contains the key.

2. Under Objects, select Keys.

3. Right-click the key and select Disable.

   

To revoke a customer-managed key with PowerShell, call the Update-AzKeyVaultKey command, as shown in the following example. Remember to replace the placeholder values in brackets with your own values to define the variables, or use the variables defined in the previous examples.

$kvName  = "<key-vault-name>"
$keyName = "<key-name>"
$enabled = $false
# $false to disable the key / $true to enable it

# Check the current state of the key (before and after enabling/disabling it)
Get-AzKeyVaultKey -Name $keyName -VaultName $kvName

# Disable (or enable) the key
Update-AzKeyVaultKey -VaultName $kvName -Name $keyName -Enable $enabled

To revoke a customer-managed key with Azure CLI, call the az keyvault key set-attributes command, as shown in the following example. Remember to replace the placeholder values in brackets with your own values to define the variables, or use the variables defined in the previous examples.

kvName="<key-vault-name>"
keyName="<key-name>"
enabled="false"
# "false" to disable the key / "true" to enable it:

# Check the current state of the key (before and after enabling/disabling it)
az keyvault key show \
    --vault-name $kvName \
    --name $keyName

# Disable (or enable) the key
az keyvault key set-attributes \
    --vault-name $kvName \
    --name $keyName \
    --enabled $enabled

To switch from customer-managed keys back to Microsoft-managed keys in the Azure portal, follow these steps:

1. Navigate to your storage account.

2. Under Security + networking, select Encryption.

3. Change Encryption type to Microsoft-managed keys.

   

To switch from customer-managed keys back to Microsoft-managed keys with PowerShell, call Set-AzStorageAccount with the -StorageEncryption option, as shown in the following example. 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 `
    -StorageEncryption  

To switch from customer-managed keys back to Microsoft-managed keys with Azure CLI, call az storage account update and set the --encryption-key-source parameter to Microsoft.Storage, as shown in the following example. Remember to replace the placeholder values in brackets with your own values and to use the variables defined in the previous examples.

az storage account update \
    --name <storage-account> \
    --resource-group <resource_group> \
    --encryption-key-source Microsoft.Storage