Azure Key Vault Recovery Options
[Updated on November 22, 2017]
Hello again!
It's been a while since our last update. Today we are very excited to announce public preview of a new feature that our customers have often requested.
Have you ever faced a situation where you found out that an important key vault or a key or a secret was inadvertently deleted? Either as a result of you or another team member deleting it by mistake or you issuing a wrong command? What if the key was in use for encrypting large amounts of data? Surely you could restore such key via a backup if it is available. But what if no such key backup is available? This could be a major disaster scenario. If you worry about such disaster scenarios, read on!
As usual, we value your input so please take a moment to join our advisory board , send us private feedback ,and/or visit our forum.
Key Vault now offers recovery options such that you can recover deleted keys for up to 90 days. We call this feature soft-delete. Soft-delete enables you to recover deleted objects (vaults, keys, secrets).
Important: To be able to recover deleted objects, you must opt-in each key vault to enable soft-delete feature for the vault. A vault level attribute indicates if the vault has soft-delete enabled.
Today this feature is available for vaults, keys and secrets. We'll soon enable soft-delete for certificates too. [Update: soft-delete support for certificates was released on September 25, 2017]
So here's a quick bite on soft-delete for the impatient:
- You can create new vaults with soft-delete enabled. You can also turn on soft-delete for existing vaults.
- For vaults with soft-delete enabled, when a vault/key/secret is deleted, it simply goes into a ‘deleted state’ and remains in that state unless user takes an action.
- Two actions are possible:
- You can ‘recover’ the vault/key/secret. In that case the vault/key/secret will be recovered and will appear exactly as it was before deletion, including all versions, tags and other metadata.
- You can 'purge' the vault/key/secret, such that it will be permanently deleted with no recovery possible.
- If none of the above action is taken while the vault/key/secret is in deleted state for 90 days, it will be permanently deleted at the end of 90 day window.
Note: This preview enables soft-delete opt-in using Azure PowerShell commands only. So you won't find any way to turn-on soft-delete from Azure Portal or Azure CLI just yet. But rest assured that they're coming soon.
Now let's get into the nitty-gritty details.
First things first - you'll need the latest Azure PowerShell (4.0.0 or later) to run below cmdlets.
Let's first talk about key vaults. As mentioned in the summary, to be able to recover a deleted vault or deleted keys/secrets inside a vault you must first enable soft-delete for that vault. Here's how.
Say you have a key vault named 'ContosoVault', here's how you would enable soft-delete for this vault:
($resource = Get-AzureRmResource -ResourceId (Get-AzureRmKeyVault -VaultName ContosoVault).ResourceId).Properties | Add-Member -MemberType NoteProperty -Name enableSoftDelete -Value 'True'
Set-AzureRmResource -resourceid $resource.ResourceId -Properties $resource.Properties
And if you're creating a new vault, simply add '-EnableSoftDelete' parameter when running 'New-AzureRmKeyVault' cmdlet, like this:
New-AzureRmKeyVault -VaultName ContosoVault -ResourceGroupName ContosoRG -Location westus -EnableSoftDelete
To check whether a vault has soft-delete enabled, run the 'Get-AzureRmKeyVault' cmdlet and look for the 'Soft Delete Enabled?' attribute. If it is set to 'True', soft-delete is enabled for this vault. If set to empty or 'False' soft-delete is disabled.
Now that we have enabled soft-delete for our vault, let's see what happens when this vault is deleted.
The cmdlet to delete (or remove) a vault remains same, but it's behavior changes depending on whether you have enabled soft-delete or not.
Remove-AzureRmKeyVault -VaultName ContosoVault
Important: If you run the above cmdlet for a vault that does not have soft-delete enabled, you will permanently lose this vault and all its content without any options for recovery. So beware!
With soft-delete turned on, when a vault is deleted, it is removed from the resource group and placed in a different name space that is only associated with the location where it was created. All the keys/secrets in a deleted vault also become inaccessible. The DNS name for a vault in deleted state is still reserved, so a new vault with same name cannot be created. To see all the vaults in your subscription in deleted state, run this cmdlet:
PS C:\> Get-AzureRmKeyVault -InRemovedState
Vault Name : ContosoVault
Location : westus
Id : /subscriptions/xxx/providers/Microsoft.KeyVault/locations/westus/deletedVaults/ContosoVault
Resource ID : /subscriptions/xxx/resourceGroups/ContosoVault/providers/Microsoft.KeyVault/vaults/ContosoVault
Deletion Date : 5/9/2017 12:14:14 AM
Scheduled Purge Date : 8/7/2017 12:14:14 AM
Tags :
Get-AzureRmKeyVault cmdlet will only show deleted vault if you use '-InRemovedState' parameter. In other words, if you do not use '-InRemovedState' parameter, you will not see deleted vaults listed.
The 'Resource ID' in the above output simply refers to the original resource ID of this vault. Since this vault is now in deleted state, no such resource exists with that resource ID. That's where the 'Id' field above comes in, which can be used to identify the resource when recovering, or purging. The 'Scheduled Purge Date' field indicates when the vault will be permanently deleted (purged) if no action is taken for this deleted vault.
So now let's see what we need to do to recover a vault. To recover a vault, you need to specify the vault name, resource group and location. Note down the location and the resource group of the deleted vault. You'll need it when recovering.
Undo-AzureRmKeyVaultRemoval -VaultName ContosoVault -ResourceGroupName ContosoRG-Location westus
When a vault is recovered, all the keys/secrets in the vault will also become accessible again.
When a vault is recovered, it results in a new resource being created with the its original resource ID. If the resource group where the vault existed has been removed, a new resource group with same name will need to be recreated before the vault can be recovered. To purge (that is permanently delete) a vault run 'Remove-AzureRmKeyVault' with '-InRemovedState' and specify the location of the deleted vault.
Remove-AzureRmKeyVault -VaultName ContosoVault -InRemovedState -Location westus
Remember, when a vault is purged all its contents (such as keys and secrets) are also permanently deleted.
To recover a vault, a user needs to have RBAC permission to perform ‘Microsoft.KeyVault/vaults/write’ operation. Similarly to purge a deleted vault so that the vault and all its contents are permanently removed the user needs RBAC permission to perform ‘Microsoft.KeyVault/locations/deletedVaults/purge/action’ operation. To list the deleted vault a user needs RBAC permission to perform ‘Microsoft.KeyVault/deletedVaults/read’ permission.
Now that we have seen the complete life cycle of a vault with soft-delete enabled, let's turn our attention to keys and secrets in a vault with soft-delete enabled. I'm assuming here that you already know how to create keys and secrets in a vault. If not check out Get started with Azure Key Vault.
Let's say you have a key 'ContosoFirstKey' in your vault 'ContosoVault' with soft-delete enabled. Here's how you would delete that key.
Remove-AzureKeyVaultKey -VaultName ContosoVault -Name ContosoFirstKey
Important: If a key vault does not have soft-delete enabled, a deleted key cannot be recovered from such a vault. So beware!
With your key vault enabled for soft-delete, a deleted key still appears like it's deleted for the most part, except, when you explicitly list/retrieve deleted keys. Most operations on a key in deleted state will fail except for specifically listing deleted key, recovering it or purging it. For example, if you request to list keys in a key vault with 'Get-AzureKeyVaultKey -VaultName ContosoVault', the deleted key will not show up. To see deleted keys in a vault, you must use the '-InRemovedState' parameter.
Note: When you delete a key in a vault with soft-delete enabled it may take a while (a few seconds, usually) for the transition to complete; during this interval, it may appear that the key is in neither the active state, nor the deleted one – i.e. listing the key, with or without the -InRemovedState parameter, will return an empty list.
This command will list all deleted keys in 'ContosoVault'.
Get-AzureKeyVaultKey -VaultName ContosoVault -InRemovedState
Vault Name : ContosoVault
Name : ContosoFirstKey
Id : https://ContosoVault.vault.azure.net:443/keys/ContosoFirstKey
Deleted Date : 2/14/2017 8:20:52 PM
Scheduled Purge Date : 5/15/2017 8:20:52 PM
Enabled : True
Expires :
Not Before :
Created : 2/14/2017 8:16:07 PM
Updated : 2/14/2017 8:16:07 PM
Tags :
Just like vaults, a deleted key or secret will remain in deleted state for up to 90 days unless you recover it or purge it. 'Scheduled Purge Date' field indicates when a key will be permanently deleted, if no action is taken.
Here is how you would recover a deleted key:
Undo-AzureKeyVaultKeyRemoval -VaultName ContosoVault -Name ContosoFirstKey
To permanently delete a key, run the following cmdlet:
Remove-AzureKeyVaultKey -VaultName ContosoVault -Name ContosoFirstKey -InRemovedState
The 'recover' and 'purge' actions have their own permissions associated in key vault access policy. For a user or service principal to be able to execute a 'recover' or 'purge' action they must have the respective permission for that object (key or secret) in the key vault access policy. By default, 'purge' permission is not added to a vault's access policy when 'all' shortcut is used to grant all permissions to a user. You must explicitly grant 'purge' permission. For example, following command grants user@contoso.com permission to perform several operations on keys in 'ContosoVault' including 'purge'.
Set-AzureRmKeyVaultAccessPolicy -VaultName ContosoVault -UserPrincipalName user@contoso.com -PermissionsToKeys get,create,delete,list,update,import,backup,restore,recover,purge
Note: If you have an existing vault, that you just enabled soft-delete, you may not have 'recover' and 'purge' permissions.
Similarly here are related commands for deleting, listing, recovering and purging secrets respectively.
Delete a secret named SQLPassword
Remove-AzureKeyVaultSecret -VaultName ContosoVault -name SQLPassword
List all deleted secrets in a key vault
Get-AzureKeyVaultSecret -VaultName ContosoVault -InRemovedState
Recover a secret in deleted state
Undo-AzureKeyVaultSecretRemoval -VaultName ContosoVault -Name SQLPAssword
Purge a secret in deleted state
Remove-AzureKeyVaultSecret -VaultName ContosoVault -InRemovedState -name SQLPassword
That's all folks!
We are eager to hear from you about soft-delete. So reach out to us and let us know what you think.
Comments are disabled, head over to the Azure Key Vault forum to discuss about this blog.