Azure Key Vault – Step by Step

NOTE: This post was updated on Nov 12 2015 to incorporate breaking changes introduced in the Azure PowerShell 1.0 release.

Welcome!

In our introductory blog post we covered the overall Key Vault model. Today we’re going to dive into the specifics of using it. If you’ve not read the prior post, please do so before proceeding with this one. In the below Sumedh and Amit, PMs on the Key Vault Team, will offer a guided walk through with far more depth.

Thanks for your support!

Dan (twitter) on behalf of the Azure Key Vault Team

Here is the Azure page: https://azure.microsoft.com/services/key-vault

We value your input so please take a moment to follow us , join our advisory board , send us private feedback ,and/or visit our forum

Hi, 

In this post we take you through how to create and manage a key vault. We start with the lifecycle of a key vault. Next, we illustrate it with a basic example with PowerShell. Finally we wrap up by showing how to use these building blocks to achieve the full scenario that Dan outlined in the previous post.

During this preview, the management interface for a key vault is Azure PowerShell. In this post, we will assume you have basic working knowledge of PowerShell. If you do not, you should still be able to follow the overall flow from the example below, even if not every detail.

Key Vault lifecycle

In the simplest case you create a key vault, and you are the only person doing all operations with the key vault. In other cases, there may be up to four sets of people and any number of applications performing different tasks on a key vault. We'll demonstrate here the four core roles that we've enabled:

1. Your usage of the Key Vault service begins with creating your own key vault. Do this using the cmdlet New-AzureRmKeyVault.

2. In all likelihood you created this key vault for one or more applications to use. You must register those applications in Azure Active Directory. You must also authorize them to use your vault. Do this using the cmdlet Set-AzureRmKeyVaultAccessPolicy.

Optional: To allow other users (say your team members) to add/remove keys to this key vault, authorize those users for those specific operations on your key vault. Do this also using the cmdlet Set-AzureRmKeyVaultAccessPolicy.

3. You, or the users you authorized, then add your secrets (e.g. passwords) and cryptographic keys to that key vault. Do this using the cmdlets Set-AzureKeyVaultSecret and Add-AzureKeyVaultKey respectively. For each secret or key that you add, you get a unique URI.

4. The application operator must configure applications to use the URI of your key vault (or of specific secrets or keys). The specific configuration steps are unique to each application; generally the application will provide you a place in their configuration to paste the URI of your key or secret.

5. Subsequently the application you authorized can use your key vault programmatically using the Key Vault REST API or Key Vault Client classes. The application can do the following:

• It can read or write secrets into your key vault, if it is authorized for those operations.
• It can use your keys by calling methods of the service such as decrypt or sign. The application cannot read (extract) your keys. This is because the Key Vault service performs the cryptographic operation on the application’s behalf.
• The application may also add, remove, or update keys in your key vault, if authorized for those specific operations, but this is less common.

6. (Coming soon) You, the key vault owner, or a delegate such as an auditor, will be able to monitor operations performed on your keys and secrets by retrieving a usage log from the Key Vault service.

7. At any point, you or your delegate can update values of an existing keys or secret. Do this using the cmdlet Add-AzureKeyVaultKey with the existing key name, or Set-AzureKeyVaultKey with the existing secret name.

8. When you are done using your keys and secrets, delete them using the cmdlets Remove-AzureKeyVaultKey and Remove-AzureKeyVaultSecret respectively.

9. At any point, you can de-authorize (revoke) users and applications from accessing your key vault, or authorize other users and applications. Do this using the cmdlets Remove-AzureRmKeyVaultAccessPolicy and Set-AzureRmKeyVaultAccessPolicy.

10. When you are done using the key vault, delete the entire key vault using the cmdlet Remove-AzureRmKeyvault.

The next section walks you through an example of these steps with screenshots.

Step-by-step instructions

• For step-by-step instructions to create your first key vault and authorize an application, see Getting Started with Key Vault.

• Download sample applications. Follow the instructions in README.md to configure these applications. You need Visual Studio 2012 or 2013 to compile these applications.

Example

This example shows a developer Derick at Trey Research creating a key vault, adding a key to that key vault, and running the sample application HelloKeyVault with that key vault. Derick is using the account his organization gave him (derick@treycorpusa.onmicrosoft.com) and he has a 30-day trial subscription to Azure, good enough to play with Azure.

Get an identity for the application

First things first -- everybody who uses key vaults, whether users or applications, needs to be registered in Azure Active Directory (Azure AD). Derick’s user account is already in Azure AD. But his application is not. So he registers his instance of the HelloKeyVault sample application in his organization's (treycorpusa.onmicrosoft.com) Azure AD directory . The next few screenshots show the standard application registration workflow for Azure AD. None of these steps are unique to Azure Key Vault.

Derick signs in to the Azure management portal, and selects ACTIVE DIRECTORY on the left.

He sees his organization’s directory, “Trey Corporation”. He clicks it. In that directory, he clicks the APPLICATIONS tab.

This page normally shows him the applications he has previously registered. In this case he has none. He clicks the ADD icon at the bottom.

In the dialog that comes up, he enters a name for his application 'DerickHelloKeyVault' and chooses the type WEB APPLICATION. He clicks the arrow at the bottom to go to the next screen.

It asks him for a couple of URIs. The sign-on URI is relevant if the application has a sign-on page for users. This sample application does not have one, so we can enter any value there. In the App ID URI, Derick enters a URI that is unique within his organization. The corresponding site does not need to exist, the URI is just a label that uniquely identifies the application in the organization’s directory.

Now that the application is added, he goes to the CONFIGURE TAB.

He scrolls down to find the application’s CLIENT ID, also known as App ID. He notes this down.

He also creates a new client secret that will be used by the application as a credential to sign in to Azure AD. In the portal this secret is called ‘keys’ – this has no relation to key vaults! He chooses an expiry of one year, clicks SAVE at the bottom. He notes down the generated secret, highlighted in the screen below.

At this point he has an identity and a credential for his application.

Create and configure a key vault

Let’s get back to key vaults. During this preview, the management interface to Azure Key Vault is Azure PowerShell. Derick installs the latest Azure PowerShell (1.0.1 or higher). He signs in, using the cmdlet Login-AzureRmAccount.

All Azure resources created via the Azure Resource Manager must be contained in resource groups. So Derick creates a new resource group called DerickDevRG to house the key vault he is going to create next.

Now he creates a new key vault called DerickKeyVault in West Europe. The “accessPolicies” section of the output shows the permissions. By default, Derick has permissions to create keys, delete keys, list keys, update keys, backup keys, restore keys, and get the public half of keys in this key vault. He also has permissions to do anything with secrets in this key vault.

Derick can authorize other users and applications. In this case he has created the key vault for himself, so he does not need to authorize any other users. He does need to authorize the instance of the HelloKeyVault application that he just registered in Azure AD. He does this as shown next. In the ServicePrincipalName parameter, he passes in the CLIENT ID that he noted down when registering the application in Azure AD. He grants this application permission to encrypt, decrypt, wrap, and unwrap with keys in the key vault. The Set-AzureRmKeyVaultAccessPolicy cmdlet runs silently (no output) if it runs successfully. Derick runs the 'Get-AzureRmKeyVault' command to confirm permissions.

Derick sees two sets of permissions. The first is for himself. The second is for his application, "DerickHelloKeyVault".

Finally, he adds a key. Since this is not a production deployment, he specifies a Destination of ‘Software’. This creates a software-protected key. Operations on software-protected keys happen on Azure VMs (as opposed to operations on HSM-protected keys, which happen on an HSM.)

Configure and run application

He downloads the Hello Key Vault sample application. In the app.config file he adds the URI of his key vault, and the CLIENT ID and secret that he noted down when he registered his application in Azure AD. He then compiles the application.

He runs the application. He specifies parameters ‘encrypt’ and ‘decrypt’. Doing this makes the Hello Key Vault execute only those operations against the vault. The application signs in to Azure AD, then uses that token to authenticate to Azure Key Vault.

The scenario from the first post

Now that you have seen the basic flow, let’s use the building blocks to stitch together the real-world business problem mentioned in the first post in this blog. In that scenario, Contoso discovered that their LOB application is not as secure as they thought. They decided to move all keys into a key vault, instead of being packaged with the application. Contoso outsources all development.

When the outsourced developers build and test the application, they follow exactly the steps shown above for Derick. They do this with subscriptions belonging to them. They register (the test instances of) their application in their own Azure AD tenant.

When the outsourced developers are done, Contoso’s IT department takes the application for a test drive. The difference is that Contoso’s IT now registers the application in Contoso’s Azure AD tenant. They also create a key vault in their own Azure subscription.

If this test drive succeeds, they decide to move the application to production. The difference in this step is:

• To reduce exposure to keys, Contoso's CSO Cecil is the one who creates a key vault. He does this in a subscription reserved for that class of assets.
• To meet his organization's compliance rules, Cecil creates an HSM-protected key. To do this he must created a Premium SKU key vault.

He authorizes the app. To keep this example simple, we show him authorizing Derick's instance of the app. In reality Cecil will insist on a new deployment in a subscription that is tightly controlled.

Cecil also adds an HSM-protected key.

Finally, he passes the URI of the key (or for some applications, the URI of the key vault) to the IT professional who is deploying the application. That application now is managed by the app operator, but at runtime uses the key vault created by the CSO. The keys in the key vault are out of sight for the application.

In closing

We showed the basic flow of creating a key vault, adding keys, and authorizing applications to use those keys. In an upcoming blog post, Sunil will show how to build on this to enable Transparent Data Encryption in SQL Server with keys in a key vault.

Keep watching this blog space. We will share updates as they come along.

We are looking forward to your feedback. Please take a moment to send us feedback and to join our advisory board. Your feedback is key (pun intended!) to making this service meet your needs in Azure!

Cheers,

Sumedh and Amit on behalf of the Azure Key Vault team.

Comments

• Anonymous
  January 01, 2003
  Hi JD, can you past this message into an email and send to azurekeyvault@microsoft.com. There are a few other paths we can suggest after a bit of back and forth.
• Anonymous
  January 09, 2015
  Sumedh,
  
  Thank you for the primer.
  
  I have been over all of the API docs (REST and C# library) and will be jumping into this first thing on Monday. I recently spun up a proof of concept document encryption service that individually encrypts documents by generating unique, one time use symmetric keys using Stefan Gordon's Azure Encryption Extensions (https://github.com/stefangordon/azure-encryption-extensions). Each document that is uploaded to the service is encrypted and stored in blob storage and then the newly generated key is stored in a separate storage account.
  
  When decryption is required, a call into the services by an authenticated service (resource owner bearer token) retrieves the key and blob and decrypts them.
  
  My biggest exposure is in the web.config where my storage keys are exposed and there is certainly an opportunity for storing them in secrets, but I was curious how I may be able to better leverage key vault for the encryption, and/or key wrapping.
  
  The files in question can reach up to 50MB in size.
  
  Any thoughts?
  
  Kind Regards,
  
  JD
• Anonymous
  January 10, 2015
  Dan,
  
  I found the team forums after leaving this comment. Amit and I have a dialog going here:https://social.msdn.microsoft.com/Forums/azure/en-US/e2969d03-e12d-4bfb-a127-41451e0defc7/key-vault-and-encryption?forum=AzureKeyVault
  
  Thanks,
  
  JD
• Anonymous
  January 12, 2015
  Welcome!
  In our first blog Azure Key Vault - Making the cloud safer , we introduced you to the Azure
• Anonymous
  January 17, 2015
  There are a lot of steps missing in here. If anyone has come here looking to get started should probably go herehttp://azure.microsoft.com/en-us/documentation/articles/key-vault-get-started/
  
  Rahul
  http://www.rahulpnath.com
• Anonymous
  September 24, 2015
  By Stephen Lewontin, Solution Architect
  In this week's post I'm going to look at a recently introduced