We live in a world where data and security is not to be taken lightly. Having to create or maintain a system that enable you to keep secrets and/or certificates safe is a challenge in itself. In this particular article we'll see how to refer and inject the value of a secret kept in Azure Key Vault in an ARM template.

Prerequisites

  • Azure PowerShell cmdlets v1.0.4 or later
  • an existing Azure Key Vault with at least one secret with proper permissions.

If you need help creating an Azure Key Vault, see the In this series section for related information.

Referencing secrets in an ARM template

The first thing you need is the ID of your key vault. In the previous article we created a Key Vault named MyUniqueKeyVaultName and a secret with the name MyAdminPassword, we'll continue to use these values in this article.

To get the ID of your vault, you can do something like this in PowerShell (replace the value for the VaultName parameter with yours)

(Get-AzureRmKeyVault -VaultName MyUniqueKeyVaultName).ResourceId

If should return a string with a format like this:
/subscriptions/edf192ff-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/AzureKeyVaultDemo/providers/Microsoft.KeyVault/va ults/MyUniqueKeyVaultName

Now we need to instruct the engine that we want to refer a key vault secret. The following syntax will enable us to do so:

  "reference": {
    "keyVault": {
      "id": "/subscriptions/edf192ff-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/AzureKeyVaultDemo/providers/Microsoft.KeyVault/vaults/MyUniqueKeyVaultName"
    },
    "secretName": "MyAdminPassword"
  }

Using this syntax, you specify the id of the key vault to use and which secret value you're after.

At runtime, ARM will replace all the key vault references with the actual secret values.

Parameters

If you want the value of a secret to be passed to a template parameter, you can either create a new one or use an existing one but declare it as securestring. It is a secret after all and this is the proper way to to let Azure know that this is sensitive information. Special care are took by the platform when handling securestrings. In short, they will not travel as plain text and won't be shown in the portal and deployment logs.

Here is a very basic example for a template, it do not create anything but you'll see how to declare your parameter as securestring.


{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "myAdminUsername": {
      "type": "string",
      "minLength": 4
    },
    "myAdminPassword": {
      "type": "securestring"
    }
  },
  "resources": [
  ],
  "outputs": {
    "password": {
      "type": "securestring",
      "value": "[parameters('myAdminPassword')]"
    }
  }
}

I have also created an output named password to show you that you can use your parameter like any others in your template.

In your parameters file, use the reference syntax we saw earlier:

{
  "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "myAdminUsername": {
      "value": "MyAdministrator"
    },
    "myAdminPassword": {
      "reference": {
        "keyVault": {
          "id": "/subscriptions/edf192ff-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/AzureKeyVaultDemo/providers/Microsoft.KeyVault/vaults/MyUniqueKeyVaultName"
        },
        "secretName": "MyAdminPassword"
      }
    }
  }
}

Here is the output when I deploy this parameter
After Key Vault reference in parameters deployment execution

Debugging tips: Changing the type securestring to string in the output section, it will enable you to see the value in clear text. If you do this, switch it back to a securestring immediately after. You put that information in a secure vault in the first time, it is certainly not to let exposed in the wild later on ;)

Variables

Referring key vault in a variable is not supported at the moment, let's cross our fingers this is coming soon.

In this series

References