Azure Key Vault recovery management with soft delete and purge protection

This article covers two recovery features of Azure Key Vault, soft delete and purge protection. This document provides an overview of these features, and shows you how to manage them through the Azure portal, Azure CLI, and Azure PowerShell.

Important

If a key vault does not have soft-delete protection enabled, deleting a key deletes it permanently. Customers are strongly encouraged to turn on soft delete enforcement for their vaults via Azure Policy.

For more information about Key Vault, see

• Key Vault overview
• Azure Key Vault keys, secrets, and certificates overview

Prerequisites

• An Azure subscription - create one for free

• Azure PowerShell.

• Azure CLI

• A Key Vault - you can create one using Azure portal Azure CLI, or Azure PowerShell

• The user needs the following permissions (at subscription level) to perform operations on soft-deleted vaults:

  Permission	Description
  Microsoft.KeyVault/locations/deletedVaults/read	View the properties of a soft deleted key vault
  Microsoft.KeyVault/locations/deletedVaults/purge/action	Purge a soft deleted key vault
  Microsoft.KeyVault/locations/operationResults/read	To check purging state of vault
  Key Vault Contributor	To recover soft-deleted vault

What are soft-delete and purge protection

Soft delete and purge protection are two different key vault recovery features.

Soft delete is designed to prevent accidental deletion of your key vault and keys, secrets, and certificates stored inside key vault. Think of soft-delete like a recycle bin. When you delete a key vault or a key vault object, it remains recoverable for a user configurable retention period or a default of 90 days. Key vaults in the soft deleted state can also be purged (permanently deleted), allowing you to recreate key vaults and key vault objects with the same name. Both recovering and deleting key vaults and objects require elevated access policy permissions. Once soft delete has been enabled, it cannot be disabled.

It is important to note that key vault names are globally unique, so you aren't able to create a key vault with the same name as a key vault in the soft deleted state. Similarly, the names of keys, secrets, and certificates are unique within a key vault. You aren't able to create a secret, key, or certificate with the same name as another in the soft deleted state.

Purge protection is designed to prevent the deletion of your key vault, keys, secrets, and certificates by a malicious insider. Think of it as a recycle bin with a time based lock. You can recover items at any point during the configurable retention period. You will not be able to permanently delete or purge a key vault until the retention period elapses. Once the retention period elapses the key vault or key vault object is purged automatically.

Note

Purge Protection is designed so that no administrator role or permission can override, disable, or circumvent purge protection. When purge protection is enabled, it cannot be disabled or overridden by anyone including Microsoft. This means you must recover a deleted key vault or wait for the retention period to elapse before reusing the key vault name.

For more information about soft-delete, see Azure Key Vault soft-delete overview

Azure portal

Verify if soft delete is enabled on a key vault and enable soft delete

1. Sign in to the Azure portal.
2. Select your key vault.
3. Select the "Properties" blade.
4. Verify if the radio button next to soft-delete is set to "Enable Recovery".
5. If soft-delete is not enabled on the key vault, select the radio button to enable soft delete and select "Save".

Grant access to a service principal to purge and recover deleted secrets

1. Sign in to the Azure portal.
2. Select your key vault.
3. Select the "Access Policy" blade.
4. In the table, find the row of the security principal you wish to grant access to (or add a new security principal).
5. Select the drop-down for keys, certificates, and secrets.
6. Scroll to the bottom of the drop-down and select "Recover" and "Purge"
7. Security principals also need "get" and "list" functionality to perform most operations.

List, recover, or purge a soft-deleted key vault

1. Sign in to the Azure portal.
2. Select the search bar at the top of the page.
3. Search for the "Key Vault" service. Do not select an individual key vault.
4. At the top of the screen, select the option to "Manage deleted vaults"
5. A context pane opens on the right side of your screen.
6. Select your subscription.
7. If your key vault has been soft deleted, it appears in the context pane on the right.
8. If there are too many vaults, you can either select "Load More" at the bottom of the context pane or use CLI or PowerShell to get the results.
9. Once you find the vault you wish to recover or purge, select the checkbox next to it.
10. Select the recover option at the bottom of the context pane if you would like to recover the key vault.
11. Select the purge option if you would like to permanently delete the key vault.

List, recover or purge soft deleted secrets, keys, and certificates

1. Sign in to the Azure portal.
2. Select your key vault.
3. Select the blade corresponding to the secret type you want to manage (keys, secrets, or certificates).
4. At the top of the screen, select "Manage deleted (keys, secrets, or certificates)
5. A context pane appears on the right side of your screen.
6. If your secret, key, or certificate does not appear in the list, it is not in the soft-deleted state.
7. Select the secret, key, or certificate you would like to manage.
8. Select the option to recover or purge at the bottom of the context pane.

Azure CLI

Key Vault (CLI)

• Verify if a key-vault has soft-delete enabled

  Azure CLI

  az keyvault show --subscription {SUBSCRIPTION ID} -g {RESOURCE GROUP} -n {VAULT NAME}
  

• Enable soft-delete on key-vault

  All new key vaults have soft delete enabled by default. If you currently have a key vault that does not have soft delete enabled, use the following command to enable soft delete.

  Azure CLI

  az keyvault update --subscription {SUBSCRIPTION ID} -g {RESOURCE GROUP} -n {VAULT NAME} --enable-soft-delete true
  

• Delete key vault (recoverable if soft delete is enabled)

  Azure CLI

  az keyvault delete --subscription {SUBSCRIPTION ID} -g {RESOURCE GROUP} -n {VAULT NAME}
  

• List all soft-deleted key vaults

  Azure CLI

  az keyvault list-deleted --subscription {SUBSCRIPTION ID} --resource-type vault
  

• Recover soft-deleted key-vault

  Azure CLI

  az keyvault recover --subscription {SUBSCRIPTION ID} -n {VAULT NAME}
  

• Purge soft-deleted key vault (WARNING! THIS OPERATION WILL PERMANENTLY DELETE YOUR KEY VAULT)

  Azure CLI

  az keyvault purge --subscription {SUBSCRIPTION ID} -n {VAULT NAME}
  

• Enable purge-protection on key-vault

  Azure CLI

  az keyvault update --subscription {SUBSCRIPTION ID} -g {RESOURCE GROUP} -n {VAULT NAME} --enable-purge-protection true
  

Certificates (CLI)

• Grant access to purge and recover certificates

  Azure CLI

  az keyvault set-policy --upn user@contoso.com --subscription {SUBSCRIPTION ID} -g {RESOURCE GROUP} -n {VAULT NAME}  --certificate-permissions recover purge
  

• Delete certificate

  Azure CLI

  az keyvault certificate delete --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {CERTIFICATE NAME}
  

• List deleted certificates

  Azure CLI

  az keyvault certificate list-deleted --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME}
  

• Recover deleted certificate

  Azure CLI

  az keyvault certificate recover --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {CERTIFICATE NAME}
  

• Purge soft-deleted certificate (WARNING! THIS OPERATION WILL PERMANENTLY DELETE YOUR CERTIFICATE)

  Azure CLI

  az keyvault certificate purge --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {CERTIFICATE NAME}
  

Keys (CLI)

• Grant access to purge and recover keys

  Azure CLI

  az keyvault set-policy --upn user@contoso.com --subscription {SUBSCRIPTION ID} -g {RESOURCE GROUP} -n {VAULT NAME}  --key-permissions recover purge
  

• Delete key

  Azure CLI

  az keyvault key delete --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {KEY NAME}
  

• List deleted keys

  Azure CLI

  az keyvault key list-deleted --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME}
  

• Recover deleted key

  Azure CLI

  az keyvault key recover --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {KEY NAME}
  

• Purge soft-deleted key (WARNING! THIS OPERATION WILL PERMANENTLY DELETE YOUR KEY)

  Azure CLI

  az keyvault key purge --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {KEY NAME}
  

Secrets (CLI)

• Grant access to purge and recover secrets

  Azure CLI

  az keyvault set-policy --upn user@contoso.com --subscription {SUBSCRIPTION ID} -g {RESOURCE GROUP} -n {VAULT NAME}  --secret-permissions recover purge
  

• Delete secret

  Azure CLI

  az keyvault secret delete --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {SECRET NAME}
  

• List deleted secrets

  Azure CLI

  az keyvault secret list-deleted --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME}
  

• Recover deleted secret

  Azure CLI

  az keyvault secret recover --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {SECRET NAME}
  

• Purge soft-deleted secret (WARNING! THIS OPERATION WILL PERMANENTLY DELETE YOUR SECRET)

  Azure CLI

  az keyvault secret purge --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {SECRET NAME}
  

Azure PowerShell

Key Vault (PowerShell)

• Verify if a key-vault has soft-delete enabled

  Azure PowerShell

  Get-AzKeyVault -VaultName "ContosoVault"
  

• Delete key vault

  Azure PowerShell

  Remove-AzKeyVault -VaultName 'ContosoVault'
  

• List all soft-deleted key vaults

  Azure PowerShell

  Get-AzKeyVault -InRemovedState
  

• Recover soft-deleted key-vault

  Azure PowerShell

  Undo-AzKeyVaultRemoval -VaultName ContosoVault -ResourceGroupName ContosoRG -Location westus
  

• Purge soft-deleted key-vault (WARNING! THIS OPERATION WILL PERMANENTLY DELETE YOUR KEY VAULT)

  Azure PowerShell

  Remove-AzKeyVault -VaultName ContosoVault -InRemovedState -Location westus
  

• Enable purge-protection on key-vault

  Azure PowerShell

  Update-AzKeyVault -VaultName ContosoVault -ResourceGroupName ContosoRG -EnablePurgeProtection
  

Certificates (PowerShell)

• Grant permissions to recover and purge certificates

  Azure PowerShell

  Set-AzKeyVaultAccessPolicy -VaultName ContosoVault -UserPrincipalName user@contoso.com -PermissionsToCertificates recover,purge
  

• Delete a Certificate

  Azure PowerShell

  Remove-AzKeyVaultCertificate -VaultName ContosoVault -Name 'MyCert'
  

• List all deleted certificates in a key vault

  Azure PowerShell

  Get-AzKeyVaultCertificate -VaultName ContosoVault -InRemovedState
  

• Recover a certificate in the deleted state

  Azure PowerShell

  Undo-AzKeyVaultCertificateRemoval -VaultName ContosoVault -Name 'MyCert'
  

• Purge a soft-deleted certificate (WARNING! THIS OPERATION WILL PERMANENTLY DELETE YOUR CERTIFICATE)

  Azure PowerShell

  Remove-AzKeyVaultcertificate -VaultName ContosoVault -Name 'MyCert' -InRemovedState
  

Keys (PowerShell)

• Grant permissions to recover and purge keys

  Azure PowerShell

  Set-AzKeyVaultAccessPolicy -VaultName ContosoVault -UserPrincipalName user@contoso.com -PermissionsToKeys recover,purge
  

• Delete a key

  Azure PowerShell

  Remove-AzKeyVaultKey -VaultName ContosoVault -Name 'MyKey'
  

• List all deleted keys in a key vault

  Azure PowerShell

  Get-AzKeyVaultKey -VaultName ContosoVault -InRemovedState
  

• To recover a soft-deleted key

  Azure PowerShell

  Undo-AzKeyVaultKeyRemoval -VaultName ContosoVault -Name ContosoFirstKey
  

• Purge a soft-deleted key (WARNING! THIS OPERATION WILL PERMANENTLY DELETE YOUR KEY)

  Azure PowerShell

  Remove-AzKeyVaultKey -VaultName ContosoVault -Name ContosoFirstKey -InRemovedState
  

Secrets (PowerShell)

• Grant permissions to recover and purge secrets

  Azure PowerShell

  Set-AzKeyVaultAccessPolicy -VaultName ContosoVault -UserPrincipalName user@contoso.com -PermissionsToSecrets recover,purge
  

• Delete a secret named SQLPassword

  Azure PowerShell

  Remove-AzKeyVaultSecret -VaultName ContosoVault -Name SQLPassword
  

• List all deleted secrets in a key vault

  Azure PowerShell

  Get-AzKeyVaultSecret -VaultName ContosoVault -InRemovedState
  

• Recover a secret in the deleted state

  Azure PowerShell

  Undo-AzKeyVaultSecretRemoval -VaultName ContosoVault -Name SQLPassword
  

• Purge a secret in deleted state (WARNING! THIS OPERATION WILL PERMANENTLY DELETE YOUR KEY)

  Azure PowerShell

  Remove-AzKeyVaultSecret -VaultName ContosoVault -Name SQLPassword -InRemovedState 
  

Next steps

• Azure Key Vault PowerShell cmdlets
• Key Vault Azure CLI commands
• Azure Key Vault backup
• How to enable Key Vault logging
• Azure Key Vault security features
• Azure Key Vault developer's guide