Some fun with Azure Key Vault REST API and HttpClient – Part 5

We have gone through 5 articles about Azure Key Vault REST API in which we explored the possibility of working with Azure Key Vault REST API, specific to Vault and Secret. We also realized just ‘a bit‘ about how unclear Key Vault REST API documentation is. There are a few obsolete information. Some are missing or unclear of parameters we need to pass to the request body.

As planned, this article will give you some information related to Azure Key Vault recovery generally at first. It will then provide some uses of REST API to work with backup/restore and recovery for Vault and Secret.

Keep track of the series:

Why Recovery?

When Azure Key Vault is used to store your credential, API key or database connection string, you put Azure Key Vault as an imperative key to application sustainability. Imagine if a vault is inaccessible, your application cannot initialize an SQL connection with its connection string. Another example is that inaccessible API key which results to failure of API request call. Most of the cases, when a system goes live, there is a disaster recovery plan. This plan is part of your service management plan and sometime is just to comply with corporate policy. Recovery is important because it ensures that your business keeps being operated with the application.

There are two main incident levels which triggers a recovery. First, it is when the entire Azure region is unavailable due to unpredictable or out-of-control events such as natural disaster or terrorism activities.When an outage like this happens, there is a failover triggered to a secondary region. Microsoft has no official information about the failover mechanism of Azure Key Vault. Perhaps your vault is replicated over to the secondary region. You also should not worry anything or take any action because the failover is automated.

This is the guidance of Azure Key Vault disaster recovery. This is quite helpful to get a bit about recovery if Azure region is unavailable.

Now, the second level of incident is very important. It is made by human mistake or deliberation. An accidentally trigger of Deletion event on a secret is considered a mistake. Or someone purposely deletes your vault because he wouldn’t like you. Such a deliberated action targets to devastating your reputation. Whatever it would be, you have to be aware and plan for a disaster.

Recovering a Vault

In Part 3, I mentioned about soft-delete feature in vault. If soft-delete is enabled in a vault, this vault and its components (e.g. key, secret or certificate) can be recovered in case the vault is accidentally deleted. Soft-delete feature cannot be enabled via Azure Portal. You need PowerShell, REST API or other SDKs to enable the feature. One interesting thing is that this vault is still stored in Azure Key Vault service and you cannot create a new vault using the same name of the deleted one.

For demonstration purpose, first, create a new vault. Remember to set true for enableSoftDelete property. Otherwise, listing deleted vault will return null.

Now, use DELETE method to delete a specified vault. Part 3 in the series showed you all the operations against vault so make sure you don’t miss the information.

..and list the deleted vault to make sure it is already deleted and now in the list. Below is the vault I just deleted.

Now, what do we need to do? The list of vault REST API has no operation or something so-called “Recover vault” right? You cannot create a new vault that has exactly the same configuration with the deleted one. But are allowed to let Azure know that the vault you are going to create is for recovery mode. To do this, you just only need to set createMode property to recover and also location. Pay attention to highlighted lines below:

The response body will contain details of your vault you just recover. No configuration is changed, including access policies, vault property (e.g. soft-delete feature..). This is all you need to do, it is super simple!

Backing up a secret

Backup secret can be done easy by using POST method. You just only need to specify secret name you need to back up. There is no request body request (can set null as an argument).

The backup contains a secret bundle including all versions.

Restoring a backup

Restoring a backup is to revert back to the state of backup. For example, you make some changes in the secret (e.g. expiration date or create a new version) and now you need to revert to the configuration in the backup. When restoring a backup, the new version will be removed. The very important thing to note is that you cannot restore a backup to an existing vault which has the same secret name. The location and subscription also must be the same with the backed secret.

You can store blob value in a blob file in Azure Storage and read from it. Or just paste the whole value to your string. The response body is as follows:

The result shows you that the backup only has one version. Restoration would be good when you have more than one environment. For example, you would like to migrate secrets from development vault to staging vault.

Recovering a secret

There might be a misunderstanding in recovery. Recovery is different from restoration. Recovery is needed when you accidentally delete your secret and you would like to recover that deleted secret. Restoration is when you would like to revert back to the state of backup. In Azure Key Vault, you cannot overwrite a backup to the same secret. It means you would need to restore to another vault.

To recover a secret, there is a couple of prerequisites:

  • Your vault to which the secret belongs must have soft-delete feature enabled.
  • recoveryLevel property in your secret must set Recoverable. When creating or updating a secret, you can set this property.

Here is the sample code. Pay attention to the highlighted URL request.


This article just showed you some demonstrations about recovery of vault and secret in Azure Key Vault. With recovery, you can recover a deleted vault in case you accidentally delete that vault. The deleted vault must enable soft-delete feature before being recovered.

Backup and restoration is used in different scenario. Backup is to keep the designated state of your secret including its version. When you want to migrate to another vault, or just want to revert to a temporary vault before restoring back to the original one, use restoration approach. While recovery can recover the entirely vault, restoration can only restore the backup and work in secret, key or certificate scope.


Leave a Reply

© 2018 The Soldier of Fortune.