Create a virtual machine by retrieving the password stored in a Key Vault

When you need to pass a secure value such as a password during deployment, you can store that value as a secret in an Azure Stack key vault and reference it in the Azure Resource Manager templates. You do not need to manually enter the secret each time you deploy the resources, you can also specify which users or service principals can access the secret.

In this article, we walk you through the steps required to deploy a Windows virtual machine in Azure Stack by retrieving the password that is stored in a Key Vault. Therefore the password is never put in plain text in the template parameter file. You can use these steps either from the Azure Stack Development Kit, or from an external client if you are connected through VPN.


The following steps describe the process required to create a virtual machine by retrieving the password stored in a Key Vault:

  1. Create a Key Vault secret.
  2. Update the azuredeploy.parameters.json file.
  3. Deploy the template.

Create a Key Vault secret

The following script creates a key vault, and stores a password in the key vault as a secret. Use the -EnabledForDeployment parameter when you're creating the key vault. This parameter makes sure that the key vault can be referenced from Azure Resource Manager templates.

$vaultName = "contosovault"
$resourceGroup = "contosovaultrg"
$location = "local"
$secretName = "MySecret"

New-AzureRmResourceGroup `
  -Name $resourceGroup `
  -Location $location

New-AzureRmKeyVault `
  -VaultName $vaultName `
  -ResourceGroupName $resourceGroup `
  -Location $location

$secretValue = ConvertTo-SecureString -String '<Password for your virtual machine>' -AsPlainText -Force

Set-AzureKeyVaultSecret `
  -VaultName $vaultName `
  -Name $secretName `
  -SecretValue $secretValue

When you run the previous script, the output includes the secret URI. Make a note of this URI. You have to reference it in the Deploy Windows virtual machine with password in key vault template. Download the 101-vm-secure-password folder onto your development computer. This folder contains the azuredeploy.json and azuredeploy.parameters.json files, which you will need in the next steps.

Modify the azuredeploy.parameters.json file according to your environment values. The parameters of special interest are the vault name, the vault resource group, and the secret URI (as generated by the previous script). The following file is an example of a parameter file:

Update the azuredeploy.parameters.json file

Update the azuredeploy.parameters.json file with the KeyVault URI, secretName, adminUsername of the virtual machine values as per your environment. The following JSON file shows an example of the template parameters file:

    "$schema":  "",
    "contentVersion":  "",
    "parameters":  {
       "adminUsername":  {
         "value":  "demouser"
         "adminPassword":  {
           "reference":  {
              "keyVault":  {
                "id":  "/subscriptions/xxxxxx/resourceGroups/RgKvPwd/providers/Microsoft.KeyVault/vaults/KvPwd"
              "secretName":  "MySecret"
       "dnsLabelPrefix":  {
          "value":  "mydns123456"
        "windowsOSVersion":  {
          "value":  "2016-Datacenter"

Template deployment

Now deploy the template by using the following PowerShell script:

New-AzureRmResourceGroupDeployment `
  -Name KVPwdDeployment `
  -ResourceGroupName $resourceGroup `
  -TemplateFile "<Fully qualified path to the azuredeploy.json file>" `
  -TemplateParameterFile "<Fully qualified path to the azuredeploy.parameters.json file>"

When the template is deployed successfully, it results in the following output:

Deployment output

Next steps

Deploy a sample app with Key Vault

Deploy a VM with a Key Vault certificate