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

After two articles doing some fun with Azure Key Vault REST API and HttpClient, I’ve got some requests to add more things to work with vault, for example listing all existing vaults under a given subscription, or deleting a vault.

In this article, let’s explore all the operations which you can work through Azure Key Vault REST API for Vault.

Keep track of the series:

Prerequisites

For the sake of quick overview, there are some prerequisites you need before moving to the main method. First, you need to get access token before making a request to resource.There are two main resource endpoints depending on vault operation:

  • Azure Resource Management REST API endpoint: it is https://management.azure.com. This is the REST API endpoint if you want to perform operation against Azure resource, for example creating a new Azure Key Vault resource.
  • Vault REST API endpoint: it is https://vault.azure.net. It is used when you want to work against components (secret, key) under a specific vault.
  • Base Azure AD variable: this includes tenant ID, client, ID and client secret. Note that client secret is not necessary today. It’d be good to subscribe my blog for further articles using other approaches.
  • Subscription variable: this includes subscription ID of the subscription you want to play with, and other variables such as location, resource group name or so on.
  • Vault variable: along with environment variables, this contains vault name and other components for the use with REST API.
  • API version: this is very important. If you specify wrong API version, chances are you will get Bad Request 400. The API version for Azure Key Vault REST API can be found here. If you target to Azure Resource REST API, don’t rely on Azure Key Vault REST API. See the below error in List operation to get more information.
  • Acces policy: your service principal must have permission depending on operation you want to perform.

For configuration management, you can use System.Configuration.ConfigurationManager Nuget package. Since we use Azure, it’d be better to go with Microsoft.WindowsAzure.ConfigurationManager.

List all vaults in a subscription

Azure allows you to list all vaults in a specified subscription with GET method. There is not any request body required for the call. There are the following parameters to be directly passed along with URI:

  • subscriptionId: your subscription ID
  • $filter: used to query Key Vault resource only.
  • $top: specify number of results to return. This is optional.
  • api-version: because we make a request against Azure Resource Management REST API, don’t use the 2016-10-01 specified in this article.

Here is the sample code:

The response body returns as follows:

Note: as said, do not rely on the API version described in this article. It would be invalid to use with Azure Resource REST API.  Unless, you will receive Bad Request when calling. Below is the error message

Getting a vault 

Getting a vault means that you retrieve specifications of a specific vault under your subscription using GET method. There are the following parameters to be directly passed along with URI:

  • subscriptionId: your subscription ID
  • resourceGroupName: the resource group name to which the given vault belongs
  • vaultName: name of the vault you want to check
  • api-version: use 2016-10-01 as latest version.

Here is sample code

Interestingly, the API version for the the provider type of vault is 2016-10-01 as latest. Below is the return of response body which contains parameters you set in Part 1.

Deleting a vault

Deleting a vault is similar to getting a vault. The only difference is the method which is DELETE. Thus, we use DeleteAsync()

The response body only returns status code 200 when a DELETE request is made successfully.

Listing deleted vaults

For investigation, you would need to retrieve the list of vaults you have deleted. Azure allows you to do so with GET method. But you cannot get all deleted vault resources without soft-delete enabled. Azure Key Vault uses a feature named soft-delete that aims to recovery scenario for vault. When you perform DELETE request, you are no longer have an access to that vault if this vault has no soft-delete feature enabled. If you don’t set it before a vault is deleted, the return of List deleted vaults operation always be null.

More information about Azure Key Vault soft-delete feature, read here

Soft-delete feature can be enabled via REST during the provisioning of your vault which was full documented in Part 1. In the request body, just simply set:

One of the other ways to set this property is PowerShell:

Here is the sample code to retrieve deleted vaults:

And the response body returns as follows:

There are a couple of notes:

  • A vault which has soft-delete enabled is not really deleted. This means this still exists and you cannot create a new vault with the same name.
  • You cannot enable soft-delete feature via Azure Portal.

Getting a deleted vault

You can get a specific deleted vault in a specified location and vault name. The required parameters include location and vault name

The request body is similar to the one when listing deleted vaults, but contains one vault object.

Updating a vault

Update is needed if you want to re-configure access policy, or enable soft-delete feature for example, which you cannot complete via Azure Portal. There are two ways according Microsoft guidance on Azure Key Vault REST API to update a vault: PUT and PATCH. PATCH ( PathAsync() ) is not a built-in method in HttpClient, you have to write a dedicated extension method.

Remember PUT can be used to create a new vault, we can still use it to update. You just simple prepare the request body which contains all the specifications, including the existing one.

Updating access policy

Although access policy can be updated by PUT method we discussed earlier, Azure allows you to only update access policy. Along with request body containing access policy, you need the following URI parameters:

  • subscriptionId: your subscription ID
  • resourceGroupName: resource group name which the target vault belongs to
  • vaultName: name of the vault you want to update its access policy
  • operationKind: specify name of the operation: add, remove or replace.
  • api-version: uses 2016-10-01

Here is the sample code

Make sure you understand each operation to not make the application downtime. Add can be used to append new access policy which is considered a safe approach.

Purging deleted vault

A retention period of a deleted vault which has soft-delete feature enabled is 90 days. The scheduledPurgeDate property in response body tells you the retention. After 90 days from deletion date, Azure will permanently delete the vault and you will no longer have an access to the vault and its components.

In some cases, you don’t want to keep your deleted vault within the retention period, you can purge it. When purging, that deleted vault will be immediately removed out of Azure store.

Along with request body containing access policy, you need the following URI parameters:

  • subscriptionId: your subscription ID
  • location: the location of the deleted vault.
  • vaultName: name of the vault you want to update its access policy
  • api-version: uses 2016-10-01

Purging a specified deleted vault requires POST method without any Http content. You can set null in the request parameter. Here is the sample code

The response body only returns status code 202 Accepted. It means the specified deleted vault is being purged. Once it is completely purged, you can create a new vault using the same name. Once again, if the soft-delete deleted vault has not been purged, you cannot create a new vault using that deleted vault’s name.

Conclusion

This article shows you different operations against vault in Azure Key Vault service by HttpClient and REST API. During demonstration, you have gained some basic knowledge of Azure Key Vault, as well as some important notes. Sample code is publicly accessible from here.

Checking availability of vault name and creating a new vault are documented in Part 1.

Although, Microsoft has documented poorly for Azure Key Vault REST API for vault, it’s worth referring:

OperationDescriptionMethodapi-versionNote
Check Name AvailabilityChecks that the vault name is valid and is not already in usePOST2016-10-01Make sure request body is in form of Http content.
CreateCreate a key vault in a specified subscriptionPUT2016-10-01Request body format must be valid
UpdateUpdate specifications of an existing key vault in a specified subscriptionPUT2016-10-01Similar to Create operation
UpdateUpdate specifications of an existing key vault in a specified subscriptionPATCH2016-10-01Not yet tested
DeleteDelete a key vaultDELETE2016-10-01It is no longer retrievable if not setting soft-delete feature.
GetGet a specified key vaultGET2016-10-01N/A
Get Deleted Gets a deleted key vault.GET2016-10-01Can only get deleted vault that enables soft-delete feature.
ListGet all vaults associated to a specified subscriptionGET2018-01-01api-version is not 2016-10-01
List By Resource GroupGet all vaults in a specified subscription within a resource groupGET2018-01-01Similar to List operation
List By SubscriptionGet all vaults associated to a specific subscriptionGET2018-01-01Similar to List operation, without resource group specified in URI parameter
List DeletedGet all deleted vaults in a specified subscriptionGET2016-10-01Can only get deleted vaults that enables soft-delete feature.
Purge DeletedPermanently purge a deleted vault POST2016-10-01Http content can be null. Only purge deleted vaults that enable soft-delete feature
Update Access PolicyUpdate access policy of a vault PUT2016-10-01Only prepare access policy in request body. Use Add to append policy safely.

Comments

Leave a Reply

© 2018 The Soldier of Fortune.